@templatical/core 0.48.0 → 0.50.0

package/dist/index.js

@@ -1,6 +1,6 @@
-import { SdkError, assertNoSlotInContent, assertNoWrapperInContent, cloneBlock, createBlock, createDefaultTemplateContent, generateId, safeClone } from "@templatical/types";
-import { computed, reactive, readonly, ref, watch } from "@vue/reactivity";
-import { computed as computed$1, onScopeDispose, ref as ref$1, watch as watch$1 } from "vue";
+import { OperationError, SdkError, applyOperations, applyOperationsInPlace, assertNoSlotInContent, assertNoWrapperInContent, cloneBlock, createBlock, createDefaultTemplateContent, deepEqual, generateId, getColumnCount, invertOperations, invertOperations as invertOperations$1, safeClone } from "@templatical/types";
+import { computed, getCurrentScope, onScopeDispose, reactive, readonly, ref, shallowRef, watch } from "@vue/reactivity";
+import { computed as computed$1, onScopeDispose as onScopeDispose$1, ref as ref$1, watch as watch$1 } from "vue";
 //#region src/error-reporting.ts
 /**
 * Turn a thrown value into an `Error`.
@@ -32,11 +32,6 @@ function notifyHandler(onError, run) {
 }
 //#endregion
 //#region src/editor.ts
-function getColumnCount(layout) {
-	if (layout === "1") return 1;
-	if (layout === "3") return 3;
-	return 2;
-}
 function useEditor(options) {
 	const seedContent = options.content ?? createDefaultTemplateContent(options.defaultFontFamily, options.templateDefaults);
 	assertNoSlotInContent(seedContent);
@@ -53,6 +48,8 @@ function useEditor(options) {
 		isLoading: false,
 		uiTheme: "auto"
 	});
+	const loadVersion = ref(0);
+	let loadingRequest = 0;
 	/**
 	* Bumped by every content mutation. `save()` captures it before awaiting the
 	* provider and only clears `isDirty` if it is unchanged afterwards, so an edit
@@ -257,6 +254,7 @@ function useEditor(options) {
 		const { create: providerCreate } = provider;
 		if (typeof providerCreate !== "function") refuse("create()", "is disabled by the provider — its `create` is `false`.");
 		let created;
+		const request = ++loadingRequest;
 		state.isLoading = true;
 		try {
 			if (input?.content) state.content = input.content;
@@ -267,31 +265,35 @@ function useEditor(options) {
 			} : { content: state.content });
 			state.template = created;
 			if (revision === revisionAtRequest) state.isDirty = false;
+			loadVersion.value++;
 		} catch (error) {
 			options.onError?.(error);
 			throw error;
 		} finally {
-			state.isLoading = false;
+			if (loadingRequest === request) state.isLoading = false;
 		}
 		notify(() => provider.onCreated?.(created));
 		return created;
 	}
-	async function load(templateId) {
+	async function load(templateId, shouldApply) {
 		const provider = requireProvider("load()");
 		let loaded;
+		const request = ++loadingRequest;
 		state.isLoading = true;
 		try {
 			loaded = await provider.load(templateId);
 			assertNoSlotInContent(loaded.content);
 			assertNoWrapperInContent(loaded.content);
+			if (shouldApply && !shouldApply()) return loaded;
 			state.template = loaded;
 			state.content = loaded.content;
 			state.isDirty = false;
+			loadVersion.value++;
 		} catch (error) {
 			options.onError?.(error);
 			throw error;
 		} finally {
-			state.isLoading = false;
+			if (loadingRequest === request) state.isLoading = false;
 		}
 		notify(() => provider.onLoaded?.(loaded));
 		return loaded;
@@ -333,6 +335,7 @@ function useEditor(options) {
 	}
 	return {
 		state: readonly(state),
+		loadVersion: readonly(loadVersion),
 		content,
 		selectedBlock,
 		isBlockLocked,
@@ -362,7 +365,7 @@ const MAX_STACK_SIZE = 50;
 const DEBOUNCE_MS = 300;
 const NAVIGATE_IDLE_MS = 1500;
 function useHistory(options) {
-	const { content, setContent, isRemoteOperation, maxSize = MAX_STACK_SIZE } = options;
+	const { content, setContent, maxSize = MAX_STACK_SIZE } = options;
 	const undoStack = ref([]);
 	const redoStack = ref([]);
 	const isNavigating = ref(false);
@@ -384,13 +387,11 @@ function useHistory(options) {
 		}
 	}
 	function record() {
-		if (isRemoteOperation?.()) return;
 		flushPendingDebounce();
 		pushToUndoStack(cloneContent());
 		redoStack.value = [];
 	}
 	function recordDebounced(blockId) {
-		if (isRemoteOperation?.()) return;
 		if (pendingDebounce && pendingDebounce.blockId === blockId) {
 			clearTimeout(pendingDebounce.timeoutId);
 			pendingDebounce.timeoutId = setTimeout(() => {
@@ -622,8 +623,8 @@ function useDataSourceFetch(options) {
 * Wraps editor mutation methods to record history snapshots before each
 * operation. Mutates the editor object in place.
 *
-* Must be applied **after** any collaboration broadcast wrapping so the
-* call chain is: history.record() → broadcast → original mutation.
+* Not installed with a collaboration provider: its controller captures
+* changes by diffing the content and keeps its own undo history.
 */
 function useHistoryInterceptor(editor, history) {
 	const originalAddBlock = editor.addBlock;
@@ -658,6 +659,1139 @@ function useHistoryInterceptor(editor, history) {
 	};
 }
 //#endregion
+//#region src/diff-content.ts
+const ROOT_KEY = "root";
+const BLOCK_SKIP = /* @__PURE__ */ new Set([
+	"id",
+	"type",
+	"children"
+]);
+const RESIZED_SECTION_SKIP = /* @__PURE__ */ new Set([
+	"id",
+	"type",
+	"children",
+	"columns"
+]);
+const NO_SKIP = /* @__PURE__ */ new Set();
+function containerKey(parent) {
+	return parent === null ? ROOT_KEY : JSON.stringify([parent.sectionId, parent.column]);
+}
+function columnsOf(block) {
+	const children = block.children;
+	return block.type === "section" && Array.isArray(children) ? children : [];
+}
+/** Every block by id, with its container. The first occurrence of an id wins. */
+function indexBlocks(blocks) {
+	const placements = /* @__PURE__ */ new Map();
+	const walk = (list, parent) => {
+		list.forEach((block, index) => {
+			if (!placements.has(block.id)) placements.set(block.id, {
+				block,
+				key: containerKey(parent),
+				index
+			});
+			columnsOf(block).forEach((column, columnIndex) => {
+				if (Array.isArray(column)) walk(column, {
+					sectionId: block.id,
+					column: columnIndex
+				});
+			});
+		});
+	};
+	walk(blocks, null);
+	return placements;
+}
+/**
+* The positions in `values` of one longest strictly increasing run: the blocks
+* that can stay where they are while the others move around them.
+*/
+function longestIncreasingRun(values) {
+	const tails = [];
+	const previous = new Array(values.length).fill(-1);
+	values.forEach((value, position) => {
+		let low = 0;
+		let high = tails.length;
+		while (low < high) {
+			const middle = low + high >> 1;
+			if (values[tails[middle]] < value) low = middle + 1;
+			else high = middle;
+		}
+		if (low > 0) previous[position] = tails[low - 1];
+		tails[low] = position;
+	});
+	const run = /* @__PURE__ */ new Set();
+	let position = tails.length > 0 ? tails[tails.length - 1] : -1;
+	while (position !== -1) {
+		run.add(position);
+		position = previous[position];
+	}
+	return run;
+}
+/** Keys whose values differ, as `set` and `unset`. `undefined` counts as absent. */
+function keyChanges(before, after, skip) {
+	const set = {};
+	const unset = [];
+	for (const key of Object.keys(after)) {
+		if (skip.has(key) || after[key] === void 0) continue;
+		if (!deepEqual(before[key], after[key])) set[key] = safeClone(after[key]);
+	}
+	for (const key of Object.keys(before)) {
+		if (skip.has(key) || before[key] === void 0) continue;
+		if (after[key] === void 0) unset.push(key);
+	}
+	return {
+		set,
+		unset
+	};
+}
+/**
+* The operations that turn `before` into `after`. Blocks are matched by id, so
+* a drag comes out as a `moveBlock` and a layout change as a `columns` change
+* plus moves, never as deletions and re-additions.
+*
+* `applyOperations(before, diffContent(before, after))` deep-equals `after`
+* when both are well formed: unique ids, sections only at the top level, and
+* each section's `children` as long as its layout's column count. The order is
+* what the engine needs:
+*
+* 1. Deletions that take nothing still needed with them.
+* 2. The top level: additions (a new section carries its new children) and moves.
+* 3. `columns` growth, so new columns exist before blocks move into them.
+* 4. Every section column: additions and moves, out of shrinking columns too.
+* 5. `columns` shrinkage, once the dropped columns are empty.
+* 6. Deletion of sections whose surviving blocks have moved out.
+* 7. Key changes on blocks, then on settings.
+*
+* No operation carries `expect`: an ordinary edit applies over anything that
+* doesn't conflict with it, and locks keep two people off one block.
+*/
+function diffContent(before, after) {
+	const was = indexBlocks(before.blocks);
+	const now = indexBlocks(after.blocks);
+	const ops = [];
+	const typeChanged = (id) => {
+		const next = now.get(id);
+		const previous = was.get(id);
+		return next !== void 0 && previous !== void 0 && next.block.type !== previous.block.type;
+	};
+	const survives = (block) => now.has(block.id) && !typeChanged(block.id);
+	const hasSurvivor = (block) => columnsOf(block).some((column) => Array.isArray(column) && column.some((child) => survives(child) || !typeChanged(child.id) && hasSurvivor(child)));
+	const gone = /* @__PURE__ */ new Set();
+	const deferred = [];
+	const visit = (block, fate) => {
+		let childFate = "kept";
+		if (fate === "dropped") {
+			gone.add(block.id);
+			childFate = "dropped";
+		} else if (typeChanged(block.id)) {
+			ops.push({
+				op: "deleteBlock",
+				blockId: block.id
+			});
+			gone.add(block.id);
+			childFate = "dropped";
+		} else if (!now.has(block.id)) {
+			if (fate === "deferred") childFate = "deferred";
+			else if (hasSurvivor(block)) {
+				deferred.push(block.id);
+				childFate = "deferred";
+			} else {
+				ops.push({
+					op: "deleteBlock",
+					blockId: block.id
+				});
+				gone.add(block.id);
+				childFate = "dropped";
+			}
+		}
+		for (const column of columnsOf(block)) if (Array.isArray(column)) for (const child of column) visit(child, childFate);
+	};
+	for (const block of before.blocks) visit(block, "kept");
+	const exists = (id) => was.has(id) && !gone.has(id);
+	const payloadOf = (block) => {
+		const payload = safeClone(block);
+		if (payload.type === "section") payload.children = columnsOf(block).map((column) => Array.isArray(column) ? column.filter((child) => !exists(child.id)).map((child) => safeClone(child)) : column);
+		return payload;
+	};
+	const place = (parent, finalList, arrivedWithParent) => {
+		const key = containerKey(parent);
+		const indexes = [];
+		const positions = [];
+		finalList.forEach((block, position) => {
+			const previous = was.get(block.id);
+			if (exists(block.id) && previous !== void 0 && previous.key === key) {
+				indexes.push(previous.index);
+				positions.push(position);
+			}
+		});
+		const staying = new Set([...longestIncreasingRun(indexes)].map((run) => positions[run]));
+		finalList.forEach((block, position) => {
+			if (staying.has(position) || arrivedWithParent(block)) return;
+			const afterId = position > 0 ? finalList[position - 1].id : null;
+			ops.push(exists(block.id) ? {
+				op: "moveBlock",
+				blockId: block.id,
+				parent,
+				after: afterId
+			} : {
+				op: "addBlock",
+				block: payloadOf(block),
+				parent,
+				after: afterId
+			});
+		});
+	};
+	place(null, after.blocks, () => false);
+	const sections = after.blocks.filter((block) => block.type === "section");
+	const resized = /* @__PURE__ */ new Set();
+	const resize = (grow) => {
+		for (const section of sections) {
+			if (!exists(section.id)) continue;
+			const fromCount = columnsOf(was.get(section.id).block).length;
+			const toCount = columnsOf(section).length;
+			if (grow ? toCount > fromCount : toCount < fromCount) {
+				ops.push({
+					op: "updateBlock",
+					blockId: section.id,
+					set: { columns: section.columns }
+				});
+				resized.add(section.id);
+			}
+		}
+	};
+	resize(true);
+	for (const section of sections) {
+		const isNew = !exists(section.id);
+		columnsOf(section).forEach((column, columnIndex) => {
+			if (!Array.isArray(column)) return;
+			place({
+				sectionId: section.id,
+				column: columnIndex
+			}, column, (child) => isNew && !exists(child.id));
+		});
+	}
+	resize(false);
+	for (const id of deferred) ops.push({
+		op: "deleteBlock",
+		blockId: id
+	});
+	for (const [id, placement] of now) {
+		if (!exists(id)) continue;
+		const { set, unset } = keyChanges(was.get(id).block, placement.block, resized.has(id) ? RESIZED_SECTION_SKIP : BLOCK_SKIP);
+		if (Object.keys(set).length === 0 && unset.length === 0) continue;
+		ops.push({
+			op: "updateBlock",
+			blockId: id,
+			...Object.keys(set).length > 0 ? { set } : {},
+			...unset.length > 0 ? { unset } : {}
+		});
+	}
+	const settings = keyChanges(before.settings, after.settings, NO_SKIP);
+	if (Object.keys(settings.set).length > 0 || settings.unset.length > 0) ops.push({
+		op: "updateSettings",
+		...Object.keys(settings.set).length > 0 ? { set: settings.set } : {},
+		...settings.unset.length > 0 ? { unset: settings.unset } : {}
+	});
+	return ops;
+}
+/** A revision that hasn't arrived after this long is fetched. */
+const COLLABORATION_GAP_TIMEOUT_MS = 1e3;
+/** A held lock is renewed this often; the backend lets it lapse after 30 s. */
+const COLLABORATION_LOCK_RENEW_MS = 1e4;
+/** Waits between attempts at a batch that failed in transit. */
+const RETRY_DELAYS_MS = [
+	1e3,
+	2e3,
+	5e3,
+	1e4,
+	3e4
+];
+/** The snapshot history's depth, kept for the operation history too. */
+const DEFAULT_MAX_UNDO = 50;
+/** OperationBatch allows 1–100 operations. */
+const MAX_BATCH_OPS = 100;
+const REFUSAL_CODES = /* @__PURE__ */ new Set([
+	"block_exists",
+	"block_missing",
+	"anchor_missing",
+	"precondition_failed",
+	"lock_held",
+	"locked_by_others",
+	"invalid_operation",
+	"lock_lost",
+	"content_too_large"
+]);
+function refusalCode(error) {
+	const code = error?.code;
+	return typeof code === "string" && REFUSAL_CODES.has(code) ? code : null;
+}
+function refusalHolder(error) {
+	const holder = error?.holder;
+	return typeof holder === "object" && holder !== null && typeof holder.sessionId === "string" ? holder : void 0;
+}
+/** Network failures, 5xx, 408 and 429 are worth retrying; other 4xx aren't. */
+function isTransient(error) {
+	const status = error?.statusCode;
+	if (typeof status !== "number") return true;
+	return status >= 500 || status === 408 || status === 429;
+}
+function containsBlock(blocks, blockId) {
+	return blocks.some((block) => {
+		if (block.id === blockId) return true;
+		const children = block.children;
+		return block.type === "section" && Array.isArray(children) && children.some((column) => Array.isArray(column) && containsBlock(column, blockId));
+	});
+}
+/** Typing into one block, or one settings change: worth batching up. */
+function isCoalescible(ops) {
+	if (ops.length === 1 && ops[0].op === "updateSettings") return true;
+	const first = ops[0];
+	return first.op === "updateBlock" && ops.every((op) => op.op === "updateBlock" && op.blockId === first.blockId);
+}
+/**
+* A remote batch without its preconditions. The backend checked them against
+* its own copy before it accepted the batch. This copy can differ from that one
+* in merge-tag markup alone — tokens are normalized into tags on load and on
+* arrival — and an `expect` compares content exactly, so checking it here
+* refuses a batch the backend applied and reloads the template. Structural
+* checks still run, and still catch a copy that really drifted.
+*/
+function withoutPreconditions(ops) {
+	return ops.map((op) => {
+		if (!("expect" in op)) return op;
+		const { expect: _expect, ...rest } = op;
+		return rest;
+	});
+}
+/**
+* Real-time collaboration over a {@link CollaborationProvider}.
+*
+* The controller keeps the content the backend confirmed at revision R, plus
+* this session's pending batches; the canvas shows the confirmed content with
+* the pending batches applied. Local changes are captured by diffing the
+* canvas against that view: structural changes, selection changes and blur
+* send at once, typing into one block after a short pause. One batch is in
+* flight at a time. Batches from other sessions apply strictly by revision,
+* with this session's pending batches replayed on top; a gap that isn't
+* filled within a second, a re-sync, a reconnect and a refusal all fetch what
+* was missed.
+*
+* Selecting a block takes its lock (when the backend has locks), renewed
+* while selected and released on deselect, template switch and page hide.
+* Undo and redo send inverse batches guarded by preconditions; one that no
+* longer applies is dropped with a notice. Changes from others never enter the
+* stacks.
+*/
+function useCollaboration(options) {
+	const { provider } = options;
+	const sessionId = options.sessionId ?? crypto.randomUUID();
+	const maxUndo = options.maxUndo ?? DEFAULT_MAX_UNDO;
+	const locking = typeof provider.acquireLock === "function" && typeof provider.renewLock === "function" && typeof provider.releaseLock === "function";
+	const members = shallowRef([]);
+	const locks = shallowRef(/* @__PURE__ */ new Map());
+	const connection = ref(null);
+	const revision = ref(0);
+	const historyVersion = ref(0);
+	let editor = null;
+	let active = null;
+	let suspended = false;
+	let writing = false;
+	let captureQueued = false;
+	let typingTimer = null;
+	let typingSince = 0;
+	let destroyed = false;
+	/** The watchers `attach` set up; `destroy` stops them, scope or not. */
+	const stopWatching = [];
+	let wanted = null;
+	let held = null;
+	let lockQueue = Promise.resolve();
+	let renewTimer = null;
+	const canUndo = computed(() => {
+		historyVersion.value;
+		return (active?.undo.length ?? 0) > 0;
+	});
+	const canRedo = computed(() => {
+		historyVersion.value;
+		return (active?.redo.length ?? 0) > 0;
+	});
+	function reportError(error) {
+		options.onError?.(error instanceof Error ? error : new Error(String(error)));
+	}
+	function notify(notice, session = active) {
+		if (session !== active || destroyed) return;
+		options.onNotice?.(notice);
+	}
+	function lockContext() {
+		return {
+			locks: [...locks.value.values()].map((lock) => ({
+				blockId: lock.blockId,
+				sessionId: lock.holder.sessionId
+			})),
+			session: sessionId
+		};
+	}
+	function bumpHistory() {
+		historyVersion.value++;
+	}
+	function pushCapped(stack, entry) {
+		stack.push(entry);
+		if (stack.length > maxUndo) stack.splice(0, stack.length - maxUndo);
+	}
+	/** Put `view` on the canvas, changing only what differs from it. */
+	function renderView(view) {
+		if (!editor || suspended) return;
+		writing = true;
+		try {
+			const live = editor.content.value;
+			const ops = diffContent(live, view);
+			if (ops.length > 0) try {
+				applyOperationsInPlace(live, ops);
+			} catch {
+				editor.setContent(safeClone(view), false);
+			}
+			if (!deepEqual(editor.content.value, view)) editor.setContent(safeClone(view), false);
+		} finally {
+			writing = false;
+		}
+		const selected = editor.state.selectedBlockId;
+		if (selected && !containsBlock(view.blocks, selected)) editor.selectBlock(null);
+	}
+	function scheduleCapture() {
+		if (writing || captureQueued) return;
+		captureQueued = true;
+		queueMicrotask(() => {
+			captureQueued = false;
+			capture(false);
+		});
+	}
+	function clearTypingTimer() {
+		if (typingTimer) {
+			clearTimeout(typingTimer);
+			typingTimer = null;
+		}
+	}
+	/**
+	* Diff the canvas against the view and send what changed. `duringLoad` is
+	* for the moment a load or create starts: the canvas still shows this
+	* template, and its unsent typing must go before the content is replaced.
+	*/
+	function capture(force, duringLoad = false) {
+		const session = active;
+		if (!editor || !session || suspended || writing) return;
+		if (editor.state.isLoading && !duringLoad) return;
+		if (editor.state.template?.id !== session.templateId) return;
+		const ops = diffContent(session.view, editor.content.value);
+		if (ops.length === 0) {
+			clearTypingTimer();
+			return;
+		}
+		if (!force && isCoalescible(ops)) {
+			const now = Date.now();
+			if (typingTimer === null) typingSince = now;
+			if (now - typingSince < 1e3) {
+				if (typingTimer) clearTimeout(typingTimer);
+				typingTimer = setTimeout(() => {
+					typingTimer = null;
+					capture(true);
+				}, 300);
+				return;
+			}
+		}
+		clearTypingTimer();
+		commit(session, ops);
+	}
+	function flush() {
+		capture(true);
+	}
+	function commit(session, proposed) {
+		let ops = proposed;
+		let next;
+		try {
+			next = applyOperations(session.view, ops, lockContext());
+		} catch (error) {
+			if (!(error instanceof OperationError)) throw error;
+			renderView(session.view);
+			const holder = error.blockId === void 0 ? void 0 : locks.value.get(error.blockId)?.holder;
+			notify({
+				type: "editRefused",
+				code: error.code,
+				...holder ? { holder } : {}
+			});
+			if (error.code === "invalid_operation") reportError(error);
+			return;
+		}
+		const live = editor.content.value;
+		if (!deepEqual(next, live)) {
+			reportError(/* @__PURE__ */ new Error("[Templatical] Collaboration: a change couldn't be expressed as block operations, so the whole content was sent."));
+			ops = [{
+				op: "setContent",
+				content: safeClone(live)
+			}];
+			try {
+				next = applyOperations(session.view, ops, lockContext());
+			} catch (error) {
+				if (!(error instanceof OperationError)) throw error;
+				renderView(session.view);
+				notify({
+					type: "editRefused",
+					code: error.code
+				});
+				return;
+			}
+		}
+		const entry = { ops: invertOperations$1(session.view, ops) };
+		pushCapped(session.undo, entry);
+		session.redo = [];
+		bumpHistory();
+		session.view = next;
+		enqueue(session, ops, "edit", entry);
+	}
+	function enqueue(session, ops, origin, entry) {
+		const group = { dropped: false };
+		let offset = 0;
+		do {
+			session.pending.push({
+				batchId: crypto.randomUUID(),
+				ops: ops.slice(offset, offset + MAX_BATCH_OPS),
+				origin,
+				entry,
+				group,
+				sent: false,
+				revision: null
+			});
+			offset += MAX_BATCH_OPS;
+		} while (offset < ops.length);
+		pump(session);
+	}
+	function pump(session) {
+		if (session.inFlight) return;
+		const next = session.pending.find((batch) => !batch.sent);
+		if (!next) {
+			settleWaiters(session);
+			return;
+		}
+		next.sent = true;
+		session.inFlight = next;
+		send(session, next, 0);
+	}
+	function send(session, batch, attempt) {
+		provider.submit(session.templateId, {
+			batchId: batch.batchId,
+			baseRevision: session.revision,
+			ops: batch.ops,
+			...batch.origin === "ai" ? { origin: "ai" } : {}
+		}).then(({ revision: confirmedAt }) => {
+			session.inFlight = null;
+			confirmOwn(session, batch, confirmedAt);
+			pump(session);
+		}, (error) => {
+			if (refusalCode(error) !== null) {
+				session.inFlight = null;
+				refuse(session, batch, error);
+				pump(session);
+				return;
+			}
+			if (isTransient(error)) {
+				rejectWaiters(session, error);
+				const delay = RETRY_DELAYS_MS[Math.min(attempt, RETRY_DELAYS_MS.length - 1)];
+				setTimeout(() => {
+					if (!destroyed) send(session, batch, attempt + 1);
+				}, delay);
+				return;
+			}
+			session.inFlight = null;
+			reportError(error);
+			refuse(session, batch, error);
+			pump(session);
+		});
+	}
+	function confirmOwn(session, batch, at) {
+		if (batch.revision !== null) return;
+		batch.revision = at;
+		if (at <= session.revision) {
+			dropPending(session, batch);
+			rebuild(session);
+			return;
+		}
+		session.own.set(at, batch);
+		drain(session);
+	}
+	function dropPending(session, batch) {
+		session.pending = session.pending.filter((pending) => pending !== batch);
+		settleWaiters(session);
+	}
+	function takeBackEntry(session, batch) {
+		if (!batch.entry) return;
+		for (const stack of [session.undo, session.redo]) {
+			const position = stack.indexOf(batch.entry);
+			if (position !== -1) stack.splice(position, 1);
+		}
+		bumpHistory();
+	}
+	function dropRefusedGroup(session, batch) {
+		const firstRefusal = !batch.group.dropped;
+		batch.group.dropped = true;
+		session.pending = session.pending.filter((pending) => pending.group !== batch.group || pending.sent);
+		if (firstRefusal) takeBackEntry(session, batch);
+		settleWaiters(session);
+		return firstRefusal;
+	}
+	function refuse(session, batch, error) {
+		dropPending(session, batch);
+		if (dropRefusedGroup(session, batch)) {
+			const code = refusalCode(error) ?? "invalid_operation";
+			if (batch.origin === "edit" || batch.origin === "ai") {
+				const holder = refusalHolder(error);
+				notify({
+					type: "editRefused",
+					code,
+					...holder ? { holder } : {}
+				}, session);
+			} else notify({
+				type: "undoSkipped",
+				code
+			}, session);
+		}
+		rebuild(session);
+		if (session === active) catchUp();
+	}
+	function settleWaiters(session) {
+		if (session.pending.length > 0 || session.waiters.length === 0) return;
+		for (const waiter of session.waiters.splice(0)) waiter.resolve();
+	}
+	function rejectWaiters(session, error) {
+		const reason = error instanceof Error ? error : new Error(String(error));
+		for (const waiter of session.waiters.splice(0)) waiter.reject(reason);
+	}
+	function receive(session, batch) {
+		if (batch.revision <= session.revision) return;
+		const mine = session.pending.find((pending) => pending.batchId === batch.batchId);
+		if (mine) {
+			confirmOwn(session, mine, batch.revision);
+			return;
+		}
+		session.remote.set(batch.revision, batch);
+		drain(session);
+	}
+	/**
+	* The ops another session's batch applies here: rewritten by
+	* `normalizeRemoteOperations`, then without their preconditions. A
+	* normalizer that throws is reported, and the batch applies as it came.
+	*/
+	function arriving(session, batch) {
+		let ops = batch.ops;
+		if (options.normalizeRemoteOperations) try {
+			ops = options.normalizeRemoteOperations(batch.ops, session.confirmed);
+		} catch (error) {
+			reportError(error);
+		}
+		return withoutPreconditions(ops);
+	}
+	/** Apply whatever is next in revision order, own and remote alike. */
+	function drain(session) {
+		const applied = [];
+		let confirmedDroppedChunk = false;
+		for (;;) {
+			const at = session.revision + 1;
+			const remote = session.remote.get(at);
+			const own = session.own.get(at);
+			if (!remote && !own) break;
+			try {
+				session.confirmed = applyOperations(session.confirmed, remote ? arriving(session, remote) : own.ops);
+			} catch {
+				if (session.recovering) {
+					session.remote.clear();
+					session.own.clear();
+					reportError(/* @__PURE__ */ new Error("[Templatical] Collaboration: this editor can't follow the template's changes. Reload the page."));
+					return;
+				}
+				reload(session);
+				return;
+			}
+			session.revision = at;
+			if (remote) {
+				session.remote.delete(at);
+				applied.push(remote);
+			} else {
+				session.own.delete(at);
+				if (own.group.dropped) confirmedDroppedChunk = true;
+				dropPending(session, own);
+			}
+		}
+		if (session === active) revision.value = session.revision;
+		if (session.remote.size > 0 || session.own.size > 0) armGapTimer(session);
+		else clearGapTimer(session);
+		if (applied.length === 0 && !confirmedDroppedChunk) return;
+		rebuild(session);
+		if (session !== active) return;
+		for (const batch of applied) try {
+			options.onRemoteChange?.({
+				actor: batch.actor,
+				ops: batch.ops
+			});
+		} catch (error) {
+			reportError(error);
+		}
+	}
+	/** Recompute the view from `confirmed`, replaying what is still pending. */
+	function rebuild(session) {
+		if (session === active) flush();
+		let view = session.confirmed;
+		for (let index = 0; index < session.pending.length; index++) {
+			const batch = session.pending[index];
+			try {
+				view = applyOperations(view, batch.ops);
+			} catch (error) {
+				if (batch.sent) continue;
+				if (dropRefusedGroup(session, batch)) {
+					const code = error instanceof OperationError ? error.code : "invalid_operation";
+					notify(batch.origin === "edit" || batch.origin === "ai" ? {
+						type: "editRefused",
+						code
+					} : {
+						type: "undoSkipped",
+						code
+					}, session);
+				}
+				view = session.confirmed;
+				index = -1;
+			}
+		}
+		session.view = view;
+		settleWaiters(session);
+		if (session === active) renderView(view);
+	}
+	function armGapTimer(session) {
+		if (session.gapTimer) return;
+		session.gapTimer = setTimeout(() => {
+			session.gapTimer = null;
+			if (session === active) catchUp();
+		}, COLLABORATION_GAP_TIMEOUT_MS);
+	}
+	function clearGapTimer(session) {
+		if (session.gapTimer) {
+			clearTimeout(session.gapTimer);
+			session.gapTimer = null;
+		}
+	}
+	function catchUp() {
+		const session = active;
+		if (!session) return Promise.resolve();
+		if (session.catchingUp) return session.catchingUp;
+		session.catchingUp = (async () => {
+			try {
+				const result = await provider.operationsAfter(session.templateId, session.revision);
+				if (session.retired) return;
+				if ("resync" in result) {
+					await reload(session);
+					return;
+				}
+				for (const batch of result.batches) receive(session, batch);
+			} catch (error) {
+				reportError(error);
+			} finally {
+				session.catchingUp = null;
+			}
+		})();
+		return session.catchingUp;
+	}
+	async function reload(session) {
+		session.recovering = true;
+		try {
+			const template = await options.loadTemplate(session.templateId);
+			if (session.retired) return;
+			const at = template.revision ?? session.revision;
+			session.confirmed = safeClone(template.content);
+			session.revision = at;
+			session.remote = new Map([...session.remote].filter(([remoteAt]) => remoteAt > at));
+			for (const [ownAt, batch] of [...session.own]) if (ownAt <= at) {
+				session.own.delete(ownAt);
+				dropPending(session, batch);
+			}
+			if (session === active) revision.value = at;
+			rebuild(session);
+			drain(session);
+		} catch (error) {
+			reportError(error);
+		} finally {
+			session.recovering = false;
+		}
+	}
+	function handlersFor(session) {
+		const live = () => session === active && !session.retired;
+		return {
+			onBatch: (batch) => {
+				if (live()) receive(session, batch);
+			},
+			onResync: (at, actor) => {
+				if (!live() || at <= session.revision) return;
+				if (actor) try {
+					options.onRemoteResync?.({
+						revision: at,
+						actor
+					});
+				} catch (error) {
+					reportError(error);
+				}
+				catchUp();
+			},
+			onLock: (lock) => {
+				if (live()) setLock(lock);
+			},
+			onUnlock: (blockId, holderSession) => {
+				if (live()) removeLock(blockId, holderSession);
+			},
+			onMembers: (next) => {
+				if (live()) setMembers(next);
+			},
+			onConnectionChange: (state) => {
+				if (live()) changeConnection(session, state);
+			}
+		};
+	}
+	function join(session, refresh) {
+		provider.join(session.templateId, { sessionId }, handlersFor(session)).then((joined) => {
+			if (session.retired || session !== active) {
+				if (!refresh) joined.leave();
+				return;
+			}
+			session.leave = joined.leave;
+			replaceLocks(joined.locks, !refresh);
+			setMembers(joined.members);
+			if (joined.members.length > 0) connection.value = "connected";
+			if (joined.revision > session.revision) catchUp();
+			if (refresh) reconcileLock();
+		}, (error) => reportError(error));
+	}
+	function start(template) {
+		const content = safeClone(template.content);
+		const session = {
+			templateId: template.id,
+			confirmed: content,
+			revision: template.revision ?? 0,
+			pending: [],
+			view: safeClone(content),
+			remote: /* @__PURE__ */ new Map(),
+			own: /* @__PURE__ */ new Map(),
+			inFlight: null,
+			gapTimer: null,
+			catchingUp: null,
+			leave: null,
+			retired: false,
+			recovering: false,
+			undo: [],
+			redo: [],
+			waiters: []
+		};
+		active = session;
+		revision.value = session.revision;
+		bumpHistory();
+		join(session, false);
+		if (editor?.state.selectedBlockId) onSelection(editor.state.selectedBlockId);
+		scheduleCapture();
+	}
+	function retire(session) {
+		session.retired = true;
+		clearGapTimer(session);
+		session.leave?.();
+		session.leave = null;
+		rejectWaiters(session, /* @__PURE__ */ new Error("[Templatical] The template was closed."));
+	}
+	function changeConnection(session, state) {
+		const previous = connection.value;
+		connection.value = state;
+		if (state === "connected" && previous !== null && previous !== "connected") join(session, true);
+	}
+	function switchTo(template) {
+		if (active && active.templateId === template?.id) return;
+		if (active) {
+			clearTypingTimer();
+			retire(active);
+			active = null;
+		}
+		members.value = [];
+		locks.value = /* @__PURE__ */ new Map();
+		connection.value = null;
+		wanted = null;
+		reconcileLock();
+		bumpHistory();
+		if (template) start(template);
+	}
+	function setLock(lock) {
+		if (lock.holder.sessionId === sessionId) return;
+		const next = new Map([...locks.value].filter(([, existing]) => existing.holder.sessionId !== lock.holder.sessionId));
+		next.set(lock.blockId, lock);
+		locks.value = next;
+		if (editor?.state.selectedBlockId === lock.blockId) {
+			editor.selectBlock(null);
+			notify({
+				type: "selectionRefused",
+				blockId: lock.blockId,
+				holder: lock.holder
+			});
+		}
+	}
+	function removeLock(blockId, holderSession) {
+		if (locks.value.get(blockId)?.holder.sessionId !== holderSession) return;
+		const next = new Map(locks.value);
+		next.delete(blockId);
+		locks.value = next;
+	}
+	function replaceLocks(list, merge) {
+		const next = merge ? new Map(locks.value) : /* @__PURE__ */ new Map();
+		for (const lock of list) {
+			if (lock.holder.sessionId === sessionId) continue;
+			if (merge && next.has(lock.blockId)) continue;
+			next.set(lock.blockId, lock);
+		}
+		locks.value = next;
+	}
+	function setMembers(next) {
+		const present = new Set(next.map((member) => member.sessionId));
+		const departed = new Set(members.value.map((member) => member.sessionId).filter((id) => !present.has(id)));
+		members.value = next;
+		if (departed.size === 0) return;
+		const remaining = new Map([...locks.value].filter(([, lock]) => !departed.has(lock.holder.sessionId)));
+		if (remaining.size !== locks.value.size) locks.value = remaining;
+	}
+	function queueLock(task) {
+		lockQueue = lockQueue.then(task).catch(reportError);
+	}
+	/** Move what the backend granted toward what is selected, one call at a time. */
+	function reconcileLock() {
+		if (!locking) return;
+		queueLock(async () => {
+			if (held && (wanted === null || held.templateId !== wanted.templateId)) {
+				const releasing = held;
+				held = null;
+				stopRenewing();
+				await provider.releaseLock(releasing.templateId, releasing.blockId);
+			}
+			const target = wanted;
+			if (!target || held?.templateId === target.templateId && held.blockId === target.blockId) return;
+			try {
+				await provider.acquireLock(target.templateId, target.blockId);
+				held = target;
+				startRenewing();
+				forgetLock(target.blockId);
+			} catch (error) {
+				if (held?.templateId === target.templateId) {
+					const releasing = held;
+					held = null;
+					stopRenewing();
+					await provider.releaseLock(releasing.templateId, releasing.blockId).catch(() => {});
+				}
+				if (wanted !== target) return;
+				refuseSelection(target.blockId, error);
+			}
+		});
+	}
+	function forgetLock(blockId) {
+		if (!locks.value.has(blockId)) return;
+		const next = new Map(locks.value);
+		next.delete(blockId);
+		locks.value = next;
+	}
+	function refuseSelection(blockId, error) {
+		const code = refusalCode(error);
+		if (code === "lock_held" || code === "block_missing") {
+			wanted = null;
+			const holder = refusalHolder(error);
+			if (holder) setLock({
+				blockId,
+				holder,
+				expiresAt: ""
+			});
+			else if (editor?.state.selectedBlockId === blockId) editor.selectBlock(null);
+			return;
+		}
+		reportError(error);
+		setTimeout(() => {
+			if (wanted?.blockId === blockId) reconcileLock();
+		}, RETRY_DELAYS_MS[0]);
+	}
+	function startRenewing() {
+		if (renewTimer) return;
+		renewTimer = setInterval(() => {
+			queueLock(async () => {
+				const current = held;
+				if (!current) return;
+				try {
+					await provider.renewLock(current.templateId, current.blockId);
+				} catch (error) {
+					if (refusalCode(error) === "lock_lost") {
+						held = null;
+						stopRenewing();
+						reconcileLock();
+						return;
+					}
+					reportError(error);
+				}
+			});
+		}, COLLABORATION_LOCK_RENEW_MS);
+	}
+	function stopRenewing() {
+		if (renewTimer) {
+			clearInterval(renewTimer);
+			renewTimer = null;
+		}
+	}
+	function onSelection(blockId) {
+		flush();
+		if (!active) return;
+		wanted = blockId ? {
+			templateId: active.templateId,
+			blockId
+		} : null;
+		reconcileLock();
+	}
+	/** The page is going away: send what's typed, let go of the lock, leave. */
+	function onPageHide() {
+		flush();
+		if (held && locking) {
+			provider.releaseLock(held.templateId, held.blockId).catch(() => {});
+			held = null;
+			stopRenewing();
+		}
+		active?.leave?.();
+		if (active) active.leave = null;
+	}
+	function step(direction) {
+		const session = active;
+		if (!session || suspended) return;
+		flush();
+		const entry = (direction === "undo" ? session.undo : session.redo).pop();
+		if (!entry) return;
+		bumpHistory();
+		let next;
+		try {
+			next = applyOperations(session.view, entry.ops, lockContext());
+		} catch (error) {
+			if (!(error instanceof OperationError)) throw error;
+			notify({
+				type: "undoSkipped",
+				code: error.code
+			});
+			return;
+		}
+		const counter = { ops: invertOperations$1(session.view, entry.ops) };
+		pushCapped(direction === "undo" ? session.redo : session.undo, counter);
+		session.view = next;
+		renderView(next);
+		editor?.markDirty();
+		enqueue(session, entry.ops, direction, counter);
+	}
+	function applyFromTurn(ops, options) {
+		const session = active;
+		if (!editor || !session || suspended) return {
+			applied: false,
+			error: new OperationError("invalid_operation", 0, "No template is open for editing.")
+		};
+		flush();
+		let next;
+		let inverse;
+		try {
+			next = applyOperations(session.view, ops, lockContext());
+			inverse = invertOperations$1(session.view, ops);
+		} catch (error) {
+			if (error instanceof OperationError) return {
+				applied: false,
+				error
+			};
+			throw error;
+		}
+		const top = session.undo.at(-1);
+		let entry;
+		if (top && top.turn === options.turn) {
+			top.ops = [...inverse, ...top.ops];
+			entry = top;
+		} else {
+			entry = {
+				ops: inverse,
+				turn: options.turn
+			};
+			pushCapped(session.undo, entry);
+		}
+		session.redo = [];
+		bumpHistory();
+		session.view = next;
+		renderView(next);
+		editor.markDirty();
+		enqueue(session, ops, options.origin, entry);
+		return {
+			applied: true,
+			inverse
+		};
+	}
+	function attach(target) {
+		editor = target;
+		stopWatching.push(watch(() => target.state.template, (template) => switchTo(template), { immediate: true }), watch(() => target.content.value, scheduleCapture, { deep: true }), watch(() => target.state.selectedBlockId, onSelection), watch(() => target.state.isLoading, (loading) => loading ? capture(true, true) : scheduleCapture()));
+		if (typeof window !== "undefined") {
+			window.addEventListener("pagehide", onPageHide);
+			window.addEventListener("blur", flush);
+		}
+		if (getCurrentScope()) onScopeDispose(destroy);
+	}
+	function settle() {
+		flush();
+		const session = active;
+		if (!session || session.pending.length === 0) return Promise.resolve();
+		return new Promise((resolve, reject) => session.waiters.push({
+			resolve,
+			reject
+		}));
+	}
+	function suspend() {
+		flush();
+		suspended = true;
+	}
+	function resume() {
+		suspended = false;
+		if (active) renderView(active.view);
+	}
+	function destroy() {
+		if (destroyed) return;
+		flush();
+		for (const stop of stopWatching.splice(0)) stop();
+		clearTypingTimer();
+		onPageHide();
+		destroyed = true;
+		if (active) retire(active);
+		active = null;
+		stopRenewing();
+		if (typeof window !== "undefined") {
+			window.removeEventListener("pagehide", onPageHide);
+			window.removeEventListener("blur", flush);
+		}
+	}
+	return {
+		sessionId,
+		members,
+		locks,
+		connection,
+		revision,
+		canUndo,
+		canRedo,
+		attach,
+		undo: () => step("undo"),
+		redo: () => step("redo"),
+		clearHistory: () => {
+			if (!active) return;
+			active.undo = [];
+			active.redo = [];
+			bumpHistory();
+		},
+		flush,
+		settle,
+		suspend,
+		resume,
+		catchUp,
+		hasConfirmedBlock: (blockId) => active ? containsBlock(active.confirmed.blocks, blockId) : false,
+		applyOperations: applyFromTurn,
+		destroy
+	};
+}
+//#endregion
 //#region src/saved-blocks.ts
 /**
 * Reactive state over a {@link SavedBlocksProvider}.
@@ -1402,9 +2536,9 @@ function useCommentListener(options) {
 			}
 		});
 	}, { immediate: true });
-	onScopeDispose(stop);
+	onScopeDispose$1(stop);
 }
 //#endregion
-export { DEFAULT_AUTO_SAVE_DEBOUNCE_MS, createLocalStorageMediaProvider, createLocalStorageSavedBlocksProvider, useAutoSave, useBlockActions, useCommentListener, useComments, useConditionPreview, useDataSourceFetch, useEditor, useHistory, useHistoryInterceptor, useSavedBlocks, useVersionHistory };
+export { DEFAULT_AUTO_SAVE_DEBOUNCE_MS, createLocalStorageMediaProvider, createLocalStorageSavedBlocksProvider, diffContent, invertOperations, useAutoSave, useBlockActions, useCollaboration, useCommentListener, useComments, useConditionPreview, useDataSourceFetch, useEditor, useHistory, useHistoryInterceptor, useSavedBlocks, useVersionHistory };
 
 //# sourceMappingURL=index.js.map