edytor 0.1.0-next.21 → 0.1.0-next.23

package/dist/cloudflare/index.d.ts

@@ -4,5 +4,5 @@
  * `cloudflare:workers`); built on the Worker-safe CRDT entry. Documented in
  * the site's `server/` section (room, authorization, extending, protocol).
  */
-export { DocumentRoom, AttachedDocument, attachDocument, SOCKET_TAG, closedSocket, type AttachDocumentOptions, DEFAULT_COMPACT_AFTER, DEFAULT_MAX_ROW_BYTES, DEFAULT_SAVE_AFTER, MAX_REFUSALS, MAX_WAITING_DELETES, ROOM_ORIGIN, IDENTITY_HEADERS, noTimers, type Attachment, type DocumentRoomEnv, type LoadedDocument, type Refusal, type ReplicaOwner, type SavedDocument, type SocketIdentity } from './DocumentRoom.js';
+export { DocumentRoom, AttachedDocument, attachDocument, SOCKET_TAG, closedSocket, type AttachDocumentOptions, DEFAULT_COMPACT_AFTER, DEFAULT_MAX_ROW_BYTES, DEFAULT_SAVE_AFTER, DEFAULT_MAX_DOCUMENT_BYTES, DEFAULT_MAX_INBOUND_FRAME_BYTES, DEFAULT_MAX_UPDATES_PER_SECOND, MAX_REFUSALS, MAX_WAITING_DELETES, ROOM_ORIGIN, IDENTITY_HEADERS, PROBE_HEADER, noTimers, type Attachment, type DocumentRoomEnv, type LoadedDocument, type Refusal, type ReplicaOwner, type SavedDocument, type SocketIdentity, type StoredRecord, type FrameValidation, type ValidatedBlock, type RoomMetrics, type RoomLogEntry, type Timing } from './DocumentRoom.js';
 export { routeDocumentSocket, requestedReplica, type AuthorizeDocumentSocket, type ExpiredCredential, type DocumentNamespace, type DocumentIdentity } from './routeDocumentSocket.js';

package/dist/cloudflare/index.js

@@ -4,5 +4,5 @@
  * `cloudflare:workers`); built on the Worker-safe CRDT entry. Documented in
  * the site's `server/` section (room, authorization, extending, protocol).
  */
-export { DocumentRoom, AttachedDocument, attachDocument, SOCKET_TAG, closedSocket, DEFAULT_COMPACT_AFTER, DEFAULT_MAX_ROW_BYTES, DEFAULT_SAVE_AFTER, MAX_REFUSALS, MAX_WAITING_DELETES, ROOM_ORIGIN, IDENTITY_HEADERS, noTimers } from './DocumentRoom.js';
+export { DocumentRoom, AttachedDocument, attachDocument, SOCKET_TAG, closedSocket, DEFAULT_COMPACT_AFTER, DEFAULT_MAX_ROW_BYTES, DEFAULT_SAVE_AFTER, DEFAULT_MAX_DOCUMENT_BYTES, DEFAULT_MAX_INBOUND_FRAME_BYTES, DEFAULT_MAX_UPDATES_PER_SECOND, MAX_REFUSALS, MAX_WAITING_DELETES, ROOM_ORIGIN, IDENTITY_HEADERS, PROBE_HEADER, noTimers } from './DocumentRoom.js';
 export { routeDocumentSocket, requestedReplica } from './routeDocumentSocket.js';

package/dist/cloudflare/routeDocumentSocket.js

@@ -13,21 +13,42 @@
  * with its `params` read again, so a refreshed token gets in. A document
  * id the room cannot have (`validRoomId`: empty, `.` or `..`, over 256
  * characters, with a lone surrogate) is closed `4400`.
+ *
+ * A plain `GET <room>?lastUpdated` (no upgrade) is the room's probe (H12):
+ * authorized the same way, it answers `{ lastUpdated }` as JSON (the room's
+ * last stored change, ms since the epoch, or `null`), or `400`, `401` or
+ * `403` as an HTTP status.
  */
 import { CLOSE, validRoomId } from '../crdt/providers/room.js';
-import { IDENTITY_HEADERS, closedSocket, parseReplica } from './DocumentRoom.js';
+import { IDENTITY_HEADERS, PROBE_HEADER, closedSocket, parseReplica } from './DocumentRoom.js';
+/** The HTTP status a `lastUpdated` probe gets for each refusal a dial is closed with. */
+const PROBE_STATUS = {
+    [CLOSE.invalidDocument]: 400,
+    [CLOSE.expired]: 401,
+    [CLOSE.denied]: 403
+};
 /** The replica a client asked for in `?replica=<doc.clientID>` (or `param`), or `null`. */
 export const requestedReplica = (request, param = 'replica') => parseReplica(new URL(request.url).searchParams.get(param));
 export async function routeDocumentSocket(request, rooms, documentId, authorize) {
-    if (request.method !== 'GET' || request.headers.get('Upgrade')?.toLowerCase() !== 'websocket') {
+    // The `lastUpdated` probe (H12): a plain GET, authorized like a dial,
+    // answered with JSON (`{ lastUpdated }`) or an HTTP status.
+    const probe = request.method === 'GET' &&
+        request.headers.get('Upgrade') === null &&
+        new URL(request.url).searchParams.has('lastUpdated');
+    if (!probe &&
+        (request.method !== 'GET' || request.headers.get('Upgrade')?.toLowerCase() !== 'websocket')) {
         return new Response('WebSocket upgrade required', { status: 426 });
     }
+    // One refusal path: a dial gets the close the provider reads, a probe its HTTP status.
+    const refuse = (code, reason) => probe
+        ? new Response(reason, { status: PROBE_STATUS[code] ?? 403 })
+        : closedSocket(code, reason);
     if (!validRoomId(documentId)) {
-        return closedSocket(CLOSE.invalidDocument, 'invalid document id');
+        return refuse(CLOSE.invalidDocument, 'invalid document id');
     }
     const decision = await authorize(request, documentId);
     if (decision && 'expired' in decision && decision.expired === true) {
-        return closedSocket(CLOSE.expired, 'expired');
+        return refuse(CLOSE.expired, 'expired');
     }
     const identity = decision && 'userId' in decision ? decision : null;
     const replica = identity?.replica ?? null;
@@ -38,13 +59,16 @@ export async function routeDocumentSocket(request, rooms, documentId, authorize)
         // No header, even percent-encoded, carries a lone surrogate.
         /\p{Cs}/u.test(identity.userId) ||
         (replica !== null && parseReplica(replica) === null)) {
-        return closedSocket(CLOSE.denied, 'document access denied');
+        return refuse(CLOSE.denied, 'document access denied');
     }
     const headers = new Headers({
-        Upgrade: 'websocket',
         [IDENTITY_HEADERS.user]: encodeURIComponent(identity.userId),
         [IDENTITY_HEADERS.access]: identity.readOnly ? 'read' : 'write'
     });
+    if (probe)
+        headers.set(PROBE_HEADER, 'lastUpdated');
+    else
+        headers.set('Upgrade', 'websocket');
     if (replica !== null)
         headers.set(IDENTITY_HEADERS.replica, String(replica));
     return rooms.getByName(documentId).fetch(new Request(request.url, { method: 'GET', headers }));

package/dist/collaboration/awarenessSelection.d.ts

@@ -68,10 +68,16 @@ export declare const mintPresenceKey: () => string;
 export declare const publishPresence: (awareness: AwarenessLike, key: string, payload: PresenceSelection | null) => boolean;
 /** What a view shares of its selection: the selection itself, the block holding its focus, or nothing. */
 export type PresenceShare = 'caret' | 'block' | 'none';
+/**
+ * The least ms between two presence writes of a view by default (P9): a
+ * caret held down or a drag publishes about 20 writes a second instead of
+ * one per selection change, which every peer and the room relay.
+ */
+export declare const DEFAULT_PRESENCE_THROTTLE = 50;
 export type PresenceOptions = {
     /** `'caret'` (default): the selection; `'block'`: the focused block only, so moving inside it publishes nothing; `'none'`: nothing. */
     share?: PresenceShare;
-    /** Minimum ms between two presence writes (default `0`). The first goes at once; later ones collapse into one write of the newest at the window's end. */
+    /** Minimum ms between two presence writes (default {@link DEFAULT_PRESENCE_THROTTLE}, 50; `0`: every change). The first goes at once; later ones collapse into one write of the newest at the window's end. */
     throttle?: number;
 };
 /**

package/dist/collaboration/awarenessSelection.js

@@ -28,6 +28,12 @@ export const publishPresence = (awareness, key, payload) => {
     awareness.setLocalState(Object.keys(next).length > 0 ? { ...state, selections: next } : state);
     return true;
 };
+/**
+ * The least ms between two presence writes of a view by default (P9): a
+ * caret held down or a drag publishes about 20 writes a second instead of
+ * one per selection change, which every peer and the room relay.
+ */
+export const DEFAULT_PRESENCE_THROTTLE = 50;
 /**
  * One view's presence writer (R1): the only writer of its key, under the
  * view's `share` and `throttle`. `select()` hands it the full payload; the
@@ -44,7 +50,7 @@ export class PresenceWriter {
     #held;
     /** The last payload and focused block handed in, kept so a share change republishes at once. */
     #latest = [null, null];
-    constructor(awareness, key, { share = 'caret', throttle = 0 } = {}) {
+    constructor(awareness, key, { share = 'caret', throttle = DEFAULT_PRESENCE_THROTTLE } = {}) {
         this.awareness = awareness;
         this.key = key;
         this.#share = share;

package/dist/collaboration/index.d.ts

@@ -1,3 +1,3 @@
-export { freshestPublishedSelection, publishPresence, PresenceWriter, type PresenceOptions, type PresenceShare, type EdytorAwarenessSelection, type EdytorAwarenessState, type EdytorAwarenessUser, type EdytorAwarenessViewSelection } from './awarenessSelection.js';
+export { freshestPublishedSelection, publishPresence, PresenceWriter, DEFAULT_PRESENCE_THROTTLE, type PresenceOptions, type PresenceShare, type EdytorAwarenessSelection, type EdytorAwarenessState, type EdytorAwarenessUser, type EdytorAwarenessViewSelection } from './awarenessSelection.js';
 export { whenDocumentReady } from './documentSync.js';
-export { createIndexeddbSync, createWebsocketSync, clearDocument, IndexeddbPersistence, storeState, WebsocketProvider, type EdytorSync, type EdytorSyncCleanup, type EdytorSyncPayload, type IndexeddbSyncOptions, type WebsocketSync, type WebsocketSyncOptions } from './providers.js';
+export { createIndexeddbSync, createWebsocketSync, clearDocument, IndexeddbPersistence, storeState, WebsocketProvider, prefetch, lastUpdated, type EdytorSync, type EdytorSyncCleanup, type EdytorSyncPayload, type IndexeddbSyncOptions, type WebsocketSync, type WebsocketSyncOptions } from './providers.js';

package/dist/collaboration/index.js

@@ -1,3 +1,3 @@
-export { freshestPublishedSelection, publishPresence, PresenceWriter } from './awarenessSelection.js';
+export { freshestPublishedSelection, publishPresence, PresenceWriter, DEFAULT_PRESENCE_THROTTLE } from './awarenessSelection.js';
 export { whenDocumentReady } from './documentSync.js';
-export { createIndexeddbSync, createWebsocketSync, clearDocument, IndexeddbPersistence, storeState, WebsocketProvider } from './providers.js';
+export { createIndexeddbSync, createWebsocketSync, clearDocument, IndexeddbPersistence, storeState, WebsocketProvider, prefetch, lastUpdated } from './providers.js';

package/dist/collaboration/providers.d.ts

@@ -11,3 +11,7 @@ export declare const clearDocument: ProviderStack['clearDocument'];
 export declare const storeState: ProviderStack['storeState'];
 export declare const IndexeddbPersistence: ProviderStack['IndexeddbPersistence'];
 export declare const WebsocketProvider: ProviderStack['WebsocketProvider'];
+/** Keep a document's local copy fresh without opening it (sync once, then close). */
+export declare const prefetch: ProviderStack['prefetch'];
+/** When a room last stored a change: one authorized HTTP request, no document opened. */
+export declare const lastUpdated: ProviderStack['lastUpdated'];

package/dist/collaboration/providers.js

@@ -19,3 +19,7 @@ export const clearDocument = providers.clearDocument;
 export const storeState = providers.storeState;
 export const IndexeddbPersistence = providers.IndexeddbPersistence;
 export const WebsocketProvider = providers.WebsocketProvider;
+/** Keep a document's local copy fresh without opening it (sync once, then close). */
+export const prefetch = providers.prefetch;
+/** When a room last stored a change: one authorized HTTP request, no document opened. */
+export const lastUpdated = providers.lastUpdated;

package/dist/components/Edytor.svelte

@@ -12,7 +12,10 @@
 	} from '../crdt/index.js';
 	import { CLOSE, validRoomId } from '../crdt/providers/room.js';
 	import type { EdytorSync, WebsocketSyncOptions } from '../collaboration/index.js';
-	import type { PresenceOptions } from '../collaboration/awarenessSelection.js';
+	import {
+		DEFAULT_PRESENCE_THROTTLE,
+		type PresenceOptions
+	} from '../collaboration/awarenessSelection.js';
 	import { createIndexeddbSync, createWebsocketSync } from '../collaboration/providers.js';
 	export { EdytorClass as EdytorContext, useEdytor };
 	import type { Placeholder, Plugin } from '../plugins.js';
@@ -138,6 +141,13 @@
 		onSyncRefused?: (refusal: SyncRefusedError) => void;
 		/** Advanced: a custom sync factory. Overrides `room`/`server`. */
 		sync?: EdytorSync;
+		/**
+		 * Keep the view read-only, and seed nothing, until its document was
+		 * fetched once (a provider synced): a first visit offline shows no
+		 * `value` that the room's content would later duplicate. For the
+		 * document this view owns (with `document`, set it there). Read once.
+		 */
+		requireHydration?: boolean;
 	};
 </script>
 
@@ -167,6 +177,7 @@
 		params,
 		onSyncExpired,
 		onSyncRefused,
+		requireHydration,
 		awareness,
 		actor,
 		presence,
@@ -194,6 +205,7 @@
 		doc,
 		awareness,
 		actor,
+		requireHydration,
 		hotKeys,
 		onSelectionChange,
 		onChange,
@@ -273,7 +285,7 @@
 		edytor.readonly = readonly;
 	});
 	$effect(() => {
-		edytor.presence.throttle = presence?.throttle ?? 0;
+		edytor.presence.throttle = presence?.throttle ?? DEFAULT_PRESENCE_THROTTLE;
 		edytor.presence.share = presence?.share ?? 'caret';
 	});
 	// A readonly change shows or hides chrome: the overlay repositions it.

package/dist/components/Edytor.svelte.d.ts

@@ -1,7 +1,7 @@
 import { Edytor as EdytorClass, useEdytor, type Snippets } from '../edytor.svelte.js';
 import { SyncRefusedError, type Awareness, type DocumentActor, type EdytorDocument, type YDoc } from '../crdt/index.js';
 import type { EdytorSync, WebsocketSyncOptions } from '../collaboration/index.js';
-import type { PresenceOptions } from '../collaboration/awarenessSelection.js';
+import { type PresenceOptions } from '../collaboration/awarenessSelection.js';
 export { EdytorClass as EdytorContext, useEdytor };
 import type { Placeholder, Plugin } from '../plugins.js';
 import { type BlockHandlesOptions } from '../plugins/blockHandles/blockHandlesPlugin.js';
@@ -68,6 +68,13 @@ export type EdytorProps = Snippets & {
     onSyncRefused?: (refusal: SyncRefusedError) => void;
     /** Advanced: a custom sync factory. Overrides `room`/`server`. */
     sync?: EdytorSync;
+    /**
+     * Keep the view read-only, and seed nothing, until its document was
+     * fetched once (a provider synced): a first visit offline shows no
+     * `value` that the room's content would later duplicate. For the
+     * document this view owns (with `document`, set it there). Read once.
+     */
+    requireHydration?: boolean;
 };
 import type { JSONBlock, JSONDoc } from '../utils/json.js';
 import type { HotKey, HotKeyCombination } from '../session/keymap.js';

package/dist/crdt/admission.d.ts

@@ -137,5 +137,10 @@ export declare const bindAdmission: (Y: EngineApi) => {
      * Throws {@link UndecodableUpdateError} for payloads that fail to
      * decode/integrate at all, then the usual typed refusals.
      */
-    admitUpdate: (update: Uint8Array, docName?: string) => YDoc;
+    admitUpdate: (update: Uint8Array | ReadonlyArray<Uint8Array | {
+        v2: Uint8Array;
+    }>, docName?: string, options?: {
+        /** Prepare the scratch doc before anything is applied (e.g. its `gcFilter`). */
+        prepare?: (doc: YDoc) => void;
+    }) => YDoc;
 };

package/dist/crdt/admission.js

@@ -133,10 +133,17 @@ export const bindAdmission = (Y) => ({
      * Throws {@link UndecodableUpdateError} for payloads that fail to
      * decode/integrate at all, then the usual typed refusals.
      */
-    admitUpdate: (update, docName = 'loaded document') => {
+    admitUpdate: (update, docName = 'loaded document', options = {}) => {
         const doc = new Y.Doc();
+        options.prepare?.(doc);
+        const apply = (part) => part instanceof Uint8Array ? Y.applyUpdate(doc, part) : Y.applyUpdateV2(doc, part.v2);
         try {
-            Y.applyUpdate(doc, update);
+            // Several updates (`{ v2 }`: in the v2 encoding) are applied in one
+            // transaction, with no merge pass.
+            if (update instanceof Uint8Array)
+                apply(update);
+            else
+                Y.transact(doc, () => update.forEach(apply));
         }
         catch (cause) {
             throw new UndecodableUpdateError(docName, cause);

package/dist/crdt/data.d.ts

@@ -57,6 +57,8 @@ export declare const keySegment: (k: string) => string;
 export declare const segmentKey: (s: string) => string;
 /** A new node's data, as leaves. */
 export declare const dataLeaves: (data: unknown) => Map<string, unknown>;
+/** A path of the data as a leaf key (`d/` and its pointer). */
+export declare const leafKey: (path: readonly string[]) => string;
 /** `node`'s data (`undefined` when it has none). */
 export declare const readData: (node: EngineNode) => JsonObj | undefined;
 /**
@@ -75,7 +77,7 @@ export declare const applyPatch: (data: JsonObj, patches: readonly DataPatch[])
  * they still read as the patched value, else it is exploded: every leaf
  * written, the attr deleted. An unchanged value writes nothing.
  */
-export declare const patchWrites: (node: EngineNode, patches: readonly DataPatch[], client?: number, rand?: () => number) => LeafWrite[] | null;
+export declare const patchWrites: (node: EngineNode, patches: readonly DataPatch[], client?: number, rand?: () => number, atomic?: readonly string[]) => LeafWrite[] | null;
 /** Write `writes` on `node` (a detached one too: a block or atom being created). */
 export declare const writeLeaves: (node: EngineNode, writes: Iterable<LeafWrite>) => void;
 export {};

package/dist/crdt/data.js

@@ -1,5 +1,5 @@
 import { DATA, DATA_LEAF_PREFIX } from './schema.js';
-import { decodeRank, encodeRank, rankBetween } from './placement/rank.js';
+import { rankAfter } from './placement/rank.js';
 import { hash32 } from './rand.js';
 import { jsonEquals } from '../utils/json.js';
 export const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -17,13 +17,6 @@ export const keySegment = (k) => (k.startsWith('~') ? `~0${k.slice(1)}` : k);
 export const segmentKey = (s) => (s.startsWith('~0') ? `~${s.slice(2)}` : s);
 const RANK = /^(?:[-\w]{16})+$/;
 const index = (k) => (/^(0|[1-9]\d*)$/.test(k) ? Number(k) : -1);
-/**
- * The digit that opens a client's run after an item it made (`between`):
- * below every digit a plain insert extends a rank with (`0`, a gap's), so
- * the run sorts right after its item, and far above the digit minimum, so
- * the inserts before it (each one digit lower) never run out of room.
- */
-const RUN = -(2 ** 39);
 const rank = (v) => (typeof v === 'string' && RANK.test(v) ? v : undefined);
 /** Item `id`'s place: where a move put it (`id>`), else where it was made (`id#`). */
 const placeOf = (t, id) => rank(t.k.get(`${id}>`)?.v) ?? rank(t.k.get(`${id}#`)?.v);
@@ -103,28 +96,11 @@ const edits = (rand, client = 0) => {
     const remove = (t, id) => [id, `${id}#`, `${id}>`].forEach((s) => t.k.delete(s));
     /**
      * A rank in `(left, right)`. After an item this client placed, it is in
-     * the client's run there (`left`, the `RUN` segment, then ranks of its
-     * own): what it inserts after its own items stays together, as `Y.Array`
-     * keeps an insert after its origin, whatever a peer inserts in that gap
-     * meanwhile. Elsewhere a plain rank between the two.
+     * the client's run there (`rankAfter`): what it inserts after its own
+     * items stays together, as `Y.Array` keeps an insert after its origin,
+     * whatever a peer inserts in that gap meanwhile. Elsewhere a plain rank.
      */
-    const between = (left, right) => {
-        const plain = () => rankBetween(left, right, client, pick);
-        if (left === undefined)
-            return plain();
-        const segs = decodeRank(left);
-        const k = segs.findLastIndex((g) => g.v === RUN);
-        const run = k >= 0 && segs[k].t === client
-            ? encodeRank(segs.slice(0, k + 1))
-            : segs.at(-1).t === client
-                ? left + encodeRank([{ v: RUN, t: client }])
-                : undefined;
-        if (run === undefined)
-            return plain();
-        const tail = (r) => r && r.length > run.length && r.startsWith(run) ? r.slice(run.length) : undefined;
-        const rank = run + rankBetween(tail(left), tail(right), client, pick);
-        return right === undefined || rank < right ? rank : plain();
-    };
+    const between = (left, right) => rankAfter(left, right, client, pick);
     /** Give `entries` (kept items, moved items, new values) their places in `t`, in order. */
     const lay = (t, entries) => {
         let left;
@@ -314,9 +290,35 @@ const effective = (base, leaves) => {
             under(`${key}/`, v);
             out.set(key, []);
         }
+        else if (isObject(v) && Object.keys(v).length) {
+            // An object written as one leaf (an atomic path, `data.atomic`) reads as its keys.
+            under(`${key}/`, v);
+            out.set(key, {});
+        }
     }
     return out;
 };
+/** A path of the data as a leaf key (`d/` and its pointer). */
+export const leafKey = (path) => DATA_LEAF_PREFIX + path.map((k) => enc(k)).join('/');
+/**
+ * `leaves` with every atomic path (`data.atomic`, H8: a leaf key a kind
+ * declares) holding one leaf: the value of everything at and under it.
+ */
+const collapse = (leaves, atomic) => {
+    if (atomic.length === 0)
+        return leaves;
+    const root = treeOf(leaves);
+    for (const key of atomic) {
+        let t = root;
+        for (const s of key.slice(DATA_LEAF_PREFIX.length).split('/'))
+            t = t?.k.get(s);
+        if (t === undefined || t.k.size === 0)
+            continue;
+        t.v = valueOf(t);
+        t.k.clear();
+    }
+    return leavesFrom(root);
+};
 const read = (base, leaves) => valueOf(treeOf(effective(base, leaves)));
 /** `node`'s data (`undefined` when it has none). */
 export const readData = (node) => read(node.getAttr(DATA), leavesOf(node));
@@ -351,7 +353,7 @@ export const applyPatch = (data, patches) => {
  * they still read as the patched value, else it is exploded: every leaf
  * written, the attr deleted. An unchanged value writes nothing.
  */
-export const patchWrites = (node, patches, client = 0, rand) => {
+export const patchWrites = (node, patches, client = 0, rand, atomic = []) => {
     const [base, now] = [node.getAttr(DATA), leavesOf(node)];
     const was = effective(base, now);
     const root = treeOf(was);
@@ -359,13 +361,21 @@ export const patchWrites = (node, patches, client = 0, rand) => {
     const { apply } = edits(rand, client);
     if (!patches.every((p) => apply(root, p)))
         return null;
-    const [want, value] = [leavesFrom(root), valueOf(root)];
+    const value = valueOf(root);
     if (jsonEquals(before, value))
         return [];
+    // An atomic path is written as one leaf, and every leaf stored under it goes (H8).
+    const want = collapse(leavesFrom(root), atomic);
+    const under = (key) => atomic.some((a) => key.startsWith(`${a}/`));
     const diff = (from) => [...new Set([...from.keys(), ...want.keys()])]
         .filter((key) => !jsonEquals(from.get(key), want.get(key)))
         .map((key) => [key, want.get(key)]);
-    const own = diff(was);
+    const own = [
+        ...diff(collapse(was, atomic)),
+        ...[...now.keys()]
+            .filter((key) => under(key) && !want.has(key))
+            .map((key) => [key, undefined])
+    ];
     const after = new Map(now);
     for (const [key, value] of own)
         value === undefined ? after.delete(key) : after.set(key, value);

package/dist/crdt/document.d.ts

@@ -52,11 +52,14 @@ export type DocumentOptions = {
      * History tuning — applied when the document's undo manager attaches.
      * `captureTimeout` is the merge window in ms (engine default 500):
      * commits closer than this fuse into one undo step; `0` makes every
-     * commit its own step. Stacks are unbounded regardless — see
-     * {@link EdytorDocument.clearHistory} for the pruning surface.
+     * commit its own step. `limit` is the number of undo steps kept (default
+     * {@link DEFAULT_HISTORY_LIMIT}, 200; `Infinity` keeps every step): an
+     * older step is dropped and the deleted content it kept is collected.
+     * {@link EdytorDocument.clearHistory} drops both stacks.
      */
     history?: {
         captureTimeout?: number;
+        limit?: number;
     };
     /**
      * Opt-in per-block lineage ring — `depth > 0` captures a subtree
@@ -71,6 +74,17 @@ export type DocumentOptions = {
     lineage?: {
         depth?: number;
     };
+    /**
+     * Decide an EMPTY document only from a provider that synced (H12): the
+     * room answered, or a local store hydrated. A provider's bound or
+     * failure never seeds it, so a first visit offline writes nothing — no
+     * seed of `value` that a different seed in the room would later meet as
+     * duplicate blocks — and stays `pending` (a view keeps it read-only)
+     * until the document is fetched once. A document holding content is
+     * decided as before; an explicit {@link EdytorDocument.sync} still
+     * decides.
+     */
+    requireHydration?: boolean;
 };
 export type CreateDocumentOptions = DocumentOptions & {
     /**
@@ -158,10 +172,12 @@ export type EdytorDocumentInit = {
     semantics?: DocumentSemanticsConfig;
     history?: {
         captureTimeout?: number;
+        limit?: number;
     };
     lineage?: {
         depth?: number;
     };
+    requireHydration?: boolean;
 };
 /**
  * The assembled document — see the module header for the lifecycle,
@@ -253,6 +269,8 @@ export declare class EdytorDocument {
     private _defaultType;
     private readonly _historyOptions;
     private readonly _lineageDepth;
+    /** {@link DocumentOptions.requireHydration}: an empty document waits for a provider's `synced`. */
+    readonly requireHydration: boolean;
     /** Attached providers keyed by transport target (O75): one per target. */
     private _providers;
     private _pendingSyncs;
@@ -299,6 +317,12 @@ export declare class EdytorDocument {
      * @internal
      */
     get historyCaptureTimeout(): number | undefined;
+    /**
+     * The undo steps this document's history keeps (P6): the configured
+     * `history.limit`, else {@link DEFAULT_HISTORY_LIMIT}. The `attachDocument`
+     * dedupe check reads it (a reattach naming another limit is a conflict).
+     */
+    get historyLimit(): number;
     /**
      * The lineage ring depth this document was configured with — read by
      * the `attachDocument` dedupe compatibility check (a reattach naming
@@ -406,12 +430,11 @@ export declare class EdytorDocument {
     untrackOrigin: (origin: unknown) => void;
     private _attachHistory;
     /**
-     * Prune the undo/redo stacks — the document's retention surface. The
-     * engine keeps unbounded stacks: nothing is pruned implicitly (the
-     * `captureTimeout` merge window only fuses adjacent commits into one
-     * step). Call this to bound memory on long-lived documents, e.g. after
-     * a save checkpoint. No-op while history has not attached (there is
-     * nothing to clear — it does NOT force attach or throw on pending).
+     * Drop the undo/redo stacks. The undo stack already keeps only its
+     * newest `history.limit` steps (P6); call this where undo no longer makes
+     * sense, e.g. after a save checkpoint. No-op while history has not
+     * attached (there is nothing to clear — it does NOT force attach or throw
+     * on pending).
      */
     clearHistory: () => void;
     /** Local document transaction — headless edits, one undo step per call. */