@embedpdf/core 3.0.0-next.14 → 3.0.0-next.15

package/dist/settings-CMWFRjmQ.js

@@ -0,0 +1,1837 @@
+import { EngineError, encodePageKey, generateUuidV7, objectNumbersNamedBy, objectNumbersReferencedBy, pageRefsEqual } from "@embedpdf/engine-core/runtime";
+//#region src/types.ts
+/** Built-in token for the document registry capability (provided by the kernel). */
+const DocumentsToken = { name: "documents" };
+//#endregion
+//#region src/bursts.ts
+const txOf = (event) => "origin" in event ? event.origin.tx : void 0;
+function createBurstGate(store) {
+	let open = null;
+	const close = () => {
+		const held = open;
+		open = null;
+		held?.release();
+	};
+	return {
+		first(event) {
+			const tx = txOf(event);
+			if (open && open.id !== tx?.id) close();
+			if (!open && tx && tx.index === 0 && tx.count > 1) open = {
+				id: tx.id,
+				release: store.hold()
+			};
+		},
+		last(event) {
+			const tx = txOf(event);
+			if (open && tx?.id === open.id && tx.index === tx.count - 1) close();
+		},
+		close
+	};
+}
+//#endregion
+//#region src/scope.ts
+/**
+* A lifecycle operation was cancelled — the tab was closed mid-open, or the
+* kernel was destroyed mid-start. Not a failure: callers that race `open()`
+* against `close()` should treat this rejection as "the close won".
+*/
+var CancelledError = class extends Error {
+	constructor(what) {
+		super(`[kernel] cancelled: ${what}`);
+		this.name = "CancelledError";
+	}
+};
+const isCancelled = (error) => error instanceof CancelledError;
+function createScope(report) {
+	const teardowns = [];
+	let disposal = null;
+	return {
+		get disposed() {
+			return disposal !== null;
+		},
+		defer(teardown) {
+			if (disposal) disposal.then(() => Promise.resolve().then(teardown).catch(report));
+			else teardowns.push(teardown);
+		},
+		dispose() {
+			return disposal ?? (disposal = (async () => {
+				while (teardowns.length) try {
+					await teardowns.pop()();
+				} catch (error) {
+					report(error);
+				}
+			})());
+		}
+	};
+}
+//#endregion
+//#region src/errors.ts
+var PluginError = class extends Error {
+	constructor(code, capability, message, options = {}) {
+		super(message);
+		this.name = "PluginError";
+		if (options.cause !== void 0) this.cause = options.cause;
+		this.code = code;
+		this.capability = capability;
+		this.permission = options.permission ?? null;
+		this.details = options.details;
+	}
+};
+function toPluginErrorInfo(error) {
+	return {
+		code: error.code,
+		message: error.message,
+		capability: error.capability,
+		permission: error.permission
+	};
+}
+function isPluginError(value, code) {
+	if (!(value instanceof PluginError)) return false;
+	return code === void 0 || value.code === code;
+}
+const ENGINE_CODE_MAP = {
+	InvalidArg: "invalid-input",
+	MalformedPdf: "invalid-input",
+	PayloadTooLarge: "invalid-input",
+	WireFormat: "operation-failed",
+	DocNotOpen: "not-ready",
+	DocPasswordRequired: "permission-denied",
+	DocPasswordIncorrect: "permission-denied",
+	SharePasswordRequired: "permission-denied",
+	Unauthenticated: "permission-denied",
+	Forbidden: "permission-denied",
+	ProtectedDocument: "permission-denied",
+	NotFound: "not-found",
+	NotImplemented: "unsupported",
+	Aborted: "operation-cancelled",
+	LayerVersionConflict: "conflict",
+	StaleBase: "conflict",
+	SigningPending: "conflict",
+	SigningExpired: "conflict",
+	SigningVersionMismatch: "conflict",
+	ObjectNumberUnavailable: "conflict",
+	LayerFull: "conflict",
+	ChangeConflict: "conflict",
+	UndoUnavailable: "conflict",
+	IdempotencyKeyReused: "invalid-input"
+};
+/**
+* The permission an engine refusal names. `PermissionDenied` puts it in `details.required`
+* (the first of `details.anyOf` when any of several would have done), and `details` is what
+* survives the trip from a worker or the server, where the refusal arrives as a plain
+* `EngineError` with code `Forbidden`.
+*/
+function requiredPermissionOf(error) {
+	const required = error.details?.required;
+	return typeof required === "string" ? required : null;
+}
+/**
+* The one boundary mapping from whatever an engine call threw to a
+* `PluginError`. Idempotent: an existing PluginError passes through.
+* Cancellation (the kernel's CancelledError, a DOM AbortError, or an engine
+* abort) is `operation-cancelled`, never `operation-failed`, so callers can
+* tell "nobody wanted this anymore" from "this broke". A refusal names the
+* missing permission in `permission`; `details` keeps the rest of what the
+* engine sent (`anyOf`, `context`).
+*/
+function toPluginError(capability, error) {
+	if (error instanceof PluginError) return error;
+	if (isCancelled(error) || error instanceof Error && error.name === "AbortError") return new PluginError("operation-cancelled", capability, "operation cancelled", { cause: error });
+	if (EngineError.is(error)) {
+		const code = ENGINE_CODE_MAP[String(error.code)] ?? "operation-failed";
+		return new PluginError(code, capability, error.message, {
+			cause: error,
+			details: error.details,
+			permission: code === "permission-denied" ? requiredPermissionOf(error) : null
+		});
+	}
+	return new PluginError("operation-failed", capability, error instanceof Error ? error.message : String(error), { cause: error });
+}
+//#endregion
+//#region src/event-hook.ts
+/**
+* Create one capability event.
+*
+* Subscribe with `{ signal }` to tie the subscription to an AbortSignal; a
+* pre-aborted signal never registers.
+*
+* Delivery contract: synchronous fan-out over a snapshot of the listener set
+* (listeners added or removed during an emit don't affect that emit); a
+* throwing listener is isolated — reported through `onListenerError`, never
+* allowed to break the emitting operation or its sibling listeners. After
+* `dispose()`, `on` returns an inert unsubscribe (teardown races never throw).
+* No value cache, no replay, no equality — state belongs to the store.
+*/
+function createEventHook(onListenerError) {
+	let listeners = /* @__PURE__ */ new Set();
+	return {
+		on(listener, options) {
+			if (!listeners || options?.signal?.aborted) return () => {};
+			listeners.add(listener);
+			const off = () => void listeners?.delete(listener);
+			options?.signal?.addEventListener("abort", off, { once: true });
+			return off;
+		},
+		emit(event) {
+			if (!listeners) return;
+			for (const listener of [...listeners]) try {
+				listener(event);
+			} catch (error) {
+				onListenerError?.(error);
+			}
+		},
+		dispose() {
+			listeners = null;
+		}
+	};
+}
+//#endregion
+//#region src/changes.ts
+/**
+* The change queue (`ctx.changes`): one per open document, shared by every
+* plugin of it.
+*
+* A user action is one change: a list of the engine's ops, applied all or
+* nothing by `doc.apply`, sent as one request and undone as one step. A plugin
+* stages it; every mirror's `view()` shows it at once (`predict`, mirror.ts),
+* and the queue sends it after everything staged before it. The engine keeps
+* that order, and publishes a change's events before it answers.
+*
+* A change leaves the views once the engine answered:
+*   - applied: once each mirror holds the answer. A mirror that folded the
+*     events already does; one that asked to read again keeps showing the
+*     change until that read lands (mirror.ts).
+*   - refused: at once, together with the changes that name an object only it
+*     would have created (its dependents), which can't apply either.
+*
+* Two ways a change is put together over time:
+*   - a hold can still be amended before it is sent (typing, a form commit
+*     waiting for its scripts). Any later stage sends the open holds first, so
+*     send order is always staging order;
+*   - a group makes everything staged inside it, by any plugin, one change.
+*/
+const changeOf = (entry) => entry.undoOf !== null ? { undoOf: entry.undoOf } : { ops: entry.ops ?? [] };
+function createDocumentChanges(options) {
+	let entries = [];
+	let version = 0;
+	let nextSeq = 0;
+	let grouping = null;
+	let closed = false;
+	const staged = createEventHook(options.report);
+	const settled = createEventHook(options.report);
+	const handleFor = (capability) => {
+		const handle = options.handle();
+		if (!handle) throw new PluginError("not-ready", capability, "the document has not opened yet");
+		return handle;
+	};
+	const assertOpen = (capability) => {
+		if (closed) throw new PluginError("instance-closed", capability, "the document closed");
+	};
+	const changed = () => {
+		version += 1;
+		options.notify();
+	};
+	const createEntry = (init) => {
+		let resolve;
+		let reject;
+		const result = new Promise((onResolve, onReject) => {
+			resolve = onResolve;
+			reject = onReject;
+		});
+		result.catch(() => {});
+		return {
+			...init,
+			merge: init.merge ?? null,
+			seq: nextSeq++,
+			opId: generateUuidV7(),
+			result,
+			answered: false,
+			abort: null,
+			resolve,
+			reject
+		};
+	};
+	const remove = (entry) => {
+		entries = entries.filter((candidate) => candidate !== entry);
+	};
+	const applied = (entry, result) => {
+		if (entry.answered) return;
+		entry.answered = true;
+		remove(entry);
+		changed();
+		entry.resolve(result);
+		settled.emit({
+			change: entry,
+			status: "applied",
+			result
+		});
+	};
+	const refused = (entry, error) => {
+		if (entry.answered) return;
+		entry.answered = true;
+		remove(entry);
+		entry.reject(error);
+		settled.emit({
+			change: entry,
+			status: "refused",
+			error
+		});
+		refuseDependents(entry);
+		changed();
+	};
+	/** The changes staged after `entry` that name an object only it would have created. */
+	const refuseDependents = (entry) => {
+		const created = new Set(objectNumbersNamedBy(changeOf(entry)));
+		if (created.size === 0) return;
+		for (const later of entries) {
+			if (later.seq < entry.seq || later.answered) continue;
+			if (!objectNumbersReferencedBy(changeOf(later)).some((number) => created.has(number))) continue;
+			later.abort?.();
+			refused(later, new PluginError("conflict", later.capability, `a change it depends on (${entry.label.key}) was refused`, { details: {
+				reason: "dependency-refused",
+				dependsOn: entry.opId
+			} }));
+		}
+	};
+	const send = (entry) => {
+		entry.held = false;
+		let answer;
+		try {
+			answer = handleFor(entry.capability).apply(changeOf(entry), { opId: entry.opId });
+		} catch (error) {
+			refused(entry, toPluginError(entry.capability, error));
+			return;
+		}
+		if (typeof answer.abort === "function") entry.abort = (reason) => answer.abort(reason);
+		answer.then((result) => applied(entry, result), (error) => refused(entry, toPluginError(entry.capability, error)));
+	};
+	const cancel = (entry, capability) => {
+		if (entry.answered) return;
+		entry.answered = true;
+		remove(entry);
+		entry.reject(new PluginError("operation-cancelled", capability, "the change was cancelled"));
+		changed();
+	};
+	/** Send the open holds staged before `before`, in staging order. */
+	const sendHolds = (before = Infinity) => {
+		for (const entry of entries) {
+			if (!entry.held || entry.seq >= before) continue;
+			if ((entry.ops ?? []).length === 0) {
+				cancel(entry, entry.capability);
+				continue;
+			}
+			staged.emit(entry);
+			send(entry);
+		}
+	};
+	const invalid = (capability, message) => new PluginError("invalid-input", capability, message);
+	/** One stage inside a group: its ops join the group's change. */
+	const join = (group, change) => {
+		const entry = group.entry;
+		if (!entry) {
+			group.entry = createEntry({
+				label: group.label,
+				ops: change.ops,
+				undoOf: null,
+				shows: change.ops,
+				undo: change.undo ?? [],
+				history: change.history !== false,
+				held: false,
+				capability: group.capability
+			});
+			entries.push(group.entry);
+			changed();
+			return group.entry;
+		}
+		entry.ops = [...entry.ops ?? [], ...change.ops];
+		entry.shows = entry.ops;
+		entry.undo = [...change.undo ?? [], ...entry.undo];
+		entry.history = entry.history || change.history !== false;
+		changed();
+		return entry;
+	};
+	const forPlugin = (capability) => ({
+		stage(change) {
+			assertOpen(capability);
+			if ("undoOf" in change) {
+				if (grouping) throw invalid(capability, "an undo can not join a group");
+			} else if (change.ops.length === 0) throw invalid(capability, "a change needs at least one op");
+			else if (grouping) return join(grouping, change);
+			sendHolds();
+			const entry = "undoOf" in change ? createEntry({
+				label: change.label,
+				ops: null,
+				undoOf: change.undoOf,
+				shows: change.shows,
+				undo: [],
+				history: false,
+				held: false,
+				capability
+			}) : createEntry({
+				label: change.label,
+				ops: change.ops,
+				undoOf: null,
+				shows: change.ops,
+				undo: change.undo ?? [],
+				history: change.history !== false,
+				held: false,
+				capability
+			});
+			entries.push(entry);
+			changed();
+			staged.emit(entry);
+			send(entry);
+			return entry;
+		},
+		hold(label, options = {}) {
+			assertOpen(capability);
+			if (grouping) throw invalid(capability, "a change can not be held inside a group");
+			let entry = null;
+			let cancelled = false;
+			const open = () => !closed && !cancelled && (entry === null || entry.held && !entry.answered);
+			return {
+				get open() {
+					return open();
+				},
+				get change() {
+					return entry;
+				},
+				set(ops, undo = []) {
+					if (!open()) return;
+					if (!entry) {
+						entry = createEntry({
+							label,
+							ops,
+							undoOf: null,
+							merge: options.merge ?? null,
+							shows: ops,
+							undo,
+							history: true,
+							held: true,
+							capability
+						});
+						entries.push(entry);
+					} else {
+						entry.ops = ops;
+						entry.shows = ops;
+						entry.undo = undo;
+					}
+					changed();
+				},
+				send() {
+					if (entry?.held) sendHolds(entry.seq + 1);
+					return entry;
+				},
+				cancel() {
+					cancelled = true;
+					if (entry?.held) cancel(entry, capability);
+				}
+			};
+		},
+		group(label, run) {
+			assertOpen(capability);
+			if (grouping) return run();
+			sendHolds();
+			const group = {
+				label,
+				capability,
+				entry: null
+			};
+			grouping = group;
+			let value;
+			try {
+				value = run();
+			} catch (error) {
+				grouping = null;
+				if (group.entry) cancel(group.entry, capability);
+				throw error;
+			}
+			grouping = null;
+			if (group.entry) {
+				staged.emit(group.entry);
+				send(group.entry);
+			}
+			return value;
+		},
+		sendHolds: () => sendHolds(),
+		takeObjectNumber: () => handleFor(capability).objectNumbers.take(),
+		async reserveObjectNumbers(count) {
+			try {
+				await handleFor(capability).objectNumbers.reserve(count);
+			} catch (error) {
+				throw toPluginError(capability, error);
+			}
+		},
+		pending: () => entries,
+		hasPending: () => entries.length > 0,
+		whenSettled: () => whenSettled(),
+		onStaged: staged.on,
+		onSettled: settled.on
+	});
+	const whenSettled = async () => {
+		await Promise.allSettled(entries.filter((entry) => !entry.held).map((entry) => entry.result));
+	};
+	return {
+		shown: () => entries,
+		version: () => version,
+		find: (opId) => entries.find((entry) => entry.opId === opId),
+		forPlugin,
+		settle() {
+			sendHolds();
+			return whenSettled();
+		},
+		close() {
+			if (closed) return;
+			closed = true;
+			const open = entries;
+			entries = [];
+			version += 1;
+			for (const entry of open) {
+				entry.answered = true;
+				entry.reject(new PluginError("instance-closed", entry.capability, "the document closed"));
+			}
+			staged.dispose();
+			settled.dispose();
+		}
+	};
+}
+//#endregion
+//#region src/clock.ts
+/** Timers only, no frames: the kernel's default. */
+const timerClock = {
+	now: () => performance.now(),
+	after(ms, run) {
+		const timer = setTimeout(run, ms);
+		return () => clearTimeout(timer);
+	}
+};
+/**
+* The clock of one plugin instance, over the host's. What it schedules is
+* cancelled when `lifetime` aborts (the instance closes), and nothing it
+* schedules after that runs.
+*/
+function instanceClock(host, lifetime) {
+	const pending = /* @__PURE__ */ new Set();
+	lifetime.addEventListener("abort", () => {
+		for (const cancel of [...pending]) cancel();
+	}, { once: true });
+	/** Schedules `run` with the host and keeps it until it runs or is cancelled. */
+	const own = (schedule, run) => {
+		if (lifetime.aborted) return () => {};
+		let done = false;
+		let cancelWithHost = () => {};
+		const cancel = () => {
+			if (done) return;
+			done = true;
+			pending.delete(cancel);
+			cancelWithHost();
+		};
+		pending.add(cancel);
+		cancelWithHost = schedule((...args) => {
+			if (done) return;
+			done = true;
+			pending.delete(cancel);
+			run(...args);
+		});
+		return cancel;
+	};
+	const nextFrameOfHost = (run) => host.nextFrame ? host.nextFrame(run) : host.after(0, () => run(host.now()));
+	return {
+		after: (ms, run) => own((fire) => host.after(ms, fire), run),
+		nextFrame: (run) => own(nextFrameOfHost, run),
+		hasFrames: host.nextFrame !== void 0
+	};
+}
+//#endregion
+//#region src/store.ts
+function createStore(report = console.error) {
+	let core = {
+		documents: {},
+		pending: {},
+		order: [],
+		activeId: null
+	};
+	/** Live slice states, as adapters read them (`getState().plugins`). */
+	const states = {};
+	const leases = /* @__PURE__ */ new Map();
+	const changeListeners = /* @__PURE__ */ new Set();
+	let leaseCounter = 0;
+	const guarded = (fn) => {
+		try {
+			fn();
+		} catch (error) {
+			report(error);
+		}
+	};
+	let emitting = false;
+	let pending = false;
+	let holds = 0;
+	let missed = false;
+	const emitChange = () => {
+		if (holds > 0) {
+			missed = true;
+			return;
+		}
+		if (emitting) {
+			pending = true;
+			return;
+		}
+		emitting = true;
+		try {
+			do {
+				pending = false;
+				changeListeners.forEach((listener) => guarded(listener));
+			} while (pending);
+		} finally {
+			emitting = false;
+		}
+	};
+	function lease(key, initial, instanceId = `${key}#${++leaseCounter}`) {
+		leases.get(key)?.revoke();
+		const cell = {
+			live: true,
+			state: initial
+		};
+		const changed = createEventHook(report);
+		states[key] = initial;
+		const handle = {
+			key,
+			instanceId,
+			get live() {
+				return cell.live;
+			},
+			read: () => cell.state,
+			write(next) {
+				if (!cell.live) return false;
+				if (next === cell.state) return true;
+				const previous = cell.state;
+				cell.state = next;
+				states[key] = next;
+				emitChange();
+				changed.emit({
+					next,
+					previous
+				});
+				return true;
+			},
+			onChange: changed.on,
+			revoke() {
+				if (!cell.live) return;
+				cell.live = false;
+				changed.dispose();
+				if (leases.get(key) === handle) {
+					leases.delete(key);
+					delete states[key];
+					emitChange();
+				}
+			}
+		};
+		leases.set(key, handle);
+		return handle;
+	}
+	return {
+		lease,
+		getCore: () => core,
+		getState: () => ({
+			core,
+			plugins: states
+		}),
+		setCore(patch) {
+			core = {
+				...core,
+				...patch
+			};
+			emitChange();
+		},
+		notify: () => emitChange(),
+		hold() {
+			holds += 1;
+			let released = false;
+			return () => {
+				if (released) return;
+				released = true;
+				holds -= 1;
+				if (holds > 0 || !missed) return;
+				missed = false;
+				emitChange();
+			};
+		},
+		subscribe(listener) {
+			changeListeners.add(listener);
+			return () => void changeListeners.delete(listener);
+		},
+		destroy() {
+			core = {
+				documents: {},
+				pending: {},
+				order: [],
+				activeId: null
+			};
+			for (const held of [...leases.values()]) held.revoke();
+			for (const key of Object.keys(states)) delete states[key];
+			changeListeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/env.ts
+function isDev() {
+	try {
+		return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/guarded-handle.ts
+const isPromiseLike = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+const isPlainWrappable = (value) => value !== null && typeof value === "object" && !isPromiseLike(value) && !(value instanceof ArrayBuffer) && !ArrayBuffer.isView(value) && !(value instanceof Date) && !(value instanceof RegExp) && !(value instanceof Map) && !(value instanceof Set) && !Array.isArray(value);
+/**
+* The guarded document handle a controller sees as `ctx.doc`. Every call made
+* through it is:
+*
+*   - refused (rejected `instance-closed`) once the instance has closed,
+*   - raced against the instance lifetime: a call that is still pending when
+*     the instance closes rejects `instance-closed`, its late value is dropped,
+*     and an abortable engine call is aborted so worker-side work stops,
+*   - mapped through `toPluginError`, so a controller sees one error vocabulary.
+*
+* Nested service objects (`doc.annotations`, `doc.page(ref).render`) are
+* wrapped lazily and cached; synchronous reads (`doc.security.allows`) pass
+* straight through. Methods run with the raw target as `this`, so classes
+* with private fields keep working. The returned promises keep an `abort()`
+* when the engine's promise had one, so caller-side cancellation still works.
+*/
+function guardHandle(handle, lifetime, capability) {
+	const cache = /* @__PURE__ */ new WeakMap();
+	const closedError = () => new PluginError("instance-closed", capability, `document instance ${lifetime.instanceId} was closed`);
+	const guardPromise = (pending) => {
+		const abortable = pending;
+		const guarded = new Promise((resolve, reject) => {
+			const onAbort = () => {
+				abortable.abort?.(lifetime.signal.reason);
+				reject(closedError());
+			};
+			if (lifetime.signal.aborted) onAbort();
+			else lifetime.signal.addEventListener("abort", onAbort, { once: true });
+			Promise.resolve(pending).then((value) => {
+				lifetime.signal.removeEventListener("abort", onAbort);
+				if (!lifetime.signal.aborted) resolve(value);
+			}, (error) => {
+				lifetime.signal.removeEventListener("abort", onAbort);
+				if (!lifetime.signal.aborted) reject(toPluginError(capability, error));
+			});
+		});
+		if (typeof abortable.abort === "function") Object.defineProperty(guarded, "abort", {
+			value: (reason) => abortable.abort(reason),
+			enumerable: false
+		});
+		return guarded;
+	};
+	const wrapFunction = (fn, target) => function guardedCall(...args) {
+		let result;
+		try {
+			result = fn.apply(target, args);
+		} catch (error) {
+			throw toPluginError(capability, error);
+		}
+		if (isPromiseLike(result)) return guardPromise(result);
+		return wrapValue(result, target);
+	};
+	const wrapValue = (value, target) => {
+		if (typeof value === "function") return wrapFunction(value, target);
+		if (isPlainWrappable(value)) return wrapObject(value);
+		return value;
+	};
+	const wrapObject = (target) => {
+		let proxy = cache.get(target);
+		if (!proxy) {
+			proxy = new Proxy(target, { get(proxyTarget, property) {
+				return wrapValue(Reflect.get(proxyTarget, property, proxyTarget), proxyTarget);
+			} });
+			cache.set(target, proxy);
+		}
+		return proxy;
+	};
+	return wrapObject(handle);
+}
+//#endregion
+//#region src/lanes.ts
+function createLatestLane(lifetime, capability, name) {
+	let generation = 0;
+	let active = null;
+	const closed = () => new PluginError("instance-closed", capability, `${name}: instance closed`);
+	const cancelled = (id, why) => new PluginError("operation-cancelled", capability, `${name}: ${why}`, { details: {
+		runId: id,
+		reason: why
+	} });
+	return {
+		get running() {
+			return active !== null;
+		},
+		cancel(reason) {
+			active?.abort(reason ?? "cancelled");
+			active = null;
+		},
+		async run(fn, options) {
+			if (lifetime.aborted) throw closed();
+			if (options?.signal?.aborted) throw cancelled(`${name}#${generation + 1}`, "cancelled before start");
+			const mine = ++generation;
+			const id = `${name}#${mine}`;
+			const controller = new AbortController();
+			const previous = active;
+			active = controller;
+			const onLifetime = () => controller.abort("instance-closed");
+			const onCaller = () => controller.abort("cancelled");
+			lifetime.addEventListener("abort", onLifetime, { once: true });
+			options?.signal?.addEventListener("abort", onCaller, { once: true });
+			const current = () => mine === generation && !controller.signal.aborted;
+			const run = {
+				id,
+				signal: controller.signal,
+				get superseded() {
+					return mine !== generation;
+				},
+				commit(commitFn) {
+					if (!current()) return false;
+					commitFn();
+					return true;
+				}
+			};
+			try {
+				previous?.abort("superseded");
+				if (!current()) throw cancelled(id, "superseded");
+				const value = await fn(run);
+				if (!current()) throw cancelled(id, String(controller.signal.reason ?? "superseded"));
+				return value;
+			} catch (error) {
+				if (lifetime.aborted) throw closed();
+				if (!current()) throw cancelled(id, String(controller.signal.reason ?? "superseded"));
+				throw toPluginError(capability, error);
+			} finally {
+				lifetime.removeEventListener("abort", onLifetime);
+				options?.signal?.removeEventListener("abort", onCaller);
+				if (active === controller) active = null;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/mirror.ts
+const RELOAD = Symbol("mirror.reload");
+/** Ask the mirror to reload instead of applying the event. */
+function reload(options) {
+	return { [RELOAD]: options?.pages ?? "all" };
+}
+const isReload = (value) => typeof value === "object" && value !== null && RELOAD in value;
+/** Events that invalidate every mirror: the stream skipped events, or the document moved to new bytes. */
+const isResync = (event) => event.type === "stream.desynced" || event.type === "document.versioned";
+const statusOfFailure = (error) => isPluginError(error, "permission-denied") ? "forbidden" : "error";
+/** The `opId` of the change an event belongs to, or null for an event of none. */
+const changeIdOf = (event) => "origin" in event ? event.origin.tx?.id ?? null : null;
+/** The `opId` of the change whose last event this is, or null. */
+const lastEventOf = (event) => {
+	const tx = "origin" in event ? event.origin.tx : void 0;
+	return tx && tx.index === tx.count - 1 ? tx.id : null;
+};
+/**
+* The changes of this session whose events a mirror folded, every one of
+* them: the mirror holds their answer, so its view stops replaying them, even
+* before the answer itself arrives. An entry goes once its change left the
+* queue.
+*/
+function createFoldedChanges(changes) {
+	const folded = /* @__PURE__ */ new Set();
+	return {
+		has: (opId) => folded.has(opId),
+		/** The event folded: when it was a change's last, the change is held. True when that's new. */
+		add(event) {
+			const opId = lastEventOf(event);
+			if (opId === null || folded.has(opId) || !changes.find(opId)) return false;
+			for (const each of folded) if (!changes.find(each)) folded.delete(each);
+			folded.add(opId);
+			return true;
+		}
+	};
+}
+/**
+* The changes a view shows: the queue's, but those whose events the mirror
+* folded already, and the answered ones a mirror keeps (it asked to read
+* again), each once.
+*/
+function showingWith(changes, kept, folded) {
+	const shown = new Map(changes.shown().filter((change) => !folded.has(change.opId)).map((change) => [change.opId, change]));
+	for (const { change } of kept) shown.set(change.opId, change);
+	return [...shown.values()];
+}
+/**
+* Replay changes over a value, in staging order: the shown ones and the
+* answered ones a mirror still shows. A `predict` that throws is reported,
+* and the value shows the truth.
+*/
+function replay(value, changes, predict, report) {
+	const ordered = [...changes].sort((left, right) => left.seq - right.seq);
+	let next = value;
+	try {
+		for (const change of ordered) for (const op of change.shows) next = predict(next, op);
+	} catch (error) {
+		report(error);
+		return value;
+	}
+	return next;
+}
+function createMirror(spec, env) {
+	const cell = env.cell(`mirror/${spec.name}`, {
+		value: spec.initial(),
+		status: "idle"
+	});
+	let started = false;
+	let running = null;
+	const pageReloads = /* @__PURE__ */ new Set();
+	let loadAgain = false;
+	/** Non-null while a full load runs: the events to replay after it lands. */
+	let queued = null;
+	/** How many full loads have started: a load clears what was kept before it started. */
+	let fullLoads = 0;
+	/**
+	* Changes this mirror still shows though the engine may have answered them: a
+	* fold asked to read again, and the read hasn't landed. `after`: the full
+	* loads started before; a later full load that lands holds the change too.
+	*/
+	const kept = /* @__PURE__ */ new Map();
+	let keptVersion = 0;
+	const folded = createFoldedChanges(env.changes);
+	/** Keep the change an event belongs to until a read lands, when it's one of ours. */
+	const keepUntilRead = (event, after) => {
+		const opId = changeIdOf(event);
+		const change = opId !== null && spec.predict ? env.changes.find(opId) : void 0;
+		if (!change) return null;
+		kept.set(change.opId, {
+			change,
+			after
+		});
+		keptVersion += 1;
+		return change.opId;
+	};
+	const release = (opIds) => {
+		let any = false;
+		for (const opId of opIds) any = kept.delete(opId) || any;
+		if (!any) return;
+		keptVersion += 1;
+		env.notify();
+	};
+	const releaseLoadedBy = (load) => release([...kept].filter(([, entry]) => entry.after < load).map(([opId]) => opId));
+	let viewMemo = null;
+	const view = () => {
+		const value = cell.read().value;
+		if (!spec.predict) return value;
+		const version = env.changes.version();
+		if (viewMemo && viewMemo.value === value && viewMemo.version === version && viewMemo.kept === keptVersion) return viewMemo.view;
+		const next = replay(value, showingWith(env.changes, kept.values(), folded), spec.predict, env.report);
+		viewMemo = {
+			value,
+			version,
+			kept: keptVersion,
+			view: next
+		};
+		return next;
+	};
+	const announce = (change) => {
+		try {
+			spec.changed?.(change);
+		} catch (error) {
+			env.report(error);
+		}
+	};
+	const commit = (next, change) => {
+		const previous = cell.read().value;
+		if (next === previous) return;
+		if (!cell.write({
+			...cell.read(),
+			value: next
+		})) return;
+		announce({
+			...change,
+			previous,
+			next
+		});
+	};
+	const reloadInBackground = () => {
+		refresh().catch(() => {});
+	};
+	const reloadPages = async (pages, keptFor) => {
+		try {
+			const merge = await spec.loadPages(env.doc, pages, env.lifetime);
+			if (!cell.live) return;
+			const previous = cell.read().value;
+			const next = merge(previous);
+			cell.write({
+				...cell.read(),
+				value: next
+			});
+			announce({
+				cause: "load",
+				event: null,
+				pages,
+				previous,
+				next
+			});
+			if (keptFor !== null) release([keptFor]);
+		} catch (error) {
+			if (isPluginError(error, "instance-closed") || !cell.live) return;
+			cell.write({
+				...cell.read(),
+				status: statusOfFailure(error)
+			});
+			env.report(error);
+		}
+	};
+	const applyEvent = (event) => {
+		let result;
+		try {
+			result = spec.fold(cell.read().value, event);
+		} catch (error) {
+			env.report(error);
+			if (!spec.onDemand || started) reloadInBackground();
+			return;
+		}
+		if (isReload(result)) {
+			if (spec.onDemand && !started) return;
+			const pages = result[RELOAD];
+			const keptFor = keepUntilRead(event, fullLoads);
+			if (pages === "all" || !spec.loadPages) reloadInBackground();
+			else {
+				const reloading = reloadPages(pages, keptFor).finally(() => pageReloads.delete(reloading));
+				pageReloads.add(reloading);
+			}
+			return;
+		}
+		if (spec.predict && folded.add(event)) keptVersion += 1;
+		commit(result, {
+			cause: "event",
+			event,
+			pages: null
+		});
+	};
+	env.onDocumentEvent((event) => {
+		if (!cell.live) return;
+		if (isResync(event)) {
+			if (started) reloadInBackground();
+			return;
+		}
+		if (queued) {
+			queued.push(event);
+			keepUntilRead(event, fullLoads - 1);
+		} else applyEvent(event);
+	});
+	const loadOnce = async () => {
+		if (spec.readable && !spec.readable()) {
+			cell.write({
+				...cell.read(),
+				status: "forbidden"
+			});
+			return;
+		}
+		if (cell.read().status !== "ready") cell.write({
+			...cell.read(),
+			status: "loading"
+		});
+		const load = ++fullLoads;
+		queued = [];
+		let loaded;
+		try {
+			loaded = await spec.load(env.doc, env.lifetime);
+		} catch (error) {
+			const pending = queued ?? [];
+			queued = null;
+			if (!cell.live || isPluginError(error, "instance-closed")) return;
+			cell.write({
+				...cell.read(),
+				status: statusOfFailure(error)
+			});
+			for (const event of pending) applyEvent(event);
+			throw error;
+		}
+		const pending = queued ?? [];
+		queued = null;
+		if (!cell.live) return;
+		const previous = cell.read().value;
+		cell.write({
+			value: loaded.value,
+			status: "ready"
+		});
+		announce({
+			cause: "load",
+			event: null,
+			pages: "all",
+			previous,
+			next: loaded.value
+		});
+		const cursor = loaded.cursor ?? null;
+		for (const event of pending) {
+			const serverId = "origin" in event ? event.origin.serverId : null;
+			if (cursor !== null && serverId !== null && serverId <= cursor) continue;
+			applyEvent(event);
+		}
+		releaseLoadedBy(load);
+	};
+	function refresh() {
+		started = true;
+		if (running) {
+			loadAgain = true;
+			return running;
+		}
+		running = (async () => {
+			let failure = null;
+			do {
+				loadAgain = false;
+				try {
+					await loadOnce();
+					failure = null;
+				} catch (error) {
+					failure = error;
+				}
+			} while (loadAgain && cell.live);
+			if (failure !== null) throw failure;
+		})().finally(() => {
+			running = null;
+		});
+		return running;
+	}
+	return {
+		mirror: {
+			get: () => cell.read().value,
+			view,
+			getStatus: () => cell.read().status,
+			ensureLoaded: () => {
+				if (running) return running;
+				if (cell.read().status === "ready") return Promise.resolve();
+				return refresh();
+			},
+			refresh,
+			async settled() {
+				while (running || pageReloads.size > 0) await Promise.allSettled([running, ...pageReloads]);
+			}
+		},
+		start() {
+			if (!started && !spec.onDemand) reloadInBackground();
+		}
+	};
+}
+//#endregion
+//#region src/page-mirror.ts
+/**
+* Page mirrors: engine data that is loaded page by page, on demand, and kept
+* current from the document event stream.
+*
+* A page is `idle` until something calls `ensureLoaded(page)`. Once loaded it
+* stays current: an event the spec maps to that page either folds into the
+* page's value or re-reads it. Every read carries a per-page epoch, so a read
+* that started before a newer one can never overwrite it. Loads for the same
+* page are shared while in flight. Deleted pages are dropped, and
+* `stream.desynced` / `document.versioned` re-read every loaded page.
+*
+* `view(page)` is the page's value with this session's pending changes on
+* top (`predict`), as for whole-document mirrors (mirror.ts): an answered
+* change that made a page read again stays in that page's view until the
+* read lands.
+*/
+const IDLE = "idle";
+function createPageMirror(spec, env) {
+	const cell = env.cell(`page-mirror/${spec.name}`, {});
+	const epochs = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	/**
+	* Per page: answered changes the page still shows, because an event of
+	* theirs made it read again. `epoch`: the page's epoch then; a later read
+	* that lands clears them.
+	*/
+	const kept = /* @__PURE__ */ new Map();
+	let keptVersion = 0;
+	/** Changes every event of which reached the pages: each page holds its part, or keeps the change. */
+	const folded = createFoldedChanges(env.changes);
+	const keepUntilRead = (key, event) => {
+		const opId = changeIdOf(event);
+		const change = opId !== null && spec.predict ? env.changes.find(opId) : void 0;
+		if (!change) return;
+		let page = kept.get(key);
+		if (!page) kept.set(key, page = /* @__PURE__ */ new Map());
+		page.set(change.opId, {
+			change,
+			epoch: epochs.get(key) ?? 0
+		});
+		keptVersion += 1;
+	};
+	const releasePage = (key, epoch) => {
+		const page = kept.get(key);
+		if (!page) return;
+		const before = page.size;
+		for (const [opId, entry] of page) if (entry.epoch < epoch) page.delete(opId);
+		if (page.size === 0) kept.delete(key);
+		if (page.size === before) return;
+		keptVersion += 1;
+		env.notify();
+	};
+	const views = /* @__PURE__ */ new Map();
+	const view = (page) => {
+		const key = encodePageKey(page);
+		const value = entryOf(key)?.value;
+		if (value === void 0 || !spec.predict) return value;
+		const version = env.changes.version();
+		const memo = views.get(key);
+		if (memo && memo.value === value && memo.version === version && memo.kept === keptVersion) return memo.view;
+		const predict = spec.predict;
+		const next = replay(value, showingWith(env.changes, kept.get(key)?.values() ?? [], folded), (current, op) => predict(current, op, page), env.report);
+		views.set(key, {
+			value,
+			version,
+			kept: keptVersion,
+			view: next
+		});
+		return next;
+	};
+	const entryOf = (key) => cell.read()[key];
+	const setEntry = (key, entry) => {
+		const { [key]: _replaced, ...rest } = cell.read();
+		return cell.write(entry ? {
+			...rest,
+			[key]: entry
+		} : rest);
+	};
+	const announce = (change) => {
+		if (change.cause !== "load" && change.previous === change.next) return;
+		try {
+			spec.changed?.(change);
+		} catch (error) {
+			env.report(error);
+		}
+	};
+	const load = (page) => {
+		const key = encodePageKey(page);
+		const epoch = (epochs.get(key) ?? 0) + 1;
+		epochs.set(key, epoch);
+		const before = entryOf(key);
+		if (before?.status !== "ready") setEntry(key, {
+			page,
+			status: "loading",
+			value: before?.value
+		});
+		const isCurrent = () => cell.live && epochs.get(key) === epoch;
+		const request = spec.load(env.doc, page, env.lifetime).then((value) => {
+			if (!isCurrent()) return;
+			const previous = entryOf(key)?.value;
+			setEntry(key, {
+				page,
+				status: "ready",
+				value
+			});
+			announce({
+				page,
+				cause: "load",
+				event: null,
+				previous,
+				next: value
+			});
+			if (kept.has(key)) releasePage(key, epoch);
+		}, (error) => {
+			if (!isCurrent() || isPluginError(error, "instance-closed")) return;
+			setEntry(key, {
+				page,
+				status: statusOfFailure(error),
+				value: entryOf(key)?.value
+			});
+			throw error;
+		}).finally(() => {
+			if (inFlight.get(key) === request) inFlight.delete(key);
+		});
+		inFlight.set(key, request);
+		return request;
+	};
+	const reloadInBackground = (page) => {
+		load(page).catch(() => {});
+	};
+	const loadedPages = () => Object.values(cell.read()).filter((entry) => entry.status !== IDLE).map((entry) => entry.page);
+	env.onDocumentEvent((event) => {
+		if (!cell.live) return;
+		foldEvent(event);
+		if (spec.predict && folded.add(event)) keptVersion += 1;
+	});
+	/** One event, into every loaded page it concerns. */
+	function foldEvent(event) {
+		if (isResync(event)) {
+			for (const page of loadedPages()) reloadInBackground(page);
+			return;
+		}
+		if (event.type === "pages.deleted") {
+			for (const page of event.pages) {
+				const key = encodePageKey(page);
+				const before = entryOf(key);
+				if (!before) continue;
+				epochs.set(key, (epochs.get(key) ?? 0) + 1);
+				kept.delete(key);
+				views.delete(key);
+				setEntry(key, null);
+				announce({
+					page,
+					cause: "drop",
+					event,
+					previous: before.value,
+					next: void 0
+				});
+			}
+			return;
+		}
+		const affected = spec.affected(event);
+		if (affected === null) return;
+		const pages = affected === "all" ? loadedPages() : affected;
+		for (const page of pages) {
+			const key = encodePageKey(page);
+			const entry = entryOf(key);
+			if (!entry || entry.status === IDLE) continue;
+			if (!spec.fold || entry.status !== "ready") {
+				keepUntilRead(key, event);
+				reloadInBackground(page);
+				continue;
+			}
+			let next;
+			try {
+				next = spec.fold(entry.value, event, page);
+			} catch (error) {
+				env.report(error);
+				next = "reload";
+			}
+			if (next === "reload") {
+				keepUntilRead(key, event);
+				reloadInBackground(page);
+				continue;
+			}
+			if (next === entry.value) continue;
+			epochs.set(key, (epochs.get(key) ?? 0) + 1);
+			setEntry(key, {
+				page,
+				status: "ready",
+				value: next
+			});
+			announce({
+				page,
+				cause: "event",
+				event,
+				previous: entry.value,
+				next
+			});
+		}
+	}
+	return {
+		get: (page) => entryOf(encodePageKey(page))?.value,
+		view,
+		getStatus: (page) => entryOf(encodePageKey(page))?.status ?? IDLE,
+		ensureLoaded(page) {
+			const key = encodePageKey(page);
+			const running = inFlight.get(key);
+			if (running) return running;
+			if (entryOf(key)?.status === "ready") return Promise.resolve();
+			return load(page);
+		},
+		refresh(page) {
+			if (page) return load(page);
+			return Promise.all(loadedPages().map((loaded) => load(loaded))).then(() => void 0);
+		}
+	};
+}
+//#endregion
+//#region src/serial-queue.ts
+/** `capability` names the plugin in the error a skipped operation rejects with. */
+function createSerialQueue(capability) {
+	let tail = Promise.resolve();
+	const queue = (operation, options) => {
+		const start = () => options?.signal?.aborted ? Promise.reject(new PluginError("operation-cancelled", capability, "cancelled before it started", { cause: options.signal.reason })) : operation();
+		const result = tail.then(start, start);
+		tail = result.then(() => void 0, () => void 0);
+		return result;
+	};
+	return Object.assign(queue, { idle: () => tail });
+}
+//#endregion
+//#region src/cancellable.ts
+/**
+* What `ctx.cancellable` does: race an engine call against the caller's
+* signal. When the signal fires, the call is aborted, so the worker or the
+* server stops working on it (an `AbortablePromise`, and a call made through
+* the guarded `ctx.doc`, carry `abort()`), and the returned promise rejects
+* `operation-cancelled` at once instead of waiting for the engine to notice.
+* The guarded handle does the same for the instance's lifetime
+* (guarded-handle.ts). A signal that fires after the call settled changes
+* nothing.
+*/
+function cancellable(capability, signal, task) {
+	if (!signal) return task;
+	const abortable = task;
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			abortable.abort?.(signal.reason);
+			reject(new PluginError("operation-cancelled", capability, "operation cancelled", { cause: signal.reason }));
+		};
+		task.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(toPluginError(capability, error));
+		});
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+//#region src/page-of.ts
+/**
+* A page argument as plugins take it, a `PageRef` or a zero-based index into
+* the document's page list (display order), looked up two ways. A read asks
+* {@link findPage} and gets null for a page that isn't there: reads run while
+* rendering, and a page deleted mid-render must not break a layer. A verb asks
+* {@link pageOf}, which refuses with `not-found`.
+*/
+/** What `ctx.getPage` reads: the page `page` names in `pages`, or null. */
+function findPage(pages, page) {
+	if (typeof page === "number") return pages[page] ?? null;
+	return pages.find((pageInfo) => pageRefsEqual(pageInfo.ref, page)) ?? null;
+}
+/** What `ctx.pageOf` resolves: the page `page` names in `pages`. Throws `not-found` when there is none. */
+function pageOf(pages, page, capability) {
+	const found = findPage(pages, page);
+	if (found) return found;
+	throw new PluginError("not-found", capability, typeof page === "number" ? `there is no page ${page} in this document` : `page ${page.objectNumber} is not in this document`);
+}
+//#endregion
+//#region src/permissions.ts
+/**
+* What `ctx.allows` reads: the document session's own predicates, the ones the
+* engine enforces with, so a control gated on the answer never disagrees with
+* what the verb then does.
+*/
+function sessionAllows(security, permission) {
+	return permission === "annotations:create" ? security.allowsAnnotation("create") : security.allows(permission);
+}
+/** What `ctx.assertAllowed` throws: a refusal that names what was missing. */
+function permissionDenied(capability, permission, operation) {
+	return new PluginError("permission-denied", capability, `${operation} requires ${permission}`, { permission });
+}
+/**
+* What a plugin throws for a form field the session may not fill in or sign:
+* a refusal that names the permission it would take, as the engine's does
+* (`fields:<action>:group=<group>`, or the broad one for a field in no group).
+*/
+function fieldPermissionDenied(capability, action, field, operation) {
+	const permission = field.groupId !== null ? `fields:${action}:group=${field.groupId}` : action === "fill" ? "doc.forms.fill" : "doc.sign";
+	return new PluginError("permission-denied", capability, `${operation} requires ${permission}`, { permission });
+}
+//#endregion
+//#region src/context.ts
+/** A plugin's slice key. Workspace plugins use their id; document-scoped plugins are per-document. */
+const sliceKey = (pluginId, documentId) => documentId ? `${pluginId}::${documentId}` : pluginId;
+/** `read`, inside every wrap: the first registered is the outermost. */
+const readWrapped = (wraps, read) => wraps.reduceRight((inner, wrap) => () => wrap(inner), read)();
+/**
+* The tokens a plugin may resolve: its declared `requires` and `optional`, its
+* own token, and the always-available documents token. Resolving anything else
+* is a lie in the dependency graph (the kernel cannot order or validate what it
+* does not know about), so in development it throws with the remedy.
+*/
+function declaredTokens(plugin) {
+	const declared = /* @__PURE__ */ new Set([
+		DocumentsToken,
+		...plugin.requires ?? [],
+		...plugin.optional ?? []
+	]);
+	if (plugin.token) declared.add(plugin.token);
+	return declared;
+}
+const connectedHooks = /* @__PURE__ */ new WeakMap();
+/** Kernel-side: the plugin's `connect` ran; start what waits for it (mirror loads). */
+function markConnected(context) {
+	connectedHooks.get(context)?.();
+}
+/**
+* Build the context a plugin's `create()` receives. With a `session` the
+* context is bound to that document: its state slice, `document()`, the
+* guarded `doc`, and `get()` resolving document-scoped capabilities for it.
+* `lifetime` aborts and `scope` disposes when the instance closes. One kind of
+* context serves every plugin, so `settings()` is always there and throws for
+* a plugin that declares none; the plugin's own types hide it (`definePlugin`).
+*/
+function createPluginContext(services, plugin, session, lifetime, scope) {
+	const { engine, store } = services;
+	const documentId = session?.id;
+	const instanceId = session?.instanceId ?? `workspace:${plugin.id}`;
+	const capability = plugin.id;
+	const lease = (session?.leases ?? services.workspaceLeases).get(plugin);
+	if (!lease) throw new Error(`[kernel] no state lease for plugin "${plugin.id}" (${documentId ?? "workspace"})`);
+	const declared = declaredTokens(plugin);
+	const guard = (token) => {
+		if (isDev() && !plugin.resolvesAnyCapability && !declared.has(token)) throw new Error(`[kernel] plugin "${plugin.id}" resolved capability "${token.name}" without declaring it; add the token to its \`requires\` or \`optional\` list.`);
+	};
+	let reportedClosed = false;
+	const reportClosed = (what) => {
+		if (reportedClosed) return;
+		reportedClosed = true;
+		services.report(new PluginError("instance-closed", plugin.id, `${what} after the instance closed (${lease.instanceId}); dropped`));
+	};
+	let guarded = null;
+	const doc = () => {
+		if (!session) throw new Error(`[kernel] workspace plugin "${plugin.id}" has no bound document; use ctx.forDocument(token, documentId).`);
+		if (!session.handle) throw new PluginError("not-ready", capability, `document ${session.id} has no engine handle yet`);
+		return guarded ?? (guarded = guardHandle(session.handle, {
+			signal: lifetime,
+			instanceId
+		}, capability));
+	};
+	const metaOf = () => session ? store.getCore().documents[session.id] ?? session.stagedMeta : null;
+	const notFound = (ref) => new PluginError("not-found", capability, `page ${ref.objectNumber} is not in this document`);
+	const queues = /* @__PURE__ */ new Map();
+	const lanes = /* @__PURE__ */ new Map();
+	let instanceSettings = null;
+	let changeQueue = null;
+	const pendingStarts = [];
+	const mirrorEnvironment = () => ({
+		doc: doc(),
+		changes: session.changes,
+		notify: () => {
+			if (lease.live) store.notify();
+		},
+		lifetime,
+		cell(name, initial) {
+			const cell = store.lease(`${sliceKey(plugin.id, session?.id)}/${name}`, initial, instanceId);
+			if (lifetime.aborted) cell.revoke();
+			else lifetime.addEventListener("abort", () => cell.revoke(), { once: true });
+			return cell;
+		},
+		onDocumentEvent(listener) {
+			const off = doc().events.subscribe(listener);
+			scope.defer(off);
+		},
+		report: services.report
+	});
+	const context = {
+		id: plugin.id,
+		instanceId,
+		documentId,
+		engine,
+		get doc() {
+			return doc();
+		},
+		documentHandle: (requestedDocumentId) => requestedDocumentId ? services.documentHandle(requestedDocumentId) : session ? session.handle : services.documentHandle(void 0),
+		document: () => {
+			if (session) return metaOf();
+			const id = store.getCore().activeId;
+			return id ? store.getCore().documents[id] ?? null : null;
+		},
+		getPage: (page) => findPage(metaOf()?.pages ?? [], page),
+		pageOf: (page) => pageOf(metaOf()?.pages ?? [], page, capability),
+		assertPageRef: (ref) => {
+			if (!metaOf()?.pages.some((pageInfo) => pageRefsEqual(pageInfo.ref, ref))) throw notFound(ref);
+		},
+		allows: (permission) => sessionAllows(doc().security, permission),
+		assertAllowed: (permission, operation) => {
+			if (!sessionAllows(doc().security, permission)) throw permissionDenied(capability, permission, operation);
+		},
+		allowsField: (action, field) => doc().security.allowsField(action, { groupId: field.groupId }),
+		assertAllowedField: (action, field, operation) => {
+			if (!doc().security.allowsField(action, { groupId: field.groupId })) throw fieldPermissionDenied(capability, action, field, operation);
+		},
+		get: (token) => (guard(token), services.resolveCapability(token, documentId)),
+		tryGet: (token) => (guard(token), services.tryResolveCapability(token, documentId)),
+		forDocument: (token, otherDocumentId) => (guard(token), services.resolveCapability(token, otherDocumentId)),
+		tryForDocument: (token, otherDocumentId) => (guard(token), services.tryResolveCapability(token, otherDocumentId)),
+		state: {
+			get: () => lease.read(),
+			update: (transition, ...args) => {
+				if (!lease.write(transition(lease.read(), ...args))) reportClosed("a state update");
+			},
+			onChange: lease.onChange
+		},
+		settings: () => {
+			if (instanceSettings) return instanceSettings;
+			const registration = services.settingsStoreOf(plugin);
+			if (!registration) throw new Error(`[kernel] plugin "${plugin.id}" read ctx.settings() but declares no settings; add \`settings: { defaults, registered }\` to its definition.`);
+			return instanceSettings = registration.forInstance((teardown) => scope.defer(teardown));
+		},
+		notify: () => {
+			if (lease.live) store.notify();
+		},
+		watch: (select, handler, isEqual = Object.is) => {
+			let previous = select();
+			const unsubscribe = store.subscribe(() => {
+				const next = select();
+				if (isEqual(previous, next)) return;
+				const prior = previous;
+				previous = next;
+				handler(next, prior);
+			});
+			scope.defer(unsubscribe);
+			return unsubscribe;
+		},
+		waitFor(predicate, options) {
+			return new Promise((resolve, reject) => {
+				let done = false;
+				const finish = (fn) => {
+					if (done) return;
+					done = true;
+					unsubscribe();
+					lifetime.removeEventListener("abort", onClose);
+					options?.signal?.removeEventListener("abort", onCancel);
+					fn();
+				};
+				const onClose = () => finish(() => reject(new PluginError("instance-closed", capability, "closed while waiting")));
+				const onCancel = () => finish(() => reject(new PluginError("operation-cancelled", capability, "cancelled while waiting")));
+				const check = () => {
+					let holds = false;
+					try {
+						holds = predicate();
+					} catch (error) {
+						finish(() => reject(error));
+						return;
+					}
+					if (holds) finish(resolve);
+				};
+				const unsubscribe = store.subscribe(check);
+				if (lifetime.aborted) return onClose();
+				if (options?.signal?.aborted) return onCancel();
+				lifetime.addEventListener("abort", onClose, { once: true });
+				options?.signal?.addEventListener("abort", onCancel, { once: true });
+				check();
+			});
+		},
+		mirror(spec) {
+			const controller = createMirror(spec, mirrorEnvironment());
+			pendingStarts.push(controller.start);
+			return controller.mirror;
+		},
+		pageMirror: (spec) => createPageMirror(spec, mirrorEnvironment()),
+		events: { source() {
+			const hook = createEventHook(services.report);
+			scope.defer(() => hook.dispose());
+			return hook;
+		} },
+		listen(source, listener) {
+			const off = typeof source === "function" ? source(listener) : source.subscribe(listener);
+			scope.defer(off);
+		},
+		get changes() {
+			if (!session) throw new Error(`[kernel] workspace plugin "${plugin.id}" has no document to change; ctx.changes is for document-scoped plugins.`);
+			return changeQueue ?? (changeQueue = session.changes.forPlugin(plugin.id));
+		},
+		cleanup: (teardown) => scope.defer(teardown),
+		clock: instanceClock(services.clock, lifetime),
+		onSettle(flush) {
+			if (!session) throw new Error(`[kernel] workspace plugin "${plugin.id}" has no document to settle; ctx.onSettle() is for document-scoped plugins.`);
+			session.settleFlushes.add(flush);
+			scope.defer(() => {
+				session.settleFlushes.delete(flush);
+			});
+		},
+		aroundDownload(wrap) {
+			if (!session) throw new Error(`[kernel] workspace plugin "${plugin.id}" has no document to download; ctx.aroundDownload() is for document-scoped plugins.`);
+			session.downloadWraps.push(wrap);
+			scope.defer(() => {
+				const index = session.downloadWraps.indexOf(wrap);
+				if (index >= 0) session.downloadWraps.splice(index, 1);
+			});
+		},
+		async acquire(get, dispose) {
+			const value = await get(lifetime);
+			if (lifetime.aborted) {
+				await dispose(value);
+				throw new PluginError("instance-closed", capability, "closed while acquiring a resource");
+			}
+			scope.defer(() => dispose(value));
+			return value;
+		},
+		cancellable: (signal, task) => cancellable(capability, signal, task),
+		latest(key) {
+			let lane = lanes.get(key);
+			if (!lane) {
+				lane = createLatestLane(lifetime, capability, key);
+				lanes.set(key, lane);
+			}
+			return lane;
+		},
+		serialQueue(key = "default") {
+			let queue = queues.get(key);
+			if (!queue) {
+				queue = createSerialQueue(capability);
+				queues.set(key, queue);
+			}
+			return queue;
+		}
+	};
+	connectedHooks.set(context, () => {
+		for (const start of pendingStarts.splice(0)) start();
+	});
+	return context;
+}
+//#endregion
+//#region src/settle.ts
+/**
+* Settling a document: before something reads the whole file (a download), everything its
+* plugins hold back from the engine is sent, and the engine has answered. Each plugin registers
+* a flush with `ctx.onSettle()` for what it holds back: text typed a moment ago, a drawing waiting
+* for its next stroke, the writes on their way in its write queue. The rules are in
+* `docs/conventions/state-and-sync.md`.
+*
+* A flush that fails doesn't stop the read: the file is then what the engine has, and the plugin
+* reports its own failure.
+*/
+/**
+* Run every flush and wait for all of them. Rejects with `operation-cancelled` as soon as one of
+* `signals` aborts, such as the caller's or the document's own (it aborts when the document
+* closes).
+*/
+async function settle(flushes, signals, report) {
+	const stop = new AbortController();
+	const listening = signals.filter((signal) => signal !== void 0);
+	const abort = () => stop.abort();
+	for (const signal of listening) if (signal.aborted) abort();
+	else signal.addEventListener("abort", abort, { once: true });
+	try {
+		await whileNotAborted((async () => {
+			const running = [...flushes].map(async (flush) => flush(stop.signal));
+			for (const outcome of await Promise.allSettled(running)) if (outcome.status === "rejected") report(outcome.reason);
+		})(), stop.signal);
+	} finally {
+		for (const signal of listening) signal.removeEventListener("abort", abort);
+	}
+}
+/** `work`, or `operation-cancelled` as soon as `signal` aborts. */
+async function whileNotAborted(work, signal) {
+	let onAbort;
+	const aborted = new Promise((_, reject) => {
+		onAbort = () => reject(new PluginError("operation-cancelled", "documents", "settling was cancelled"));
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		await Promise.race([work, aborted]);
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+//#endregion
+//#region src/settings.ts
+/**
+* A plugin's settings: what the app registered over the plugin's defaults, changed at runtime
+* with `updateSettings()`. A plugin declares them in its definition
+* (`definePlugin({ settings: { defaults, registered } })`), and the kernel builds one store per
+* plugin registration when it plans the plugin list. The store belongs to the registration, not
+* to a document: it exists before the first document opens, every instance of the plugin shares
+* it, and a change reaches every open document and the ones opened later. A plugin reads its
+* store with `ctx.settings()`; an adapter reads it with `kernel.settingsOf(token)`.
+*
+* Changes merge into the settings the same way everywhere (`registered` over the defaults, and
+* every `updateSettings()`): plain objects merge key by key, arrays and every other value
+* replace, and `undefined` leaves a setting as it is.
+*/
+/**
+* Build a registration's store. `wake` runs after every change, before the event, so readers
+* that poll the capability (selectors over `getSettings()`) read again.
+*/
+function createSettingsStore({ defaults, registered, whole = [] }, wake, report) {
+	const initial = mergeSettings(defaults, registered, whole);
+	let current = initial;
+	const changedHook = createEventHook(report);
+	const commit = (next) => {
+		const changed = changedKeys(current, next);
+		if (changed.length === 0) return;
+		current = next;
+		wake();
+		changedHook.emit({
+			settings: next,
+			changed
+		});
+	};
+	const api = {
+		getSettings: () => current,
+		updateSettings: (changes) => commit(mergeSettings(current, changes, whole)),
+		resetSettings: () => commit(initial),
+		onSettingsChanged: changedHook.on
+	};
+	return {
+		api,
+		forInstance(cleanup) {
+			const instanceChanged = createEventHook(report);
+			cleanup(changedHook.on((event) => instanceChanged.emit(event)));
+			cleanup(() => instanceChanged.dispose());
+			return {
+				get: api.getSettings,
+				api: {
+					...api,
+					onSettingsChanged: instanceChanged.on
+				}
+			};
+		},
+		dispose: () => changedHook.dispose()
+	};
+}
+/**
+* `changes` merged into `settings`, the `whole` ones replaced instead: the merge every settings
+* store applies, for code that keeps changes before a store exists (an adapter whose engine is
+* still loading). What a change leaves as it was keeps its object, so a reader that compares by
+* reference sees only what really changed.
+*/
+function mergeSettings(settings, changes, whole = []) {
+	if (whole.length === 0 || !isPlainObject(changes)) return mergeValue(settings, changes);
+	const merged = mergeValue(settings, omit(changes, whole));
+	let replaced = null;
+	for (const key of whole) {
+		const change = changes[key];
+		if (change === void 0 || sameValue(merged[key], change)) continue;
+		replaced ?? (replaced = { ...merged });
+		replaced[key] = change;
+	}
+	return replaced ?? merged;
+}
+/** `object` without `keys`. */
+function omit(object, keys) {
+	const rest = {};
+	for (const key of Object.keys(object)) if (!keys.includes(key)) rest[key] = object[key];
+	return rest;
+}
+function mergeValue(base, change) {
+	if (change === void 0) return base;
+	if (!isPlainObject(change)) return sameValue(base, change) ? base : change;
+	const into = isPlainObject(base) ? base : {};
+	let merged = null;
+	for (const key of Object.keys(change)) {
+		const current = hasOwn(into, key) ? into[key] : void 0;
+		const next = mergeValue(current, change[key]);
+		if (next === current) continue;
+		merged ?? (merged = { ...into });
+		merged[key] = next;
+	}
+	return merged ?? base;
+}
+/** The top-level settings whose value differs between `previous` and `next`. */
+function changedKeys(previous, next) {
+	const before = previous;
+	const after = next;
+	return [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].filter((key) => !sameValue(before[key], after[key]));
+}
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+/** Equal by value: the same primitive or object, or arrays and plain objects with equal entries. */
+function sameValue(left, right) {
+	if (Object.is(left, right)) return true;
+	if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((item, index) => sameValue(item, right[index]));
+	if (isPlainObject(left) && isPlainObject(right)) {
+		const keys = Object.keys(left);
+		return keys.length === Object.keys(right).length && keys.every((key) => hasOwn(right, key) && sameValue(left[key], right[key]));
+	}
+	return false;
+}
+//#endregion
+export { createScope as A, createDocumentChanges as C, toPluginError as D, isPluginError as E, createBurstGate as M, DocumentsToken as N, toPluginErrorInfo as O, timerClock as S, PluginError as T, reload as _, markConnected as a, createStore as b, fieldPermissionDenied as c, findPage as d, pageOf as f, createMirror as g, createPageMirror as h, createPluginContext as i, isCancelled as j, CancelledError as k, permissionDenied as l, createSerialQueue as m, mergeSettings as n, readWrapped as o, cancellable as p, settle as r, sliceKey as s, createSettingsStore as t, sessionAllows as u, createLatestLane as v, createEventHook as w, instanceClock as x, guardHandle as y };
+
+//# sourceMappingURL=settings-CMWFRjmQ.js.map