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

package/dist/index.js

@@ -1,197 +1,39 @@
-import { AbortablePromise, CONTINUOUS_RENDER_POLICY, CONTINUOUS_RENDER_POLICY as CONTINUOUS_RENDER_POLICY$1, PermissionDenied, snapAppearanceScale, snapFullPageViewport, snapTileScale } from "@embedpdf/engine-core/runtime";
-//#region src/types.ts
-/** Kernel-emitted document-lifecycle actions; plugins may react via `onAction`. */
-const CORE_DOCUMENT_ADDED = "@@core/document-added";
-const CORE_DOCUMENT_REMOVED = "@@core/document-removed";
-const CORE_ACTIVE_CHANGED = "@@core/active-changed";
-const CORE_ORDER_CHANGED = "@@core/order-changed";
-/** A document's page registry was replaced by a mutation event (rotate/move/delete). */
-const CORE_DOCUMENT_PAGES_UPDATED = "@@core/document-pages-updated";
-/** A tab slot was reserved: `open()` was called; the document is loading. */
-const CORE_DOCUMENT_OPENING = "@@core/document-opening";
-/** The engine reports the document needs a password (`documents.unlock`). */
-const CORE_DOCUMENT_LOCKED = "@@core/document-locked";
-/** The open failed; the tab stays with `status: 'error'` until closed. */
-const CORE_DOCUMENT_OPEN_FAILED = "@@core/document-open-failed";
-/** Field-wise DocInfo equality — the ONE definition every adapter's reactive
-*  `docs` read keys on, so a new lifecycle field can never silently stop
-*  re-rendering one framework's tab bar. */
-const docInfoEquals = (a, b) => a.id === b.id && a.name === b.name && a.status === b.status && a.pageCount === b.pageCount && a.passwordProvided === b.passwordProvided;
-const docInfoListEquals = (a, b) => a === b || a.length === b.length && a.every((d, i) => docInfoEquals(d, b[i]));
-/** Built-in token for the document registry capability (provided by the kernel). */
-const DocumentsToken = { name: "documents" };
-//#endregion
-//#region src/store.ts
-function createStore(report = console.error) {
-	let core = {
-		documents: {},
-		pending: {},
-		order: [],
-		activeId: null
-	};
-	const slices = {};
-	const reducers = {};
-	const changeListeners = /* @__PURE__ */ new Set();
-	const actionListeners = /* @__PURE__ */ new Set();
-	const guarded = (fn) => {
-		try {
-			fn();
-		} catch (error) {
-			report(error);
-		}
-	};
-	let emitting = false;
-	let pending = false;
-	const emitChange = () => {
-		if (emitting) {
-			pending = true;
-			return;
-		}
-		emitting = true;
-		try {
-			do {
-				pending = false;
-				changeListeners.forEach((listener) => guarded(listener));
-			} while (pending);
-		} finally {
-			emitting = false;
-		}
-	};
-	const emitAction = (action) => actionListeners.forEach((listener) => guarded(() => listener(action)));
-	return {
-		registerSlice(key, reducer, initial) {
-			reducers[key] = reducer;
-			slices[key] = initial;
-		},
-		removeSlice(key) {
-			delete reducers[key];
-			delete slices[key];
-			emitChange();
-		},
-		getSlice: (key) => slices[key],
-		getCore: () => core,
-		getState: () => ({
-			core,
-			plugins: slices
-		}),
-		dispatchTo(key, action) {
-			const r = reducers[key];
-			if (!r) return;
-			const next = r(slices[key], action);
-			if (next !== slices[key]) {
-				slices[key] = next;
-				emitChange();
-			}
-			emitAction(action);
-		},
-		setCore(patch, action) {
-			core = {
-				...core,
-				...patch
-			};
-			emitChange();
-			emitAction(action);
-		},
-		subscribe(listener) {
-			changeListeners.add(listener);
-			return () => void changeListeners.delete(listener);
-		},
-		subscribeAction(listener) {
-			actionListeners.add(listener);
-			return () => void actionListeners.delete(listener);
-		},
-		destroy() {
-			core = {
-				documents: {},
-				pending: {},
-				order: [],
-				activeId: null
-			};
-			for (const key of Object.keys(slices)) delete slices[key];
-			for (const key of Object.keys(reducers)) delete reducers[key];
-			changeListeners.clear();
-			actionListeners.clear();
-		}
-	};
-}
-//#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;
-/**
-* Build the context a plugin sees. When `session` is given the context is bound
-* to that document — `getState`/`dispatch` target its slice, `document()` returns
-* it, and `get()` resolves document-scoped capabilities for it.
-*/
-function createPluginContext(services, plugin, session) {
-	const { engine, store } = services;
-	const documentId = session?.id;
-	const key = sliceKey(plugin.id, documentId);
-	const ownScope = session?.scope ?? services.workspaceScope;
-	return {
-		id: plugin.id,
-		engine,
-		documentId,
-		doc: session ? session.handle : services.documentHandle(void 0),
-		documentHandle: (requestedDocumentId) => requestedDocumentId ? services.documentHandle(requestedDocumentId) : session ? session.handle : services.documentHandle(void 0),
-		getState: () => store.getSlice(key),
-		dispatch: (action) => store.dispatchTo(key, action),
-		subscribe: store.subscribe,
-		core: store.getCore,
-		document: () => {
-			if (session) return store.getCore().documents[session.id] ?? session.stagedMeta;
-			const id = store.getCore().activeId;
-			return id ? store.getCore().documents[id] ?? null : null;
-		},
-		get: (token) => services.resolveCapability(token, documentId),
-		forDocument: (token, otherDocumentId) => services.resolveCapability(token, otherDocumentId),
-		tryGet: (token) => services.tryResolveCapability(token, documentId),
-		tryForDocument: (token, otherDocumentId) => services.tryResolveCapability(token, otherDocumentId),
-		cleanup: (teardown) => ownScope.defer(teardown)
-	};
-}
-/** A plugin context plus the side-effect primitives (watch / onAction / cleanup). */
-function createEffectContext(services, plugin, session) {
-	const { store } = services;
-	const ownScope = session?.scope ?? services.workspaceScope;
-	return {
-		...createPluginContext(services, plugin, session),
-		watch: (select, handler, isEqual = Object.is) => {
-			let previous = select();
-			const unsubscribe = store.subscribe(() => {
-				const next = select();
-				if (!isEqual(previous, next)) {
-					const prior = previous;
-					previous = next;
-					handler(next, prior);
-				}
-			});
-			ownScope.defer(unsubscribe);
-			return unsubscribe;
-		},
-		onAction: (type, handler) => {
-			const unsubscribe = store.subscribeAction((action) => {
-				if (action.type === type) handler(action);
-			});
-			ownScope.defer(unsubscribe);
-			return unsubscribe;
-		}
-	};
-}
-//#endregion
+import { A as createScope, C as createDocumentChanges, D as toPluginError, E as isPluginError, M as createBurstGate, N as DocumentsToken, O as toPluginErrorInfo, S as timerClock, T as PluginError, _ as reload, a as markConnected, b as createStore, d as findPage, i as createPluginContext, j as isCancelled, k as CancelledError, l as permissionDenied, m as createSerialQueue, n as mergeSettings, o as readWrapped, p as cancellable, r as settle, s as sliceKey, t as createSettingsStore, u as sessionAllows, v as createLatestLane, w as createEventHook, y as guardHandle } from "./settings-CMWFRjmQ.js";
+import { AbortablePromise, CONTINUOUS_RENDER_POLICY, CONTINUOUS_RENDER_POLICY as CONTINUOUS_RENDER_POLICY$1, PermissionDenied, annotationKey, decodePageKey, encodePageKey, isLocalDocument, isLocalEngine, pageRefsEqual, pageRefsEqual as pageRefsEqual$1, resolvePageLayers, snapAppearanceScale, snapFullPageViewport, snapTileScale, toPageRef } from "@embedpdf/engine-core/runtime";
 //#region src/order.ts
 /**
-* Validate `requires` (fail fast) and topologically sort plugins so dependencies
-* are initialised before dependents.
+* Validate the composition (fail fast, before anything is constructed) and
+* topologically sort plugins so dependencies are initialised before dependents.
+*
+* Rejected compositions, each with both names in the error:
+*   - the same plugin definition installed twice, or two definitions sharing an id;
+*   - two plugins providing the same capability token (no implicit last-wins —
+*     an intentional replacement is a composition-time choice, made by
+*     removing the old definition from the list);
+*   - a workspace plugin that `requires` a document-scoped token (it has no
+*     document to resolve it for; `ctx.forDocument()` is the explicit path);
+*   - a required token no plugin provides;
+*   - a dependency cycle.
 */
 function planPlugins(plugins) {
+	const byId = /* @__PURE__ */ new Map();
 	const providerByToken = /* @__PURE__ */ new Map();
 	const scopeByToken = /* @__PURE__ */ new Map([[DocumentsToken, "workspace"]]);
-	for (const plugin of plugins) if (plugin.token && plugin.capability) {
-		providerByToken.set(plugin.token, plugin);
-		scopeByToken.set(plugin.token, plugin.scope ?? "workspace");
+	for (const plugin of plugins) {
+		const prior = byId.get(plugin.id);
+		if (prior) throw new Error(prior === plugin ? `[kernel] plugin "${plugin.id}" is installed twice.` : `[kernel] two different plugins use the id "${plugin.id}".`);
+		byId.set(plugin.id, plugin);
+		if (plugin.token) {
+			const other = providerByToken.get(plugin.token);
+			if (other) throw new Error(`[kernel] capability "${plugin.token.name}" is provided by both "${other.id}" and "${plugin.id}".`);
+			providerByToken.set(plugin.token, plugin);
+			scopeByToken.set(plugin.token, plugin.scope ?? "workspace");
+		}
+	}
+	for (const plugin of plugins) for (const required of plugin.requires ?? []) {
+		if (required !== DocumentsToken && !providerByToken.has(required)) throw new Error(`Plugin "${plugin.id}" requires capability "${required.name}", which no plugin provides` + (required.hint ? ` — ${required.hint}.` : "."));
+		if (plugin.scope !== "document" && providerByToken.get(required)?.scope === "document") throw new Error(`[kernel] workspace plugin "${plugin.id}" requires document-scoped capability "${required.name}"; resolve it per document with ctx.forDocument() and declare it as optional.`);
 	}
-	for (const plugin of plugins) for (const required of plugin.requires ?? []) if (required !== DocumentsToken && !providerByToken.has(required)) throw new Error(`Plugin "${plugin.id}" requires capability "${required.name}", which no plugin provides` + (required.hint ? ` — ${required.hint}.` : "."));
 	const ordered = [];
 	const status = /* @__PURE__ */ new Map();
 	const visit = (plugin) => {
@@ -214,49 +56,44 @@ function planPlugins(plugins) {
 	};
 }
 //#endregion
-//#region src/scope.ts
+//#region src/viewer-settings.ts
+/** The viewer's settings when the app gives none; the colors are the theming page's defaults. */
+const VIEWER_DEFAULTS = Object.freeze({
+	identity: null,
+	scope: null,
+	accent: "#3858e9",
+	page: Object.freeze({
+		background: "#ffffff",
+		shadow: "0 6px 18px rgb(0 0 0 / 0.18)"
+	})
+});
+/** An identity is one person: a new one replaces the last instead of merging into it. */
+const VIEWER_WHOLE_SETTINGS = ["identity"];
 /**
-* 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".
+* The viewer's settings as a framework's viewer component gives them: a setting left out is its
+* default, and `page` fills in the side it leaves out. Every adapter's viewer starts the kernel
+* with this and passes it again when its props change.
 */
-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;
+function viewerSettingsOf({ identity, scope, accent, page }) {
 	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);
-				}
-			})());
+		identity: identity ?? null,
+		scope: scope ?? null,
+		accent: accent ?? VIEWER_DEFAULTS.accent,
+		page: {
+			...VIEWER_DEFAULTS.page,
+			...page
 		}
 	};
 }
 //#endregion
 //#region src/kernel.ts
+const EMPTY_PAGES = Object.freeze([]);
 /** The new page registry a document mutation carries, or null for events that
 *  don't change page structure (annotations, metadata). The snapshot is the
 *  same shape `pages.list()` returns, so callers swap it in directly. */
 function layoutFromEvent(event) {
 	switch (event.type) {
-		case "pages.moved":
+		case "pages.reordered":
 		case "pages.rotated":
 		case "pages.deleted":
 		case "pages.inserted": return event.layout;
@@ -264,24 +101,70 @@ function layoutFromEvent(event) {
 	}
 }
 const isDocumentScoped = (plugin) => plugin.scope === "document";
-const initialStateOf = (plugin) => typeof plugin.initialState === "function" ? plugin.initialState() : plugin.initialState ?? {};
-const reducerOf = (plugin) => plugin.reduce ?? ((state) => state);
-const toDocInfo = (meta) => ({
+const initialStateOf = (plugin) => plugin.state?.();
+/**
+* A document's public fields, one object per registry entry: the entries are replaced, never
+* changed, so the same entry gives the same object, and readers re-render only for their own.
+*/
+const infoByEntry = /* @__PURE__ */ new WeakMap();
+function documentInfoOf(entry) {
+	let info = infoByEntry.get(entry);
+	if (!info) {
+		info = "pages" in entry ? readyInfo(entry) : pendingInfo(entry);
+		infoByEntry.set(entry, info);
+	}
+	return info;
+}
+const readyInfo = (meta) => Object.freeze({
 	id: meta.id,
 	name: meta.name,
 	status: "ready",
-	pageCount: meta.pageCount
+	pageCount: meta.pageCount,
+	hasUnsavedChanges: meta.hasUnsavedChanges
 });
-const pendingToDocInfo = (meta) => ({
+const pendingInfo = (meta) => Object.freeze({
 	id: meta.id,
 	name: meta.name,
 	status: meta.status,
 	pageCount: 0,
-	passwordProvided: meta.passwordProvided
+	hasUnsavedChanges: false,
+	...meta.status === "locked" ? { passwordProvided: meta.passwordProvided ?? false } : {},
+	...meta.status === "error" && meta.error !== void 0 ? { error: toPluginErrorInfo(toPluginError("documents", meta.error)) } : {}
+});
+/** Whether an event is a change to the document, one a download would carry. */
+const changesDocument = (event) => event.type !== "stream.desynced" && event.type !== "document.versioned" && event.type !== "signatures.prepared" && event.type !== "signatures.cancelled";
+/** Download a URL source's file; its tab shows the failure when the server says no. */
+async function fetchUrlSource(source, signal) {
+	const fetchFile = globalThis.fetch;
+	if (!fetchFile) throw new PluginError("unsupported", "documents", `can't download ${source.url}: no fetch()`);
+	const response = await fetchFile(source.url, { signal });
+	if (!response.ok) throw new PluginError(response.status === 404 ? "not-found" : "operation-failed", "documents", `couldn't download ${source.url} (HTTP ${response.status})`);
+	return {
+		kind: "bytes",
+		bytes: new Uint8Array(await response.arrayBuffer())
+	};
+}
+const isUrlSource = (source) => source.kind === "url";
+const noLayer = () => new PluginError("unsupported", "documents", "only the local engine gives a layer to download");
+/**
+* The documents capability as seen from inside one document's scope: every call whose document
+* is optional uses that document instead of the active one. The rest is the registry itself.
+*/
+const documentsInScope = (documents, documentId) => ({
+	...documents,
+	get: (id = documentId) => documents.get(id),
+	download: (id = documentId, options) => documents.download(id, options),
+	downloadLayer: (id = documentId, options) => documents.downloadLayer(id, options),
+	canDownload: (id = documentId) => documents.canDownload(id),
+	canPrint: (id = documentId) => documents.canPrint(id),
+	listPages: (id = documentId) => documents.listPages(id),
+	getPage: (page, id = documentId) => documents.getPage(page, id),
+	getPageIndex: (ref, id = documentId) => documents.getPageIndex(ref, id),
+	getRevision: (id = documentId) => documents.getRevision(id)
 });
 /** The stable id an input implies, if it carries one ('bytes'/'layerBytes'/'id'). */
 const idOfInput = (input) => "id" in input && typeof input.id === "string" ? input.id : null;
-const passwordOfInput = (input) => "password" in input ? input.password : void 0;
+let instanceCounter = 0;
 /** Engine rejections carry AbortError when close() aborts the live call;
 *  match structurally so test fakes with plain promises still work. */
 const isAbortLike = (error) => error instanceof Error && error.name === "AbortError";
@@ -289,7 +172,10 @@ const isAbortLike = (error) => error instanceof Error && error.name === "AbortEr
 * Assemble a kernel from an engine + plugins.
 *
 *   planPlugins        — validate dependencies, order them
-*   resolveCapability  — workspace singletons, or per-document instances built lazily
+*   resolveCapability  — workspace singletons (or their view from a document's scope),
+*                        or per-document instances built lazily
+*   settings           — one store per plugin registration, built up front, shared
+*                        by its instances and readable with no document
 *   document lifecycle — one DocumentSession per document: transactional open
 *                        (publish-last), one idempotent close for every phase
 *   start / destroy    — explicit status machine; destroy closes everything
@@ -297,14 +183,49 @@ const isAbortLike = (error) => error instanceof Error && error.name === "AbortEr
 * The kernel closes every handle it opened; it never destroys the engine —
 * ownership follows acquisition, and the engine was handed in by the caller.
 */
-function createKernel(opts) {
-	const { engine, plugins } = opts;
-	const report = opts.report ?? ((error) => console.error("[kernel]", error));
+function createKernel(config) {
+	const { engine, plugins } = config;
+	const report = config.report ?? ((error) => console.error("[kernel]", error));
 	const store = createStore(report);
 	const plan = planPlugins(plugins);
 	const documentScopedPlugins = plan.ordered.filter(isDocumentScoped);
 	const workspaceCapabilities = /* @__PURE__ */ new Map();
+	const workspaceLeases = /* @__PURE__ */ new Map();
+	const workspaceConnectors = /* @__PURE__ */ new Map();
+	const workspaceCancel = new AbortController();
 	const workspaceScope = createScope(report);
+	/** How each workspace capability looks from inside a document's scope, by token. The
+	*  documents capability is built in, so its view is declared here; plugins declare theirs. */
+	const inScopeByToken = /* @__PURE__ */ new Map([[DocumentsToken, documentsInScope]]);
+	for (const plugin of plan.ordered) if (plugin.token && plugin.inScope && !isDocumentScoped(plugin)) inScopeByToken.set(plugin.token, plugin.inScope);
+	const opened = createEventHook(report);
+	const openFailed = createEventHook(report);
+	const locked = createEventHook(report);
+	const closed = createEventHook(report);
+	const activeChanged = createEventHook(report);
+	const pagesChanged = createEventHook(report);
+	const unsavedChangesChanged = createEventHook(report);
+	workspaceScope.defer(() => {
+		for (const hook of [
+			opened,
+			openFailed,
+			locked,
+			closed,
+			activeChanged,
+			pagesChanged,
+			unsavedChangesChanged
+		]) hook.dispose();
+	});
+	/** Every core write goes through here so an active-tab change is observed exactly once. */
+	const setCore = (patch) => {
+		const before = store.getCore().activeId;
+		store.setCore(patch);
+		const after = store.getCore().activeId;
+		if (before !== after) activeChanged.emit({
+			documentId: after,
+			previousDocumentId: before
+		});
+	};
 	const sessions = /* @__PURE__ */ new Map();
 	let status = "created";
 	let startPromise = null;
@@ -319,12 +240,12 @@ function createKernel(opts) {
 	* Await an engine/network call under the session's cancellation:
 	*   - the call is retained so close() can abort real worker-side work
 	*     (`AbortablePromise`), and
-	*   - the await RACES the cancellation, so close()'s join never blocks on a
+	*   - the await races the cancellation, so close()'s join never blocks on a
 	*     call that cannot be aborted (a plain-promise engine, a stuck fetch).
 	* When cancellation wins but the call later lands anyway, `onLateResult`
 	* routes the result into the session scope — whose late-defer rule runs it
 	* immediately after disposal — so a late-arriving resource cannot leak.
-	* (Plugin inits are deliberately NOT raced: they are first-party code that
+	* (Plugin inits are deliberately not raced: they are first-party code that
 	* close() joins to completion; only unbounded external waits are raced.)
 	*/
 	async function engineCall(session, call, onLateResult) {
@@ -350,19 +271,38 @@ function createKernel(opts) {
 		}
 	}
 	function createSession(id, name) {
+		const cancel = new AbortController();
 		const session = {
 			id,
+			instanceId: `${id}#${++instanceCounter}`,
 			name,
+			source: null,
+			openOptions: void 0,
 			phase: "opening",
 			handle: null,
 			stagedMeta: null,
 			scope: createScope(report),
 			operation: null,
 			engineOp: null,
-			cancel: new AbortController(),
+			cancel,
+			signal: cancel.signal,
 			capabilities: /* @__PURE__ */ new Map(),
+			building: /* @__PURE__ */ new Set(),
+			views: /* @__PURE__ */ new Map(),
+			connectors: /* @__PURE__ */ new Map(),
+			leases: /* @__PURE__ */ new Map(),
+			settleFlushes: /* @__PURE__ */ new Set(),
+			downloadWraps: [],
+			changes: createDocumentChanges({
+				handle: () => session.handle,
+				notify: () => store.notify(),
+				report
+			}),
+			changeCount: 0,
 			close: () => closeSession(session)
 		};
+		session.settleFlushes.add(() => session.changes.settle());
+		session.scope.defer(() => session.changes.close());
 		return session;
 	}
 	/** One transition at a time per session (open, then possibly unlock). */
@@ -380,14 +320,15 @@ function createKernel(opts) {
 		const previousId = session.id;
 		if (previousId === nextId) return;
 		const core = store.getCore();
-		if (sessions.has(nextId) || core.documents[nextId] || core.pending[nextId]) throw new Error(`[documents] duplicate document id: ${nextId}`);
+		if (sessions.has(nextId) || core.documents[nextId] || core.pending[nextId]) throw new PluginError("conflict", "documents", `duplicate document id: ${nextId}`);
 		sessions.delete(previousId);
 		session.id = nextId;
 		sessions.set(nextId, session);
+		session.views.clear();
 		const slot = core.pending[previousId];
 		if (slot) {
 			const { [previousId]: _moved, ...pending } = core.pending;
-			store.setCore({
+			setCore({
 				pending: {
 					...pending,
 					[nextId]: {
@@ -397,7 +338,7 @@ function createKernel(opts) {
 				},
 				order: core.order.map((id) => id === previousId ? nextId : id),
 				activeId: core.activeId === previousId ? nextId : core.activeId
-			}, { type: CORE_ORDER_CHANGED });
+			});
 		}
 	}
 	const closingSessions = /* @__PURE__ */ new WeakMap();
@@ -407,6 +348,7 @@ function createKernel(opts) {
 		const closing = (async () => {
 			session.phase = "closing";
 			unpublishSlot(session.id);
+			for (const lease of session.leases.values()) lease.revoke();
 			const reason = new CancelledError(`closed while opening: ${session.id}`);
 			session.cancel.abort(reason);
 			session.engineOp?.abort(reason);
@@ -415,6 +357,8 @@ function createKernel(opts) {
 			});
 			await session.scope.dispose();
 			if (sessions.get(session.id) === session) sessions.delete(session.id);
+			session.views.clear();
+			closed.emit({ documentId: session.id });
 		})();
 		closingSessions.set(session, closing);
 		return closing;
@@ -427,7 +371,7 @@ function createKernel(opts) {
 	}
 	function publishPendingSlot(session, activate) {
 		const core = store.getCore();
-		store.setCore({
+		setCore({
 			pending: {
 				...core.pending,
 				[session.id]: {
@@ -436,13 +380,13 @@ function createKernel(opts) {
 					status: "loading"
 				}
 			},
-			order: [...core.order, session.id],
+			order: core.order.includes(session.id) ? core.order : [...core.order, session.id],
 			activeId: activate || core.activeId === null ? session.id : core.activeId
-		}, { type: CORE_DOCUMENT_OPENING });
+		});
 	}
 	function publishLocked(session, passwordProvided) {
 		const core = store.getCore();
-		store.setCore({ pending: {
+		setCore({ pending: {
 			...core.pending,
 			[session.id]: {
 				id: session.id,
@@ -450,11 +394,15 @@ function createKernel(opts) {
 				status: "locked",
 				passwordProvided
 			}
-		} }, { type: CORE_DOCUMENT_LOCKED });
+		} });
+		locked.emit({
+			documentId: session.id,
+			passwordProvided
+		});
 	}
 	function publishError(session, error) {
 		const core = store.getCore();
-		store.setCore({ pending: {
+		setCore({ pending: {
 			...core.pending,
 			[session.id]: {
 				id: session.id,
@@ -462,35 +410,70 @@ function createKernel(opts) {
 				status: "error",
 				error
 			}
-		} }, { type: CORE_DOCUMENT_OPEN_FAILED });
+		} });
+		openFailed.emit({
+			documentId: session.id,
+			error: toPluginErrorInfo(toPluginError("documents", error))
+		});
 	}
 	function unpublishSlot(id) {
 		const core = store.getCore();
 		if (!core.pending[id] && !core.documents[id]) return;
 		const { [id]: _pending, ...pending } = core.pending;
 		const { [id]: _document, ...documents } = core.documents;
-		store.setCore({
+		setCore({
 			pending,
 			documents,
 			order: core.order.filter((other) => other !== id),
 			activeId: nextActiveDocument(core, id)
-		}, { type: CORE_DOCUMENT_REMOVED });
+		});
 	}
-	/** The ONE ready transition: swap the pending slot for the staged meta and
-	*  fire CORE_DOCUMENT_ADDED. Everything before this is unpublished and rolls
+	/** The one ready transition: swap the pending slot for the staged meta and
+	*  announce `onOpened`. Everything before this is unpublished and rolls
 	*  back by disposing the session scope; nothing after this can fail. */
 	function commitReady(session) {
 		session.phase = "ready";
 		const meta = session.stagedMeta;
 		const core = store.getCore();
 		const { [session.id]: _resolved, ...pending } = core.pending;
-		store.setCore({
+		setCore({
 			documents: {
 				...core.documents,
 				[session.id]: meta
 			},
 			pending
-		}, { type: CORE_DOCUMENT_ADDED });
+		});
+		opened.emit({
+			documentId: session.id,
+			info: documentInfoOf(meta)
+		});
+	}
+	/**
+	* The document changed, or a download read every change it had: set `hasUnsavedChanges` and
+	* announce a flip. Before the document is published, its staged meta carries the flag.
+	*/
+	function setUnsavedChanges(session, hasUnsavedChanges) {
+		const core = store.getCore();
+		const published = core.documents[session.id];
+		if (!published) {
+			if (session.stagedMeta && session.stagedMeta.hasUnsavedChanges !== hasUnsavedChanges) session.stagedMeta = {
+				...session.stagedMeta,
+				hasUnsavedChanges
+			};
+			return;
+		}
+		if (published.hasUnsavedChanges === hasUnsavedChanges) return;
+		setCore({ documents: {
+			...core.documents,
+			[session.id]: {
+				...published,
+				hasUnsavedChanges
+			}
+		} });
+		unsavedChangesChanged.emit({
+			documentId: session.id,
+			hasUnsavedChanges
+		});
 	}
 	const sessionOf = (documentId) => {
 		const id = documentId ?? store.getCore().activeId;
@@ -503,18 +486,89 @@ function createKernel(opts) {
 		if (!session) return null;
 		return session.phase === "bringup" || session.phase === "ready" ? session.handle : null;
 	};
+	/** The session a per-document verb acts on: `documentId`, or the active document. */
+	function readySession(documentId, verb) {
+		const session = sessionOf(documentId);
+		if (!session || !documentHandle(session.id)) throw new PluginError("not-ready", "documents", `no open document to ${verb}`);
+		return session;
+	}
+	const allowsOn = (documentId, permission) => {
+		const handle = documentHandle(documentId);
+		return handle ? sessionAllows(handle.security, permission) : false;
+	};
+	/**
+	* Read the document's file, with everything the user sees: refuse without `doc.download`, let
+	* it settle (what its plugins held back is sent and answered, settle.ts), then read it inside
+	* every `aroundDownload` wrap (the document's own save actions). A read that saw every change
+	* the document had clears `hasUnsavedChanges`; a change during the read, or after it (a
+	* did-save script), keeps it. Closing the document, or `signal`, cancels it.
+	*/
+	async function downloadFile(documentId, signal, verb, read, refuse) {
+		const session = readySession(documentId, verb);
+		if (!allowsOn(session.id, "doc.download")) throw permissionDenied("documents", "doc.download", `documents.${verb}`);
+		const refusal = refuse?.(session.handle);
+		if (refusal) throw refusal;
+		try {
+			await settle(session.settleFlushes, [signal, session.signal], report);
+			const handle = documentHandle(session.id);
+			if (!handle) throw new PluginError("not-ready", "documents", `no open document to ${verb}`);
+			let readAt = -1;
+			const readFile = () => {
+				readAt = session.changeCount;
+				return cancellable("documents", signal, read(handle));
+			};
+			const bytes = await readWrapped(session.downloadWraps, readFile);
+			if (readAt === session.changeCount) setUnsavedChanges(session, false);
+			return bytes;
+		} catch (error) {
+			throw toPluginError("documents", error);
+		}
+	}
+	/** Whether the plugin's `create()` is running for this document: it has no capability yet. */
+	const isBuilding = (plugin, session) => session.building.has(plugin) && !session.capabilities.has(plugin);
 	function buildDocumentCapability(plugin, session) {
 		let capability = session.capabilities.get(plugin);
 		if (!capability) {
-			capability = plugin.capability(createPluginContext(services, plugin, session));
+			if (session.building.has(plugin)) throw new PluginError("not-ready", plugin.id, `"${plugin.id}" was asked for while it is being created`);
+			const ctx = createPluginContext(services, plugin, session, session.signal, session.scope);
+			session.building.add(plugin);
+			let created;
+			try {
+				created = plugin.create(ctx);
+			} finally {
+				session.building.delete(plugin);
+			}
+			const { api, connect } = created;
+			capability = api;
+			session.connectors.set(plugin, () => {
+				connect?.();
+				markConnected(ctx);
+			});
 			session.capabilities.set(plugin, capability);
 		}
 		return capability;
 	}
+	/**
+	* A workspace capability as a document's scope sees it: the view its plugin declares
+	* (`inScope`), built once per document and kept on the session, so it is the same object on
+	* every call and goes when the document closes. Without a document, or for a document the
+	* kernel doesn't know, it is the capability itself.
+	*/
+	function workspaceViewOf(token, capability, documentId) {
+		const inScope = inScopeByToken.get(token);
+		const session = documentId === void 0 ? void 0 : sessions.get(documentId);
+		if (!inScope || !session) return capability;
+		let view = session.views.get(token);
+		if (view === void 0) {
+			view = inScope(capability, session.id);
+			session.views.set(token, view);
+		}
+		return view;
+	}
 	function resolveCapability(token, documentId) {
 		guardUsable(`capability("${token.name}")`);
 		const workspaceCapability = workspaceCapabilities.get(token);
-		if (workspaceCapability) return workspaceCapability;
+		if (workspaceCapability) return workspaceViewOf(token, workspaceCapability, documentId);
 		const provider = plan.providerOf(token);
 		if (!provider) throw new Error(`No capability "${token.name}".`);
 		const id = documentId ?? store.getCore().activeId;
@@ -530,55 +584,91 @@ function createKernel(opts) {
 	function tryResolveInternal(token, documentId) {
 		if (status === "destroying" || status === "destroyed") return null;
 		const workspaceCapability = workspaceCapabilities.get(token);
-		if (workspaceCapability) return workspaceCapability;
+		if (workspaceCapability) return workspaceViewOf(token, workspaceCapability, documentId);
 		const provider = plan.providerOf(token);
 		if (!provider) return null;
 		const session = sessionOf(documentId);
 		if (!session || session.phase !== "bringup" && session.phase !== "ready") return null;
+		if (isBuilding(provider, session)) return null;
 		return buildDocumentCapability(provider, session);
 	}
 	/** Public total resolver — see `Kernel.tryCapability`. `ready` only: the
-	*  null→instance flip at commit time IS the adapters' re-render signal. */
+	*  null→instance flip at commit time is the adapters' re-render signal. */
 	function tryResolveCapability(token, documentId) {
 		if (status === "destroying" || status === "destroyed") return null;
 		const workspaceCapability = workspaceCapabilities.get(token);
-		if (workspaceCapability) return workspaceCapability;
+		if (workspaceCapability) return workspaceViewOf(token, workspaceCapability, documentId);
 		const provider = plan.providerOf(token);
 		if (!provider) return null;
 		const session = sessionOf(documentId);
 		if (!session || session.phase !== "ready") return null;
+		if (isBuilding(provider, session)) return null;
 		return buildDocumentCapability(provider, session);
 	}
+	const viewerSettings = createSettingsStore({
+		defaults: VIEWER_DEFAULTS,
+		registered: config.settings,
+		whole: VIEWER_WHOLE_SETTINGS
+	}, store.notify, report);
+	workspaceScope.defer(() => viewerSettings.dispose());
+	const settingsStores = /* @__PURE__ */ new Map();
+	for (const plugin of plan.ordered) if (plugin.settings) settingsStores.set(plugin, createSettingsStore(plugin.settings, store.notify, report));
+	workspaceScope.defer(() => {
+		for (const settings of settingsStores.values()) settings.dispose();
+	});
+	function settingsOf(token) {
+		const provider = plan.providerOf(token);
+		if (!provider) throw new Error(`No capability "${token.name}".`);
+		const settings = settingsStores.get(provider);
+		if (!settings) throw new Error(`Plugin "${provider.id}" has no settings.`);
+		return settings.api;
+	}
 	const services = {
 		engine,
 		store,
 		workspaceScope,
+		workspaceSignal: workspaceCancel.signal,
+		workspaceLeases,
+		report,
+		clock: config.clock ?? timerClock,
 		resolveCapability,
 		tryResolveCapability: tryResolveInternal,
-		documentHandle
+		documentHandle,
+		settingsStoreOf: (plugin) => settingsStores.get(plugin)
 	};
 	let ticketCounter = 0;
 	const nextTicket = () => `pending:${++ticketCounter}`;
-	/** Slices + event subscription + plugin inits + effect SETUP — every step's
-	*  release deferred into the session scope, every await followed by a
-	*  checkpoint. Runs entirely pre-commit: a failure anywhere rolls the whole
-	*  session back and the document was never `ready`. */
+	/** Slices, the registry's event subscription, and every plugin's
+	*  construction and connection — every step's release deferred into the
+	*  session scope, every await followed by a checkpoint. Runs entirely
+	*  pre-commit: a failure anywhere rolls the whole session back and the
+	*  document was never `ready`. */
 	async function bringUp(session, snapshot) {
 		session.phase = "bringup";
 		let renderPolicy = CONTINUOUS_RENDER_POLICY$1;
 		try {
-			renderPolicy = await session.handle.render?.policy() ?? CONTINUOUS_RENDER_POLICY$1;
+			renderPolicy = await session.handle.render?.getPolicy() ?? CONTINUOUS_RENDER_POLICY$1;
 		} catch {}
 		checkpoint(session);
 		session.stagedMeta = {
 			id: session.id,
+			instanceId: session.instanceId,
 			name: session.name,
 			pageCount: snapshot.pageCount,
 			pages: snapshot.pages,
 			revision: 0,
-			renderPolicy
+			renderPolicy,
+			hasUnsavedChanges: false
 		};
+		const tracksChanges = isLocalDocument(session.handle);
+		const bursts = createBurstGate(store);
+		session.scope.defer(bursts.close);
 		const unsubscribeEvents = session.handle.events.subscribe((event) => {
+			bursts.first(event);
+			if (tracksChanges && changesDocument(event)) {
+				session.changeCount += 1;
+				setUnsavedChanges(session, true);
+			}
 			const layout = layoutFromEvent(event);
 			if (!layout) return;
 			const now = store.getCore();
@@ -590,72 +680,131 @@ function createKernel(opts) {
 				pages: layout.pages,
 				revision: existing.revision + 1
 			};
-			store.setCore({ documents: {
+			setCore({ documents: {
 				...now.documents,
 				[session.id]: updated
-			} }, { type: CORE_DOCUMENT_PAGES_UPDATED });
+			} });
+			pagesChanged.emit({
+				documentId: session.id,
+				revision: updated.revision,
+				pages: updated.pages
+			});
 		});
 		session.scope.defer(unsubscribeEvents);
 		for (const plugin of documentScopedPlugins) {
-			const key = sliceKey(plugin.id, session.id);
-			store.registerSlice(key, reducerOf(plugin), initialStateOf(plugin));
-			session.scope.defer(() => store.removeSlice(key));
+			const lease = store.lease(sliceKey(plugin.id, session.id), initialStateOf(plugin), session.instanceId);
+			session.leases.set(plugin, lease);
+			session.scope.defer(() => lease.revoke());
 		}
-		for (const plugin of documentScopedPlugins) {
-			await plugin.init?.(createPluginContext(services, plugin, session));
-			checkpoint(session);
+		const release = store.hold();
+		try {
+			for (const plugin of documentScopedPlugins) {
+				buildDocumentCapability(plugin, session);
+				session.connectors.get(plugin)?.();
+			}
+		} finally {
+			release();
 		}
-		for (const plugin of documentScopedPlugins) plugin.effects?.(createEffectContext(services, plugin, session));
+		session.scope.defer(session.handle.events.subscribe((event) => bursts.last(event)));
 		checkpoint(session);
 	}
-	async function openDocument(input, options) {
+	/** What `open()` and `retry()` resolve: the document as its tab shows it, ready or locked. */
+	function openedResult(session) {
+		const core = store.getCore();
+		const entry = core.documents[session.id] ?? core.pending[session.id];
+		if (!entry) throw new PluginError("instance-closed", "documents", `${session.id} was closed`);
+		return { document: documentInfoOf(entry) };
+	}
+	async function openDocument(input, options, slotId) {
+		const signal = options?.signal;
+		if (signal?.aborted) throw new PluginError("operation-cancelled", "documents", "the open was cancelled");
+		try {
+			const { session, done } = reserveAndOpen(input, options, slotId);
+			const cancel = () => void session.close();
+			signal?.addEventListener("abort", cancel, { once: true });
+			try {
+				return openedResult(await done);
+			} finally {
+				signal?.removeEventListener("abort", cancel);
+			}
+		} catch (error) {
+			throw toPluginError("documents", error);
+		}
+	}
+	/**
+	* The engine's open options for a document: its own, and the viewer's `scope` and
+	* `identity` where it has none. A document's own replace the viewer's, never merge.
+	*/
+	function engineOptionsOf(options) {
+		const { activate: _activate, name: _name, signal: _signal, ...own } = options ?? {};
+		const viewer = viewerSettings.api.getSettings();
+		const scope = own.scope ?? viewer.scope ?? void 0;
+		const identity = own.identity ?? viewer.identity ?? void 0;
+		return {
+			...own,
+			...scope !== void 0 ? { scope } : {},
+			...identity !== void 0 ? { identity } : {}
+		};
+	}
+	/**
+	* Reserve the tab slot synchronously and start the open; returns the slot id at once.
+	* `slotId` is a failed document's tab, which `retry()` opens again in place.
+	*/
+	function reserveAndOpen(input, options, slotId) {
 		guardUsable("documents.open()");
-		const { activate, name, ...engineOptions } = options ?? {};
-		const requestedId = typeof input === "function" ? nextTicket() : idOfInput(input) ?? nextTicket();
-		if (sessions.has(requestedId)) throw new Error(`[documents] document already open: ${requestedId}`);
-		const session = createSession(requestedId, name);
+		const engineOptions = engineOptionsOf(options);
+		const requestedId = slotId ?? (typeof input === "function" ? nextTicket() : idOfInput(input) ?? nextTicket());
+		if (sessions.has(requestedId)) throw new PluginError("conflict", "documents", `document already open: ${requestedId}`);
+		const session = createSession(requestedId, options?.name);
+		session.source = input;
+		session.openOptions = options;
 		sessions.set(session.id, session);
-		publishPendingSlot(session, activate ?? true);
-		return beginOperation(session, async () => {
-			try {
-				const source = typeof input === "function" ? await engineCall(session, Promise.resolve(input(session.cancel.signal))) : input;
-				checkpoint(session);
-				const sourceId = idOfInput(source);
-				if (sourceId) rekeySession(session, sourceId);
-				const handle = await engineCall(session, engine.open(source, engineOptions), (late) => late.close());
-				session.handle = handle;
-				session.scope.defer(() => handle.close());
-				checkpoint(session);
-				if (handle.id !== session.id) rekeySession(session, handle.id);
-				if (handle.security?.passwordPrompt?.state === "required") {
-					const passwordProvided = "password" in engineOptions && engineOptions.password != null || passwordOfInput(source) != null;
-					session.phase = "locked";
-					publishLocked(session, passwordProvided);
-					return session.id;
+		publishPendingSlot(session, options?.activate ?? true);
+		return {
+			session,
+			done: beginOperation(session, async () => {
+				try {
+					const given = typeof input === "function" ? await engineCall(session, Promise.resolve(input(session.cancel.signal))) : input;
+					checkpoint(session);
+					const source = isUrlSource(given) ? await engineCall(session, fetchUrlSource(given, session.cancel.signal)) : given;
+					checkpoint(session);
+					const sourceId = idOfInput(source);
+					if (sourceId) rekeySession(session, sourceId);
+					const handle = await engineCall(session, engine.open(source, engineOptions), (late) => late.close());
+					session.handle = handle;
+					session.scope.defer(() => handle.close());
+					checkpoint(session);
+					if (handle.id !== session.id) rekeySession(session, handle.id);
+					const prompt = handle.security?.passwordPrompt;
+					if (prompt?.state === "required") {
+						session.phase = "locked";
+						publishLocked(session, prompt.incorrect);
+						return session;
+					}
+					const snapshot = await engineCall(session, handle.pages.list());
+					checkpoint(session);
+					await bringUp(session, snapshot);
+					commitReady(session);
+					return session;
+				} catch (error) {
+					if (isCancelled(error)) throw error;
+					if (session.phase === "closing" || isAbortLike(error)) throw new CancelledError(`closed while opening: ${session.id}`);
+					await session.scope.dispose();
+					session.phase = "error";
+					publishError(session, error);
+					throw error;
 				}
-				const snapshot = await engineCall(session, handle.pages.list());
-				checkpoint(session);
-				await bringUp(session, snapshot);
-				commitReady(session);
-				return session.id;
-			} catch (error) {
-				if (isCancelled(error)) throw error;
-				if (session.phase === "closing" || isAbortLike(error)) throw new CancelledError(`closed while opening: ${session.id}`);
-				await session.scope.dispose();
-				session.phase = "error";
-				publishError(session, error);
-				throw error;
-			}
-		});
+			})
+		};
 	}
-	async function unlockDocument(id, input) {
+	async function unlockDocument(id, options) {
 		guardUsable("documents.unlock()");
 		const session = sessions.get(id);
-		if (!session || session.phase !== "locked" || !session.handle) throw new Error(`[documents] document is not locked: ${id}`);
+		if (!session || session.phase !== "locked" || !session.handle) throw new PluginError("invalid-input", "documents", `document is not locked: ${id}`);
 		const handle = session.handle;
 		return beginOperation(session, async () => {
 			try {
-				await engineCall(session, handle.security.unlock({ password: input.password }));
+				await cancellable("documents", options.signal, engineCall(session, handle.security.unlock({ password: options.password })));
 			} catch (error) {
 				if (session.phase === "closing" || isAbortLike(error)) throw new CancelledError(`closed while opening: ${session.id}`);
 				throw error;
@@ -674,6 +823,8 @@ function createKernel(opts) {
 				publishError(session, error);
 				throw error;
 			}
+		}).catch((error) => {
+			throw toPluginError("documents", error);
 		});
 	}
 	async function closeDocument(documentId) {
@@ -682,18 +833,81 @@ function createKernel(opts) {
 		await session.close();
 	}
 	function reorder(next) {
-		store.setCore({ order: next }, { type: CORE_ORDER_CHANGED });
+		setCore({ order: next });
 	}
+	const metaOf = (documentId) => {
+		const core = store.getCore();
+		const id = documentId ?? core.activeId;
+		return id ? core.documents[id] ?? null : null;
+	};
+	/** The tab list: the same array until one of its documents changes, or the order does. */
+	let listMemo = null;
+	const listDocuments = () => {
+		const core = store.getCore();
+		if (listMemo?.core === core) return listMemo.value;
+		const next = core.order.map((id) => documentInfoOf(core.documents[id] ?? core.pending[id]));
+		const previous = listMemo?.value;
+		const value = previous !== void 0 && previous.length === next.length && previous.every((info, i) => info === next[i]) ? previous : Object.freeze(next);
+		listMemo = {
+			core,
+			value
+		};
+		return value;
+	};
+	/** A document's fields: `documentId`, or the active document's. */
+	const getDocument = (documentId) => {
+		const core = store.getCore();
+		const id = documentId ?? core.activeId;
+		const entry = id ? core.documents[id] ?? core.pending[id] : void 0;
+		return entry ? documentInfoOf(entry) : null;
+	};
 	const documents = {
 		open: openDocument,
-		openAll: (docs) => {
+		canOpenFiles: () => engine.canOpenFiles,
+		retry: async (id, options) => {
+			const session = sessions.get(id);
+			if (!session || session.phase !== "error" || session.source === null) throw new PluginError("invalid-input", "documents", `${id} didn't fail to open; nothing to retry`);
+			const { source, openOptions } = session;
+			sessions.delete(id);
+			return openDocument(source, {
+				...openOptions,
+				activate: false,
+				signal: options?.signal
+			}, id);
+		},
+		rename: (id, name) => {
+			const core = store.getCore();
+			if (core.documents[id]) setCore({ documents: {
+				...core.documents,
+				[id]: {
+					...core.documents[id],
+					name
+				}
+			} });
+			else if (core.pending[id]) setCore({ pending: {
+				...core.pending,
+				[id]: {
+					...core.pending[id],
+					name
+				}
+			} });
+			const session = sessions.get(id);
+			if (session) session.name = name;
+		},
+		openAll: (initialDocuments) => {
 			guardUsable("documents.openAll()");
-			const activeIndex = Math.max(0, docs.findIndex((d) => d.active));
-			docs.forEach(({ source, active: _active, ...options }, index) => {
-				openDocument(source, {
-					...options,
-					activate: index === activeIndex
-				}).catch(() => {});
+			const activeIndex = Math.max(0, initialDocuments.findIndex((initialDocument) => initialDocument.active));
+			return initialDocuments.map(({ source, active: _active, ...options }, index) => {
+				try {
+					const { session, done } = reserveAndOpen(source, {
+						...options,
+						activate: index === activeIndex
+					});
+					done.catch(() => {});
+					return session.id;
+				} catch {
+					return typeof source === "function" ? "" : idOfInput(source) ?? "";
+				}
 			});
 		},
 		unlock: unlockDocument,
@@ -703,67 +917,77 @@ function createKernel(opts) {
 		},
 		setActive: (id) => {
 			const core = store.getCore();
-			if (core.documents[id] || core.pending[id]) store.setCore({ activeId: id }, { type: CORE_ACTIVE_CHANGED });
-		},
-		activeId: () => store.getCore().activeId,
-		list: () => store.getCore().order.map((id) => {
-			const core = store.getCore();
-			const meta = core.documents[id];
-			return meta ? toDocInfo(meta) : pendingToDocInfo(core.pending[id]);
-		}),
-		get: (id) => {
-			const core = store.getCore();
-			const meta = core.documents[id];
-			if (meta) return toDocInfo(meta);
-			const pending = core.pending[id];
-			return pending ? pendingToDocInfo(pending) : null;
+			if (core.documents[id] || core.pending[id]) setCore({ activeId: id });
 		},
+		getActiveId: () => store.getCore().activeId,
+		getActive: () => getDocument(),
+		list: listDocuments,
+		get: getDocument,
 		has: (id) => {
 			const core = store.getCore();
 			return core.documents[id] !== void 0 || core.pending[id] !== void 0;
 		},
-		count: () => store.getCore().order.length,
-		order: () => [...store.getCore().order],
+		getCount: () => store.getCore().order.length,
+		getOrder: () => store.getCore().order,
+		setOrder: (ids) => {
+			const current = store.getCore().order;
+			if (!(ids.length === current.length && [...ids].sort().join("\0") === [...current].sort().join("\0"))) throw new PluginError("invalid-input", "documents", "setOrder() needs a permutation of the current order");
+			reorder([...ids]);
+		},
 		move: (id, toIndex) => {
 			const core = store.getCore();
 			if (!core.documents[id] && !core.pending[id]) return;
-			const without = core.order.filter((x) => x !== id);
+			const without = core.order.filter((documentId) => documentId !== id);
 			const clamped = Math.max(0, Math.min(toIndex, without.length));
 			without.splice(clamped, 0, id);
 			reorder(without);
 		},
-		swap: (a, b) => {
+		swap: (id, otherId) => {
 			const core = store.getCore();
-			const indexA = core.order.indexOf(a);
-			const indexB = core.order.indexOf(b);
-			if (indexA < 0 || indexB < 0) return;
+			const index = core.order.indexOf(id);
+			const otherIndex = core.order.indexOf(otherId);
+			if (index < 0 || otherIndex < 0) return;
 			const next = [...core.order];
-			next[indexA] = b;
-			next[indexB] = a;
+			next[index] = otherId;
+			next[otherIndex] = id;
 			reorder(next);
 		},
-		download: (id, opts) => {
-			const handle = documentHandle(id);
-			if (!handle) return Promise.reject(/* @__PURE__ */ new Error("[documents] no document to download"));
-			return handle.download(opts);
-		},
-		downloadLayer: (id) => {
-			const handle = documentHandle(id);
-			if (!handle) return Promise.reject(/* @__PURE__ */ new Error("[documents] no document to download"));
-			if (!handle.downloadLayer) return Promise.reject(/* @__PURE__ */ new Error("[documents] this engine cannot export a layer (open with a layer on the local engine)"));
-			return handle.downloadLayer();
-		},
-		allows: (cap, id) => documentHandle(id)?.security.allows(cap) ?? false
+		download: (id, options) => downloadFile(id, options?.signal, "download", (handle) => handle.download(options?.mode !== void 0 ? { mode: options.mode } : void 0)),
+		downloadLayer: (id, options) => downloadFile(id, options?.signal, "downloadLayer", (handle) => isLocalDocument(handle) ? handle.downloadLayer() : Promise.reject(noLayer()), (handle) => isLocalDocument(handle) ? null : noLayer()),
+		canDownload: (id) => allowsOn(id, "doc.download"),
+		canPrint: (id) => allowsOn(id, "doc.print"),
+		listPages: (id) => metaOf(id)?.pages ?? EMPTY_PAGES,
+		getPage: (page, id) => findPage(metaOf(id)?.pages ?? EMPTY_PAGES, page),
+		getPageIndex: (ref, id) => metaOf(id)?.pages.findIndex((pageInfo) => pageRefsEqual$1(pageInfo.ref, ref)) ?? -1,
+		getRevision: (id) => metaOf(id)?.revision ?? -1,
+		onOpened: opened.on,
+		onOpenFailed: openFailed.on,
+		onLocked: locked.on,
+		onClosed: closed.on,
+		onActiveChanged: activeChanged.on,
+		onPagesChanged: pagesChanged.on,
+		onUnsavedChangesChanged: unsavedChangesChanged.on
 	};
 	workspaceCapabilities.set(DocumentsToken, documents);
-	for (const plugin of plan.ordered) if (!isDocumentScoped(plugin)) store.registerSlice(plugin.id, reducerOf(plugin), initialStateOf(plugin));
-	for (const plugin of plan.ordered) if (!isDocumentScoped(plugin) && plugin.token && plugin.capability) workspaceCapabilities.set(plugin.token, plugin.capability(createPluginContext(services, plugin)));
+	for (const plugin of plan.ordered) if (!isDocumentScoped(plugin)) workspaceLeases.set(plugin, store.lease(plugin.id, initialStateOf(plugin)));
+	for (const plugin of plan.ordered) {
+		if (isDocumentScoped(plugin)) continue;
+		const ctx = createPluginContext(services, plugin, void 0, workspaceCancel.signal, workspaceScope);
+		const { api, connect } = plugin.create(ctx);
+		if (plugin.token) workspaceCapabilities.set(plugin.token, api);
+		workspaceConnectors.set(plugin, () => {
+			connect?.();
+			markConnected(ctx);
+		});
+	}
 	return {
+		...viewerSettings.api,
 		engine,
 		documents,
 		capability: resolveCapability,
 		tryCapability: tryResolveCapability,
 		scopeOf: plan.scopeOf,
+		settingsOf,
 		subscribe: store.subscribe,
 		getState: store.getState,
 		status: () => status,
@@ -774,10 +998,8 @@ function createKernel(opts) {
 				try {
 					for (const plugin of plan.ordered) {
 						if (status !== "starting") return;
-						if (!isDocumentScoped(plugin)) await plugin.init?.(createPluginContext(services, plugin));
+						if (!isDocumentScoped(plugin)) workspaceConnectors.get(plugin)?.();
 					}
-					if (status !== "starting") return;
-					for (const plugin of plan.ordered) if (!isDocumentScoped(plugin)) plugin.effects?.(createEffectContext(services, plugin));
 					status = "started";
 				} catch (error) {
 					status = "failed";
@@ -791,6 +1013,7 @@ function createKernel(opts) {
 			return destroyPromise ?? (destroyPromise = (async () => {
 				const wasFailed = status === "failed";
 				status = "destroying";
+				workspaceCancel.abort(new CancelledError("kernel destroyed"));
 				await startPromise?.catch((error) => {
 					if (!isCancelled(error) && !wasFailed) report(error);
 				});
@@ -805,56 +1028,213 @@ function createKernel(opts) {
 	};
 }
 //#endregion
-//#region src/event-hook.ts
+//#region src/compose.ts
+function composeApi(capability, slices) {
+	const seen = /* @__PURE__ */ new Set();
+	const api = {};
+	for (const slice of slices) for (const key of Object.keys(slice)) {
+		if (seen.has(key)) throw new Error(`[${capability}] api member '${key}' is defined twice`);
+		seen.add(key);
+		api[key] = slice[key];
+	}
+	return api;
+}
+//#endregion
+//#region src/memo.ts
+const sameInputs = (left, right) => left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
 /**
-* Create one capability event.
-*
-* 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.
+* Recompute `compute(...inputs())` only when an input changes (compared with
+* `Object.is`, element by element); otherwise return the previous result.
 */
-function createEventHook(onListenerError) {
-	let listeners = /* @__PURE__ */ new Set();
-	return {
-		on(listener) {
-			if (!listeners) return () => {};
-			listeners.add(listener);
-			return () => void listeners?.delete(listener);
-		},
-		emit(event) {
-			if (!listeners) return;
-			for (const listener of [...listeners]) try {
-				listener(event);
-			} catch (error) {
-				onListenerError?.(error);
-			}
-		},
-		dispose() {
-			listeners = null;
+function memo(inputs, compute) {
+	let last = null;
+	return () => {
+		const next = inputs();
+		if (last && sameInputs(last.inputs, next)) return last.result;
+		const result = compute(...next);
+		last = {
+			inputs: next,
+			result
+		};
+		return result;
+	};
+}
+/**
+* `memo` per key: each key keeps its own last inputs and result. Keys are
+* compared with `Map` semantics, so use primitives (a page object number, an
+* encoded key), not freshly built objects. `maxEntries` bounds the cache;
+* the oldest key is evicted first.
+*/
+function memoByKey(inputs, compute, options = {}) {
+	const cache = /* @__PURE__ */ new Map();
+	return (key) => {
+		const next = inputs(key);
+		const cached = cache.get(key);
+		if (cached && sameInputs(cached.inputs, next)) return cached.result;
+		const result = compute(key, ...next);
+		if (cached) cache.delete(key);
+		else if (options.maxEntries !== void 0 && cache.size >= options.maxEntries) {
+			const oldest = cache.keys().next();
+			if (!oldest.done) cache.delete(oldest.value);
 		}
+		cache.set(key, {
+			inputs: next,
+			result
+		});
+		return result;
+	};
+}
+//#endregion
+//#region src/state.ts
+/**
+* Declare a plugin's state. The fields come from `read`, and `empty` is checked
+* against them (`NoInfer` keeps it out of the inference): a missing field or a
+* value of the wrong type is a type error. Write `empty` inline, because
+* TypeScript refuses an extra field only in an object literal.
+*/
+function defineState(token, declaration) {
+	return {
+		token,
+		read: declaration.read,
+		empty: Object.freeze(declaration.empty),
+		...declaration.ensure ? { ensure: declaration.ensure } : {}
 	};
 }
+/**
+* One level of identity: equal when the two values are the same, or are
+* objects (or arrays) holding the same values under the same keys. Declared
+* state compares this way, and so does a value a selector picks from it.
+*/
+function shallowEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	if (Array.isArray(left) !== Array.isArray(right)) return false;
+	const leftFields = left;
+	const rightFields = right;
+	const keys = Object.keys(leftFields);
+	return keys.length === Object.keys(rightFields).length && keys.every((key) => key in rightFields && Object.is(leftFields[key], rightFields[key]));
+}
+//#endregion
+//#region src/documents-state.ts
+/**
+* The documents' State tables as code: the document a component talks to (React's
+* `useDocument()`), and every open document with the active one (`useDocumentsState()`). Each
+* adapter turns these into its own reactive form, as it does a plugin's.
+*/
+/** No document: none is open, or none is in scope. It reads as one still on its way. */
+const NO_DOCUMENT = Object.freeze({
+	id: "",
+	name: void 0,
+	status: "loading",
+	pageCount: 0,
+	hasUnsavedChanges: false,
+	passwordProvided: void 0,
+	error: void 0
+});
+/**
+* The document in scope (the capability resolved for a document, or else the active one): its
+* id, name, status, page count, unsaved changes, and why it's locked or failed.
+*/
+const documentState = defineState(DocumentsToken, {
+	read: (documents) => documents.get() ?? NO_DOCUMENT,
+	empty: NO_DOCUMENT
+});
+const documentsState = defineState(DocumentsToken, {
+	read: (documents) => ({
+		documents: documents.list(),
+		activeId: documents.getActiveId()
+	}),
+	empty: {
+		documents: [],
+		activeId: null
+	}
+});
 //#endregion
-//#region src/serial-queue.ts
+//#region src/capability-handle.ts
 /**
-* Small promise-tail queue: operations run strictly one at a time, in
-* submission order, and failures never poison later operations. The shared
-* serializer for per-document mutation/dispatch pipelines.
+* What every framework adapter's plugin API shares (`useStage()`, `inject(EpdfSearch)`): which
+* members are reads, and what a document plugin's API reaches while its part of the app has no
+* ready document.
 *
-* Direction law for nested queues: an operation running on queue A may
-* enqueue into queue B and await it, but never the reverse on the same pair —
-* a B-operation enqueueing back into A self-deadlocks behind its caller.
+* Reads follow the capability vocabulary (docs/conventions/naming.md): a member named `get*`,
+* `list*`, `is*`, `has*` or `can*` reads state, so an adapter makes a call to it in a template or
+* a derived value update when its answer changes, and every other member tracks nothing.
+*
+* Without a document there is no capability to call, so the API reaches a stand-in: reading a
+* member never throws, so chrome renders before the first document opens, and calling one refuses
+* with `not-ready`. A member the token lists in `promises` returns the refusal as a rejected
+* promise, as the capability itself would, so a `.catch()` sees it; every other member throws.
+* The settings calls work: a plugin's settings belong to the plugin, not to a document.
 */
-function createSerialQueue() {
-	let tail = Promise.resolve();
-	return (operation) => {
-		const result = tail.then(operation, operation);
-		tail = result.then(() => void 0, () => void 0);
-		return result;
+const READ = /^(?:get|list|is|has|can)(?:[A-Z]|$)/;
+/** Whether a capability member named `name` is a read: `get*`, `list*`, `is*`, `has*` or `can*`. */
+function isReadMember(name) {
+	return READ.test(name);
+}
+/** Whether the member at `path` (`'setValue'`, `'comments.reply'`) returns a promise, as `token` declares. */
+function returnsPromise(token, path) {
+	return token.promises?.[path] === true;
+}
+/** The capability members that work without a document: a plugin's settings are the plugin's own. */
+const SETTINGS_CALLS = /* @__PURE__ */ new Set([
+	"getSettings",
+	"updateSettings",
+	"resetSettings",
+	"onSettingsChanged"
+]);
+const standIns = /* @__PURE__ */ new WeakMap();
+/**
+* What a framework adapter's API reaches for a document plugin while its part of the app has no
+* ready document. One per kernel and token, so it is the same object on every read.
+*/
+function standInFor(kernel, token) {
+	let byToken = standIns.get(kernel);
+	if (!byToken) {
+		byToken = /* @__PURE__ */ new WeakMap();
+		standIns.set(kernel, byToken);
+	}
+	let standIn = byToken.get(token);
+	if (!standIn) {
+		standIn = createStandIn(token, () => kernel.settingsOf(token));
+		byToken.set(token, standIn);
+	}
+	return standIn;
+}
+/**
+* A Proxy whose every member is a function that refuses with `not-ready`. A member is itself such
+* a Proxy, so namespaces work too (`annotation.comments.reply`). Members are cached by path, so
+* `stage.zoomIn` is the same function on every read. `then`, symbol keys and keys that start with
+* `__` (a framework's own flags, such as Vue's `__v_isRef`) read as undefined: the stand-in is no
+* thenable, and inspecting it doesn't throw. The four settings calls forward to `settings()` when
+* called; for a plugin without settings, they refuse too.
+*/
+function createStandIn(token, settings) {
+	const refusal = () => new PluginError("not-ready", token.name, "no document is open");
+	const refuse = (path) => () => {
+		if (returnsPromise(token, path)) return Promise.reject(refusal());
+		throw refusal();
+	};
+	const forward = (name) => (...args) => {
+		let api;
+		try {
+			api = settings();
+		} catch {
+			throw refusal();
+		}
+		return api[name](...args);
 	};
+	const members = /* @__PURE__ */ new Map();
+	const memberOf = (parentPath, key) => {
+		if (typeof key === "symbol" || key === "then" || key.startsWith("__")) return void 0;
+		const path = parentPath ? `${parentPath}.${key}` : key;
+		let member = members.get(path);
+		if (!member) {
+			member = !parentPath && SETTINGS_CALLS.has(key) ? forward(key) : new Proxy(refuse(path), { get: (_refuse, next) => memberOf(path, next) });
+			members.set(path, member);
+		}
+		return member;
+	};
+	return new Proxy({}, { get: (_capability, key) => memberOf("", key) });
 }
 //#endregion
 //#region src/index.ts
@@ -862,18 +1242,35 @@ function createSerialQueue() {
 * Create a typed capability token. `name` is the token's identity (debugging,
 * error messages); `options.hint` is the authored remedy the kernel appends to
 * the missing-dependency error, so the error contains its own fix.
+* `options.promises` lists the members that return a promise, so a framework
+* adapter's stand-in rejects them, rather than throwing, while no document is
+* open; a document plugin whose capability has such members gives it.
 */
 function createCapabilityToken(name, options) {
 	return {
 		name,
-		hint: options?.hint
+		hint: options?.hint,
+		...options?.promises ? { promises: options.promises } : {}
 	};
 }
-/** Identity helper that pins a plugin's generics. The real win is inference. */
-function definePlugin(def) {
-	return def;
+/**
+* The host lens over a plugin's token: the same runtime object, typed with
+* the wider capability sibling plugins use. The one place that cast lives.
+*/
+function createHostToken(token) {
+	return token;
+}
+/**
+* Define a plugin. It returns the definition as it is, and reads the types from it, so a
+* plugin passes no type arguments: the capability from `token`, the state from `state`, the
+* settings from `settings.defaults`. `create` receives a `PluginContext<State, Settings>`
+* and must return the capability. A plugin without `state` is stateless (`void`); one
+* without `settings` has `NoSettings`, and `ctx.settings()` throws there.
+*/
+function definePlugin(definition) {
+	return definition;
 }
 //#endregion
-export { AbortablePromise, CONTINUOUS_RENDER_POLICY, CORE_ACTIVE_CHANGED, CORE_DOCUMENT_ADDED, CORE_DOCUMENT_LOCKED, CORE_DOCUMENT_OPENING, CORE_DOCUMENT_OPEN_FAILED, CORE_DOCUMENT_PAGES_UPDATED, CORE_DOCUMENT_REMOVED, CORE_ORDER_CHANGED, CancelledError, DocumentsToken, PermissionDenied, createCapabilityToken, createEventHook, createKernel, createSerialQueue, definePlugin, docInfoEquals, docInfoListEquals, isCancelled, snapAppearanceScale, snapFullPageViewport, snapTileScale };
+export { AbortablePromise, CONTINUOUS_RENDER_POLICY, CancelledError, DocumentsToken, PermissionDenied, PluginError, VIEWER_DEFAULTS, VIEWER_WHOLE_SETTINGS, annotationKey, composeApi, createCapabilityToken, createEventHook, createHostToken, createKernel, createLatestLane, createSerialQueue, decodePageKey, definePlugin, defineState, documentState, documentsState, encodePageKey, guardHandle, isCancelled, isLocalEngine, isPluginError, isReadMember, memo, memoByKey, mergeSettings, pageRefsEqual, reload, resolvePageLayers, returnsPromise, shallowEqual, snapAppearanceScale, snapFullPageViewport, snapTileScale, standInFor, timerClock, toPageRef, toPluginError, toPluginErrorInfo, viewerSettingsOf };
 
 //# sourceMappingURL=index.js.map