edytor 0.1.0-next.20 → 0.1.0-next.22

package/README.md

@@ -15,7 +15,7 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **Work in progress.** Edytor is a pre-release (`0.1.0-next.20`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **Work in progress.** Edytor is a pre-release (`0.1.0-next.22`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 

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';

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';

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';
@@ -273,7 +276,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';

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
@@ -158,6 +161,7 @@ export type EdytorDocumentInit = {
     semantics?: DocumentSemanticsConfig;
     history?: {
         captureTimeout?: number;
+        limit?: number;
     };
     lineage?: {
         depth?: number;
@@ -299,6 +303,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 +416,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. */

package/dist/crdt/document.js

@@ -143,7 +143,7 @@
 import { DEV } from 'esm-env';
 import { Y } from './engine.js';
 import { bindAttribution } from './attribution/index.js';
-import { bindEdytorDoc, isInitialized, lineageDepthOf } from './edytor-doc.js';
+import { bindEdytorDoc, DEFAULT_HISTORY_LIMIT, isInitialized, lineageDepthOf } from './edytor-doc.js';
 import { assertAdmission, assertSchema, bindAdmission, checkSchema } from './admission.js';
 import { Awareness } from './protocols/awareness.js';
 import { callEach } from './protocols/observable.js';
@@ -199,12 +199,23 @@ export class DocumentDestroyedError extends Error {
  * does: from the socket's open, so a slow dial never counts).
  */
 export const DEFAULT_READINESS_BOUND = 1000;
-const normalizeRole = (role) => ({
-    void: role?.void === true,
-    island: role?.island === true,
-    lines: role?.lines === true,
-    ...(role?.layout === true && { layout: true })
-});
+const normalizeRole = (role) => {
+    const atomic = [
+        ...new Map((role?.atomic ?? []).map((p) => {
+            const path = typeof p === 'string' ? [p] : [...p];
+            return [JSON.stringify(path), path];
+        }))
+    ]
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([, path]) => path);
+    return {
+        void: role?.void === true,
+        island: role?.island === true,
+        lines: role?.lines === true,
+        ...(role?.layout === true && { layout: true }),
+        ...(atomic.length > 0 && { atomic })
+    };
+};
 const anonymousActor = () => ({
     id: `anon-${crypto.randomUUID()}`
 });
@@ -418,6 +429,14 @@ export class EdytorDocument {
     get historyCaptureTimeout() {
         return this._historyOptions?.captureTimeout;
     }
+    /**
+     * 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() {
+        return this._historyOptions?.limit ?? DEFAULT_HISTORY_LIMIT;
+    }
     /**
      * The lineage ring depth this document was configured with — read by
      * the `attachDocument` dedupe compatibility check (a reattach naming
@@ -657,17 +676,17 @@ export class EdytorDocument {
         this._history = this.facade.createUndoManager({
             trackedOrigins: this._trackedOrigins,
             captureTimeout: this._historyOptions?.captureTimeout,
+            limit: this.historyLimit,
             captureTransaction: (transaction) => transaction.local !== false
         });
         return this._history;
     };
     /**
-     * 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 = () => {
         if (this._destroyed) {
@@ -1017,6 +1036,9 @@ export const bindDocument = (Y) => {
             options.history.captureTimeout !== existing.historyCaptureTimeout) {
             throw new SemanticConflictError('history.captureTimeout', existing.historyCaptureTimeout, options.history.captureTimeout);
         }
+        if (options.history?.limit !== undefined && options.history.limit !== existing.historyLimit) {
+            throw new SemanticConflictError('history.limit', existing.historyLimit, options.history.limit);
+        }
         if (options.lineage?.depth !== undefined && options.lineage.depth !== existing.lineageDepth) {
             throw new SemanticConflictError('lineage.depth', existing.lineageDepth, options.lineage.depth);
         }

package/dist/crdt/edytor-doc.d.ts

@@ -98,6 +98,8 @@ export declare const assertUsableDoc: (doc: EngineDoc) => void;
  * counterpart of `DocumentDestroyedError` — kept in this module because a
  * bare `bindEdytorDoc` facade has no document layer above it.
  */
+/** The undo steps a document's history keeps by default (P6): older ones are released. */
+export declare const DEFAULT_HISTORY_LIMIT = 200;
 export declare class EdytorDocDisposedError extends Error {
     constructor(service?: string);
 }
@@ -120,6 +122,14 @@ export type BlockRole = {
      * a `defaultChild`.
      */
     layout?: boolean;
+    /**
+     * Data paths written as one leaf (`data.atomic`, H8): a top-level key, or
+     * an array of keys for a nested one (`['link', ['media', 'source']]`). An
+     * assignment there, or anywhere under it, writes the whole value as one
+     * last-writer-wins leaf, so two concurrent assignments never merge into a
+     * value neither wrote: one wins whole.
+     */
+    atomic?: readonly (string | readonly string[])[];
 };
 /** Island-sealing policy for a walk in document order (R5; see `next`). */
 export type OrderPolicy = {
@@ -495,7 +505,7 @@ export declare const bindEdytorDoc: (Y: EngineApi) => {
             isSelfOrDescendant: (placements: Map<BlockId, import("./placement/model.js").ResolvedPlacement>, own: import("./text/model.js").Ownership, id: BlockId, maybeAncestor: BlockId) => boolean;
             ranksAt: (siblings: readonly {
                 rank: string;
-            }[], index: number, count: number, clientId: number, rand?: () => number) => string[];
+            }[], index: number, count: number, clientId: number, rand?: () => number, run?: boolean) => string[];
             writePlacement: (doc: EngineDoc, node: EngineNode, p: BlockId | null, r: string) => void;
             withdrawOnUndo: (doc: EngineDoc) => (item: import("./engine-api.js").EngineItemRef, stackItem: {
                 inserts: {
@@ -617,7 +627,9 @@ export declare const bindEdytorDoc: (Y: EngineApi) => {
         checkSchema: () => SchemaProblem | null;
         assertSchema: () => void;
         dispose: () => void;
-        createUndoManager: (opts?: ConstructorParameters<EngineApi["UndoManager"]>[1]) => YUndoManager;
+        createUndoManager: (options?: ConstructorParameters<EngineApi["UndoManager"]>[1] & {
+            limit?: number;
+        }) => YUndoManager;
         project: () => import("./index.js").ProjectedDoc;
         toJSON: () => JSONDoc;
         blockJSON: (id: string) => JSONBlock;
@@ -712,7 +724,7 @@ export declare const bindEdytorDoc: (Y: EngineApi) => {
         isSelfOrDescendant: (placements: Map<BlockId, import("./placement/model.js").ResolvedPlacement>, own: import("./text/model.js").Ownership, id: BlockId, maybeAncestor: BlockId) => boolean;
         ranksAt: (siblings: readonly {
             rank: string;
-        }[], index: number, count: number, clientId: number, rand?: () => number) => string[];
+        }[], index: number, count: number, clientId: number, rand?: () => number, run?: boolean) => string[];
         writePlacement: (doc: EngineDoc, node: EngineNode, p: BlockId | null, r: string) => void;
         withdrawOnUndo: (doc: EngineDoc) => (item: import("./engine-api.js").EngineItemRef, stackItem: {
             inserts: {