@embedpdf/plugin-stamp 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.js

@@ -1,14 +1,686 @@
-import { a as STAMP_PIECEINFO_VERSION, c as libraryKindFromPdfName, d as stampKey, f as stampKindToPdfName, i as STAMP_PIECEINFO_APP, l as libraryKindToPdfName, m as stampPieceInfo, n as DEFAULT_LIBRARY_KIND, o as assetIdFor, p as stampLibraryPieceInfo, r as STAMP_LIBRARY_PIECEINFO_APP, s as customStampName, t as StampToken, u as parseStampKey } from "./contract-B79Onij2.js";
-import { createEventHook, definePlugin } from "@embedpdf/core";
-import { EngineError, EngineErrorCode, resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
-import { javaScriptProgramFromActionTree } from "@embedpdf/core-acrojs";
-import { ActionsToken } from "@embedpdf/plugin-actions/contract/host";
+import { a as assetIdFor, c as parseStampKey, d as stampPieceInfo, f as StampToken, i as STAMP_PIECEINFO_APP, l as stampKey, n as DEFAULT_LIBRARY_KIND, o as customStampName, r as STAMP_LIBRARY_PIECEINFO_APP, s as libraryKindFromPdfName, t as STAMP_DEFAULTS, u as stampLibraryPieceInfo } from "./contract-CJBvneyw.js";
+import { DocumentsToken, PluginError, composeApi, definePlugin, defineState, toPluginError, toPluginErrorInfo } from "@embedpdf/core";
+import { ActionsToken } from "@embedpdf/plugin-actions/contract";
 import { AnnotationToken } from "@embedpdf/plugin-annotation/contract";
+import { formEffectOps, isLocalEngine, resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
+import { javaScriptProgramFromActionTree } from "@embedpdf/core-acrojs";
+import { ActionsToken as ActionsToken$1 } from "@embedpdf/plugin-actions/contract/host";
 import { AnnotationToken as AnnotationToken$1 } from "@embedpdf/plugin-annotation/contract/host";
 import { createFormScriptingController } from "@embedpdf/plugin-form/scripting";
+//#region src/services/errors.ts
+/** A `PluginError` raised by the stamp plugin. */
+const stampError = (code, message) => new PluginError(code, "stamp", message);
+const notFound = (what, id) => stampError("not-found", `unknown ${what} '${id}'`);
+/**
+* A refusal that names the missing permission. The stamp plugin acts on a
+* document it isn't bound to, so it asks that document's checks instead of
+* `ctx.assertAllowed`, and refuses with the same error.
+*/
+const permissionDenied = (permission, operation) => new PluginError("permission-denied", "stamp", `${operation} requires ${permission}`, { permission });
+/** Stop before the next step, or before anything is kept, once the caller cancelled. */
+const throwIfCancelled = (signal) => {
+	if (signal?.aborted) throw new PluginError("operation-cancelled", "stamp", "operation cancelled", { cause: signal.reason });
+};
+/**
+* A capability verb: whatever the asset engine, a sibling plugin or a binary
+* source rejects with reaches the caller as a `PluginError`.
+*/
+const verb = (run) => async (...args) => {
+	try {
+		return await run(...args);
+	} catch (error) {
+		throw toPluginError("stamp", error);
+	}
+};
+//#endregion
+//#region src/read/catalog.ts
+/** Reads over the state and the binaries resource: libraries, assets,
+*  previews, the library's PDF, and the checks. */
+function createCatalog(ctx, { binaries, assetEngine, ghosts, targets }) {
+	const { binaries: assetBinaries, libraryBinaries } = binaries;
+	const { ghostProvider } = ghosts;
+	const { documentIdOf } = targets;
+	const listAssets = (filter) => {
+		const state = ctx.state.get();
+		return (filter?.libraryId ? [filter.libraryId] : state.libraryOrder).flatMap((libraryId) => (state.libraries[libraryId]?.assetIds ?? []).map((id) => state.assets[id])).filter((asset) => asset != null && (!filter?.kind || asset.kind === filter.kind) && (!filter?.category || (asset.categories ?? []).includes(filter.category)));
+	};
+	/** Placing is annotation work: the document's annotation plugin answers. */
+	const canPlace = (documentId) => {
+		const id = documentIdOf(documentId);
+		if (!id) return false;
+		return ctx.tryForDocument(AnnotationToken, id)?.canCreate() ?? false;
+	};
+	/** A stamp made from annotations copies them out of the document, as a download does. */
+	const canCreateFromAnnotations = (documentId) => {
+		const id = documentIdOf(documentId);
+		return id !== null && ctx.get(DocumentsToken).canDownload(id);
+	};
+	return {
+		canPlace,
+		canCreateFromAnnotations,
+		api: {
+			listLibraries: (filter) => {
+				const state = ctx.state.get();
+				const kinds = filter?.kind === void 0 ? null : new Set(typeof filter.kind === "string" ? [filter.kind] : filter.kind);
+				return state.libraryOrder.map((id) => state.libraries[id]).filter((library) => library != null && (kinds === null || kinds.has(library.kind)));
+			},
+			getLibrary: (libraryId) => ctx.state.get().libraries[libraryId] ?? null,
+			listAssets,
+			getAsset: (assetId) => ctx.state.get().assets[assetId] ?? null,
+			getAssetPreview: (assetId) => assetBinaries.get(assetId)?.preview ?? null,
+			renderAssetPreview: verb(async (assetId, { width, signal }) => {
+				throwIfCancelled(signal);
+				const binary = assetBinaries.get(assetId);
+				if (!binary) throw notFound("asset", assetId);
+				const preview = await ctx.cancellable(signal, ghostProvider(binary.bytes, binary.preview, assetId)(width));
+				return preview ? {
+					bytes: preview.bytes,
+					mimeType: preview.mimeType ?? "image/png"
+				} : null;
+			}),
+			readAssetBytes: (assetId) => {
+				const bytes = assetBinaries.get(assetId)?.bytes;
+				return bytes ? new Uint8Array(bytes) : null;
+			},
+			exportLibrary: async (libraryId, options) => {
+				throwIfCancelled(options?.signal);
+				const bytes = libraryBinaries.get(libraryId);
+				if (!bytes) throw notFound("library", libraryId);
+				return new Uint8Array(bytes);
+			},
+			canPlace,
+			canCreateFromAnnotations,
+			canImport: assetEngine.canImport
+		}
+	};
+}
+//#endregion
+//#region src/services/asset-engine.ts
+/**
+* The asset engine port and the canonical-library services every write
+* needs: opening library bytes as a document on a local engine, import-time
+* previews, and the import-support fact learned from the first import.
+*/
+/** Session-unique ids (scratch documents, library ids a file does not carry):
+*  a timestamp plus a counter. */
+let idCounter = 0;
+const uid = (prefix) => `${prefix}-${Date.now().toString(36)}-${(idCounter++).toString(36)}`;
+function createAssetEngine(ctx) {
+	const settings = ctx.settings();
+	/** Set once an import finds the asset engine is not local (cloud). */
+	let importSupported = null;
+	let resolved = null;
+	/** Engines this plugin made through a configured function: destroyed with it. */
+	const owned = [];
+	const assetEngine = () => {
+		const configured = settings.get().assetEngine;
+		if (resolved?.from !== configured) {
+			const engine = !configured ? ctx.engine : typeof configured === "function" ? configured() : configured;
+			if (typeof configured === "function") owned.push(engine);
+			resolved = {
+				from: configured,
+				engine
+			};
+			importSupported = null;
+		}
+		return resolved.engine;
+	};
+	/** Library PDFs are sliced and tagged (`/PieceInfo`) on a local engine only. */
+	const openAssetDocument = async (bytes) => {
+		const engine = await assetEngine();
+		if (!isLocalEngine(engine)) {
+			if (importSupported !== false) {
+				importSupported = false;
+				ctx.notify();
+			}
+			throw stampError("unsupported", settings.get().assetEngine ? "the stamp plugin's assetEngine must be a local engine (createLocalEngine())" : "importing a library PDF needs a local engine, and this viewer's engine is a cloud engine. Pass stampPlugin({ assetEngine: () => import('@embedpdf/engine').then((module) => module.createLocalEngine()) }): it loads lazily, on first import.");
+		}
+		return engine.open({
+			kind: "bytes",
+			id: uid("stamp-import"),
+			bytes
+		}, { scope: ["*"] });
+	};
+	/** Import-time preview render to bytes. The asset engine is local by
+	*  definition, so the image source is always inline bytes. */
+	const imageToPreview = (image) => {
+		if (image.source.kind !== "bytes") throw stampError("unsupported", "the asset engine returned a URL-sourced render; asset engines must be local");
+		return {
+			bytes: image.source.bytes,
+			mimeType: image.contentType
+		};
+	};
+	/** Thumbnail render of one library page (the small picker image). */
+	const renderThumbnail = async (handle) => imageToPreview(await handle.render.image({
+		viewport: {
+			kind: "width",
+			width: settings.get().previewWidth
+		},
+		background: "transparent",
+		includeAnnotations: true,
+		format: "png"
+	}));
+	ctx.cleanup(() => {
+		resolved = null;
+		for (const engine of owned.splice(0)) Promise.resolve(engine).then((made) => made.destroy()).catch(() => {});
+	});
+	return {
+		openAssetDocument,
+		imageToPreview,
+		renderThumbnail,
+		/** Optimistic until an import finds the asset engine is not local (cloud). */
+		canImport: () => {
+			if (resolved && resolved.from !== settings.get().assetEngine) return true;
+			return importSupported !== false;
+		}
+	};
+}
+//#endregion
+//#region src/services/binaries.ts
+function createBinaries(ctx) {
+	/** Asset bytes (a one-page placement PDF) and the cached preview, by asset id. */
+	const binaries = /* @__PURE__ */ new Map();
+	/** The durable source of truth for a canonical library. Asset PDFs above
+	*  are derived page extractions; this map owns the rewritten whole PDF. */
+	const libraryBinaries = /* @__PURE__ */ new Map();
+	/** Whole-PDF rewrites are serialized per library, or two concurrent
+	*  appends could both start from the same bytes and lose one page. A
+	*  mutation whose signal fired while it waited never starts. */
+	const mutateLibrary = (libraryId, mutation, signal) => ctx.serialQueue(`library:${libraryId}`)(mutation, { signal });
+	/**
+	* Ghost renders, one per size bucket per asset, rendered lazily on the
+	* asset engine the first time the ghost is shown at that size and kept
+	* until the asset goes away. Materialized (dynamic) placements are
+	* user/time specific and cache only for their own arm (`cacheKey` null).
+	*/
+	const ghostRenders = /* @__PURE__ */ new Map();
+	ctx.cleanup(() => {
+		binaries.clear();
+		ghostRenders.clear();
+		libraryBinaries.clear();
+	});
+	return {
+		binaries,
+		libraryBinaries,
+		ghostRenders,
+		mutateLibrary
+	};
+}
+//#endregion
+//#region src/services/documents.ts
+/**
+* The document a placing verb acts on: the one its options name, else the
+* active one (a document's scope fills `documentId` in through the plugin's
+* `inScope`), and the page arguments resolved in it.
+*/
+function createTargets(ctx) {
+	const documents = () => ctx.get(DocumentsToken);
+	/** The document's id, or null with no document open. */
+	const documentIdOf = (documentId) => documentId ?? documents().getActiveId();
+	/** The document a verb acts on. Rejects `not-ready` with no document open. */
+	const targetOf = (options) => {
+		const documentId = documentIdOf(options?.documentId);
+		if (!documentId) throw stampError("not-ready", "no document is open");
+		return documentId;
+	};
+	/** A page argument of the document, as a ref or an index. Rejects `not-found`. */
+	const pageOf = (documentId, page) => {
+		const found = documents().getPage(page, documentId);
+		if (!found) throw stampError("not-found", `no page ${typeof page === "number" ? page : page.objectNumber} in document '${documentId}'`);
+		return found;
+	};
+	return {
+		documentIdOf,
+		targetOf,
+		pageOf
+	};
+}
+//#endregion
+//#region src/services/events.ts
+function createEvents(ctx) {
+	return {
+		libraryChanged: ctx.events.source(),
+		libraryCreated: ctx.events.source(),
+		libraryUpdated: ctx.events.source(),
+		libraryDeleted: ctx.events.source(),
+		assetCreated: ctx.events.source(),
+		assetUpdated: ctx.events.source(),
+		assetDeleted: ctx.events.source(),
+		armChanged: ctx.events.source()
+	};
+}
+//#endregion
+//#region src/services/ghosts.ts
+function createGhosts({ openAssetDocument, imageToPreview }, { ghostRenders }) {
+	const renderGhost = async (bytes, devicePixelWidth) => {
+		const doc = await openAssetDocument(new Uint8Array(bytes));
+		try {
+			const page = (await doc.pages.list()).pages[0];
+			if (!page) return null;
+			return imageToPreview(await doc.page(page.ref).render.image({
+				viewport: {
+					kind: "width",
+					width: devicePixelWidth
+				},
+				background: "transparent",
+				includeAnnotations: true,
+				format: "png"
+			}));
+		} finally {
+			await doc.close();
+		}
+	};
+	/** A resolution-aware ghost source for placement bytes: the page renders
+	*  at the requested width, cached per bucket under `cacheKey` when given. */
+	const ghostProvider = (bytes, fallback, cacheKey) => {
+		const local = cacheKey ? ghostRenders.get(cacheKey) ?? /* @__PURE__ */ new Map() : /* @__PURE__ */ new Map();
+		if (cacheKey) ghostRenders.set(cacheKey, local);
+		return (devicePixelWidth) => {
+			let pending = local.get(devicePixelWidth);
+			if (!pending) {
+				pending = renderGhost(bytes, devicePixelWidth).catch((error) => {
+					globalThis.console?.warn("[stamp] ghost render failed, using the thumbnail:", error);
+					return fallback;
+				});
+				local.set(devicePixelWidth, pending);
+			}
+			return pending;
+		};
+	};
+	return { ghostProvider };
+}
+//#endregion
+//#region src/services/index.ts
+/**
+* Plugin-private services every area is built on (not the kernel): the
+* events, the binaries resource, the asset engine port, the ghost renderer
+* and the document a placing verb acts on.
+*/
+function createServices(ctx) {
+	const binaries = createBinaries(ctx);
+	const assetEngine = createAssetEngine(ctx);
+	return {
+		events: createEvents(ctx),
+		binaries,
+		assetEngine,
+		ghosts: createGhosts(assetEngine, binaries),
+		targets: createTargets(ctx)
+	};
+}
+//#endregion
+//#region src/model.ts
+const initialStampState = () => ({
+	libraries: {},
+	libraryOrder: [],
+	assets: {},
+	armed: {}
+});
+/** Remember the asset armed on a document. */
+function armAsset(state, documentId, assetId) {
+	if (state.armed[documentId] === assetId) return state;
+	return {
+		...state,
+		armed: {
+			...state.armed,
+			[documentId]: assetId
+		}
+	};
+}
+/** Forget what was armed on these documents. */
+function disarmDocuments(state, documentIds) {
+	if (!documentIds.some((documentId) => documentId in state.armed)) return state;
+	const armed = { ...state.armed };
+	for (const documentId of documentIds) delete armed[documentId];
+	return {
+		...state,
+		armed
+	};
+}
+/** Append a library to the display order. */
+function addLibrary(state, library) {
+	return {
+		...state,
+		libraries: {
+			...state.libraries,
+			[library.id]: library
+		},
+		libraryOrder: [...state.libraryOrder, library.id]
+	};
+}
+/** Replace a known library's descriptor; an unknown id changes nothing. */
+function setLibrary(state, library) {
+	if (!state.libraries[library.id]) return state;
+	return {
+		...state,
+		libraries: {
+			...state.libraries,
+			[library.id]: library
+		}
+	};
+}
+/** Remove a library together with its assets. */
+function removeLibrary(state, libraryId) {
+	const library = state.libraries[libraryId];
+	if (!library) return state;
+	const { [libraryId]: _removed, ...libraries } = state.libraries;
+	const assets = { ...state.assets };
+	for (const id of library.assetIds) delete assets[id];
+	return {
+		...state,
+		libraries,
+		libraryOrder: state.libraryOrder.filter((id) => id !== libraryId),
+		assets
+	};
+}
+/** Add an asset to the end of its library; an asset of an unknown library changes nothing. */
+function addAsset(state, asset) {
+	const library = state.libraries[asset.libraryId];
+	if (!library) return state;
+	return {
+		...state,
+		assets: {
+			...state.assets,
+			[asset.id]: asset
+		},
+		libraries: {
+			...state.libraries,
+			[library.id]: {
+				...library,
+				assetIds: [...library.assetIds, asset.id]
+			}
+		}
+	};
+}
+/** Replace a known asset's descriptor; an unknown id changes nothing. */
+function setAsset(state, asset) {
+	if (!state.assets[asset.id]) return state;
+	return {
+		...state,
+		assets: {
+			...state.assets,
+			[asset.id]: asset
+		}
+	};
+}
+/** Remove an asset and its entry in its library's order. */
+function removeAsset(state, assetId) {
+	const asset = state.assets[assetId];
+	if (!asset) return state;
+	const { [assetId]: _removed, ...assets } = state.assets;
+	const library = state.libraries[asset.libraryId];
+	return {
+		...state,
+		assets,
+		libraries: library ? {
+			...state.libraries,
+			[library.id]: {
+				...library,
+				assetIds: library.assetIds.filter((id) => id !== assetId)
+			}
+		} : state.libraries
+	};
+}
+//#endregion
+//#region src/write/assets.ts
+function createAssetWrites(ctx, { events, binaries, assetEngine, targets }, { resolveAssetSource }, { createLibrary }, { canCreateFromAnnotations }) {
+	const { libraryChanged, assetCreated, assetUpdated, assetDeleted } = events;
+	const { binaries: assetBinaries, libraryBinaries, ghostRenders, mutateLibrary } = binaries;
+	const { openAssetDocument, renderThumbnail } = assetEngine;
+	const { targetOf, pageOf } = targets;
+	const createAsset = async (input, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		if (input.libraryId && !ctx.state.get().libraries[input.libraryId]) throw notFound("library", input.libraryId);
+		const resolved = await ctx.cancellable(signal, resolveAssetSource(input));
+		const meta = sniffBinaryMetadata(resolved.bytes);
+		if (!meta) throw stampError("invalid-input", "asset source must be PNG, JPEG, or single-page PDF bytes");
+		const isPdf = meta.mimeType === "application/pdf";
+		const name = input.name ?? customStampName();
+		const label = input.label ?? name;
+		if (name.length === 0 || name.includes("=")) throw stampError("invalid-input", `invalid stamp identifier '${name}': must be non-empty and contain no '='`);
+		const rasterSize = input.size ?? ("width" in meta ? {
+			width: meta.width,
+			height: meta.height
+		} : null);
+		if (!isPdf && (!rasterSize || rasterSize.width <= 0 || rasterSize.height <= 0)) throw stampError("invalid-input", "a raster asset needs a positive `size` (its page size in points)");
+		let suppliedPreview = null;
+		if (input.preview) {
+			const preview = await resolveBinarySource(input.preview);
+			suppliedPreview = {
+				bytes: new Uint8Array(preview.bytes),
+				mimeType: preview.mimeType ?? "image/png"
+			};
+		}
+		const libraryId = input.libraryId ?? (await createLibrary(label, { signal })).library.id;
+		return mutateLibrary(libraryId, async () => {
+			const liveLibrary = ctx.state.get().libraries[libraryId];
+			if (!liveLibrary) throw stampError("not-found", `library '${libraryId}' no longer exists`);
+			const assetId = assetIdFor(liveLibrary.id, name);
+			if (ctx.state.get().assets[assetId]) throw stampError("invalid-input", `library '${liveLibrary.name}' already has a stamp named '${name}'`);
+			const canonicalBytes = libraryBinaries.get(liveLibrary.id);
+			if (!canonicalBytes) throw stampError("operation-failed", `canonical bytes are missing for library '${liveLibrary.id}'`);
+			const doc = await ctx.cancellable(signal, openAssetDocument(canonicalBytes));
+			let appended;
+			try {
+				let page;
+				if (isPdf) {
+					const result = await doc.pages.insert(new Uint8Array(resolved.bytes));
+					if (result.insertedPages.length !== 1) throw stampError("invalid-input", "a library asset must be a single-page PDF");
+					page = result.insertedPages[0];
+				} else {
+					if (!doc.pages.flatten) throw stampError("unsupported", "raster assets need an asset engine with pages.flatten");
+					page = (await doc.pages.insertBlank({ size: rasterSize })).insertedPages[0];
+					await doc.page(page).annotations.create({
+						subtype: "stamp",
+						box: {
+							x: 0,
+							y: 0,
+							width: rasterSize.width,
+							height: rasterSize.height
+						},
+						fit: "fill"
+					}, { resources: { appearance: new Uint8Array(resolved.bytes) } });
+					if ((await doc.pages.flatten([page], { usage: "display" })).results.some(({ status }) => status !== "applied")) throw stampError("operation-failed", "flattening the raster into its page failed");
+				}
+				const layout = (await doc.pages.list()).pages.find((candidate) => candidate.ref.objectNumber === page.objectNumber);
+				const handle = doc.page(page);
+				if (!layout) throw stampError("operation-failed", "the new page is missing from the library layout");
+				await doc.pages.setName({
+					name: stampKey(name, label),
+					page
+				});
+				const asset = {
+					id: assetId,
+					libraryId: liveLibrary.id,
+					kind: input.kind ?? "stamp",
+					name,
+					label,
+					size: {
+						width: layout.size.width,
+						height: layout.size.height
+					},
+					page,
+					...input.subject !== void 0 ? { subject: input.subject } : {},
+					...input.categories !== void 0 ? { categories: input.categories } : {}
+				};
+				await handle.pieceInfo.update(STAMP_PIECEINFO_APP, stampPieceInfo(asset.kind, {
+					subject: asset.subject,
+					categories: asset.categories
+				}));
+				appended = {
+					asset,
+					bytes: await doc.pages.extract([page]),
+					preview: suppliedPreview ?? await renderThumbnail(handle),
+					canonical: await doc.download()
+				};
+			} finally {
+				await doc.close();
+			}
+			throwIfCancelled(signal);
+			libraryBinaries.set(liveLibrary.id, appended.canonical);
+			assetBinaries.set(appended.asset.id, {
+				bytes: appended.bytes,
+				preview: appended.preview
+			});
+			ctx.state.update(addAsset, appended.asset);
+			libraryChanged.emit({
+				libraryId: liveLibrary.id,
+				reason: "asset-added"
+			});
+			assetCreated.emit({
+				assetId: appended.asset.id,
+				libraryId: liveLibrary.id,
+				asset: appended.asset
+			});
+			return { asset: appended.asset };
+		}, signal);
+	};
+	const createAssetFromAnnotations = async (page, refs, input, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const documentId = targetOf(options);
+		if (!canCreateFromAnnotations(documentId)) throw permissionDenied("doc.download", "stamp.createAssetFromAnnotations");
+		const doc = ctx.documentHandle(documentId);
+		if (!doc) throw stampError("not-found", `document '${documentId}' is not open`);
+		const handle = doc.page(pageOf(documentId, page).ref);
+		const source = await ctx.cancellable(signal, handle.annotations.exportAppearance([...refs]));
+		return createAsset({
+			...input,
+			source
+		}, { signal });
+	};
+	const deleteAsset = async (id, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const initialAsset = ctx.state.get().assets[id];
+		if (!initialAsset) return;
+		return mutateLibrary(initialAsset.libraryId, async () => {
+			const asset = ctx.state.get().assets[id];
+			if (!asset) return;
+			const library = ctx.state.get().libraries[asset.libraryId];
+			if (!library) return;
+			const canonicalBytes = libraryBinaries.get(library.id);
+			if (!canonicalBytes) throw stampError("operation-failed", `canonical bytes are missing for library '${library.id}'`);
+			const doc = await ctx.cancellable(signal, openAssetDocument(canonicalBytes));
+			let rewritten;
+			try {
+				await doc.pages.delete([asset.page]);
+				rewritten = await doc.download();
+			} finally {
+				await doc.close();
+			}
+			throwIfCancelled(signal);
+			libraryBinaries.set(library.id, rewritten);
+			assetBinaries.delete(id);
+			ghostRenders.delete(id);
+			ctx.state.update(removeAsset, id);
+			libraryChanged.emit({
+				libraryId: library.id,
+				reason: "asset-removed"
+			});
+			assetDeleted.emit({
+				assetId: id,
+				libraryId: library.id,
+				asset: null
+			});
+		}, signal);
+	};
+	const updateAsset = async (id, patch, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const initial = ctx.state.get().assets[id];
+		if (!initial) throw notFound("asset", id);
+		return mutateLibrary(initial.libraryId, async () => {
+			const asset = ctx.state.get().assets[id];
+			const library = asset ? ctx.state.get().libraries[asset.libraryId] : void 0;
+			if (!asset || !library) throw notFound("asset", id);
+			const next = {
+				...asset,
+				...patch.label !== void 0 ? { label: patch.label } : {},
+				...patch.categories !== void 0 ? { categories: patch.categories } : {}
+			};
+			if (patch.subject === null) delete next.subject;
+			else if (patch.subject !== void 0) next.subject = patch.subject;
+			const canonicalBytes = libraryBinaries.get(library.id);
+			if (!canonicalBytes) throw stampError("operation-failed", `canonical bytes are missing for library '${library.id}'`);
+			const doc = await ctx.cancellable(signal, openAssetDocument(canonicalBytes));
+			let rewritten;
+			try {
+				if (next.label !== asset.label) await doc.pages.setName({
+					name: stampKey(asset.name, next.label),
+					page: asset.page,
+					replace: stampKey(asset.name, asset.label)
+				});
+				await doc.page(asset.page).pieceInfo.update(STAMP_PIECEINFO_APP, stampPieceInfo(next.kind, {
+					subject: next.subject,
+					categories: next.categories
+				}));
+				rewritten = await doc.download();
+			} finally {
+				await doc.close();
+			}
+			throwIfCancelled(signal);
+			libraryBinaries.set(library.id, rewritten);
+			ctx.state.update(setAsset, next);
+			libraryChanged.emit({
+				libraryId: library.id,
+				reason: "asset-updated"
+			});
+			assetUpdated.emit({
+				assetId: next.id,
+				libraryId: library.id,
+				asset: next
+			});
+			return { asset: next };
+		}, signal);
+	};
+	const moveAsset = async (id, to, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const asset = ctx.state.get().assets[id];
+		const binary = assetBinaries.get(id);
+		if (!asset || !binary) throw notFound("asset", id);
+		if (to.libraryId === asset.libraryId) return { asset };
+		const copy = await createAsset({
+			libraryId: to.libraryId,
+			source: new Uint8Array(binary.bytes),
+			kind: asset.kind,
+			label: asset.label,
+			...asset.subject !== void 0 ? { subject: asset.subject } : {},
+			...asset.categories ? { categories: [...asset.categories] } : {},
+			...binary.preview ? { preview: binary.preview.bytes } : {}
+		}, { signal });
+		await deleteAsset(id);
+		return copy;
+	};
+	const duplicateAsset = async (id, options) => {
+		throwIfCancelled(options?.signal);
+		const asset = ctx.state.get().assets[id];
+		const binary = assetBinaries.get(id);
+		if (!asset || !binary) throw notFound("asset", id);
+		return createAsset({
+			libraryId: asset.libraryId,
+			source: new Uint8Array(binary.bytes),
+			kind: asset.kind,
+			label: options?.label ?? `${asset.label} copy`,
+			...asset.subject !== void 0 ? { subject: asset.subject } : {},
+			...asset.categories ? { categories: [...asset.categories] } : {},
+			...binary.preview ? { preview: binary.preview.bytes } : {}
+		}, { signal: options?.signal });
+	};
+	return { api: {
+		createAsset: verb(createAsset),
+		createAssetFromAnnotations: verb(createAssetFromAnnotations),
+		updateAsset: verb(updateAsset),
+		deleteAsset: verb(deleteAsset),
+		moveAsset: verb(moveAsset),
+		duplicateAsset: verb(duplicateAsset)
+	} };
+}
+//#endregion
 //#region src/blank-library.ts
 /**
-* The seed of a new library: a one-page PDF whose page is UNREGISTERED — the
+* The seed of a new library: a one-page PDF whose page is unregistered, the
 * shape Acrobat itself gives a fresh stamp library (its first page is a
 * blank starter that no `/Names /Pages` key points at). A library must be a
 * PDF from the moment it exists, and a PDF must have a page; the unregistered
@@ -36,57 +708,13 @@ function blankLibraryPdf() {
 	return new Uint8Array(cached);
 }
 //#endregion
-//#region src/capability.ts
-const DEFAULT_PREVIEW_WIDTH = 256;
-/** `#rrggbb` → the engine's sRGB triplet. */
-const hexColor = (hex) => {
-	const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
-	if (!m) throw new EngineError(EngineErrorCode.InvalidArg, `[stamp] mark color must be #rrggbb, got '${hex}'`);
-	const n = parseInt(m[1], 16);
-	return {
-		r: n >> 16 & 255,
-		g: n >> 8 & 255,
-		b: n & 255
-	};
-};
-/** An exact ArrayBuffer over a view (the engine's binary idiom). */
-const toArrayBuffer = (bytes) => {
-	const out = new ArrayBuffer(bytes.byteLength);
-	new Uint8Array(out).set(bytes);
-	return out;
-};
-/** The rect an ink mark occupies, padded by its stroke. */
-const inkBounds = (strokes, strokeWidth) => {
-	let left = Infinity;
-	let bottom = Infinity;
-	let right = -Infinity;
-	let top = -Infinity;
-	for (const stroke of strokes) for (const { x, y } of stroke) {
-		if (x < left) left = x;
-		if (x > right) right = x;
-		if (y < bottom) bottom = y;
-		if (y > top) top = y;
-	}
-	if (!Number.isFinite(left)) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] an ink mark needs at least one point");
-	const pad = strokeWidth;
-	return {
-		left: left - pad,
-		bottom: bottom - pad,
-		right: right + pad,
-		top: top + pad
-	};
-};
-/** A generous box for typed text; the export crops to the glyphs. */
-const textBounds = (text, fontSize) => ({
-	left: 0,
-	bottom: 0,
-	right: Math.max(1, text.length) * fontSize * .75 + fontSize,
-	top: fontSize * 1.6
-});
-/** Session-unique ids. Assets are session-scoped for now (no persistence),
-*  so a timestamp + counter is enough — durable ids come with the store port. */
-let seq = 0;
-const uid = (prefix) => `${prefix}-${Date.now().toString(36)}-${(seq++).toString(36)}`;
+//#region src/write/libraries.ts
+/**
+* Library writes. A library is a PDF: its `/Title` is the name, its
+* `/Names /Pages` registry the assets, its pages the artwork, PieceInfo only
+* what has no standard home. Every whole-PDF rewrite rides the per-library
+* mutation queue.
+*/
 const entryString = (entries, key) => {
 	const entry = entries[key];
 	return entry?.type === "string" && entry.value.length > 0 ? entry.value : void 0;
@@ -107,130 +735,76 @@ const kindFromPdfName = (name) => {
 		default: return;
 	}
 };
-function createStampCapability(ctx, config = {}) {
-	/** Binary sidecar of the serializable store: asset bytes + cached preview,
-	*  keyed by asset id. The reducer never sees these (kernel rule 1). */
-	const binaries = /* @__PURE__ */ new Map();
-	/** The durable source of truth for a canonical library. Asset PDFs above
-	*  are derived page extractions; this map owns the rewritten whole PDF. */
-	const libraryBinaries = /* @__PURE__ */ new Map();
-	/** Whole-PDF rewrites must be serialized per library or two concurrent
-	*  appends could both start from the same bytes and lose one page. */
-	const libraryMutationTails = /* @__PURE__ */ new Map();
-	const mutateLibrary = (libraryId, mutation) => {
-		const result = (libraryMutationTails.get(libraryId) ?? Promise.resolve()).then(mutation);
-		const tail = result.then(() => void 0, () => void 0);
-		libraryMutationTails.set(libraryId, tail);
-		return result.finally(() => {
-			if (libraryMutationTails.get(libraryId) === tail) libraryMutationTails.delete(libraryId);
-		});
-	};
-	let assetEngineRef = null;
-	const assetEngine = () => {
-		if (!assetEngineRef) {
-			const cfg = config.assetEngine;
-			assetEngineRef = !cfg ? ctx.engine : typeof cfg === "function" ? cfg() : cfg;
-		}
-		return assetEngineRef;
-	};
-	const openAssetDocument = async (bytes) => {
-		try {
-			return await (await assetEngine()).open({
-				kind: "bytes",
-				id: uid("stamp-import"),
-				bytes
-			}, { scope: ["*"] });
-		} catch (err) {
-			if (!config.assetEngine && EngineError.is(err, EngineErrorCode.InvalidArg)) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] importing a library PDF needs an engine that can open local bytes, and this viewer's engine cannot (cloud). Pass stampPlugin({ assetEngine: () => import('@embedpdf/engine').then((m) => m.createLocalEngine()) }) — it loads lazily, on first import.");
-			throw err;
-		}
-	};
-	/** Import-time preview render → bytes. The asset engine is local by
-	*  definition, so the image source is always inline bytes. */
-	const imageToPreview = (image) => {
-		if (image.source.kind !== "bytes") throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] asset engine returned a URL-sourced render; asset engines must be local");
-		return {
-			bytes: image.source.bytes,
-			mimeType: image.contentType
-		};
-	};
-	const allocateId = (preferred, prefix, taken) => {
-		let id = preferred;
-		if (!id || taken.has(id)) do
-			id = uid(prefix);
-		while (taken.has(id));
-		taken.add(id);
-		return id;
-	};
-	const libraryChanged = createEventHook((error) => globalThis.console?.error("[stamp] onLibraryChanged observer failed:", error));
-	/** Thumbnail render of one library page (the small picker image). */
-	const renderThumbnail = async (handle) => imageToPreview(await handle.render.image({
-		viewport: {
-			kind: "width",
-			width: config.previewWidth ?? DEFAULT_PREVIEW_WIDTH
-		},
-		background: "transparent",
-		includeAnnotations: true,
-		format: "png"
-	}));
-	const createLibrary = async (name, opts) => {
-		const kind = opts?.kind ?? "stamps";
-		const taken = new Set(Object.keys(ctx.getState().libraries));
-		const id = allocateId(opts?.id, "stamp-lib", taken);
-		const doc = await openAssetDocument(blankLibraryPdf());
+const allocateId = (preferred, prefix, taken) => {
+	let id = preferred;
+	if (!id || taken.has(id)) do
+		id = uid(prefix);
+	while (taken.has(id));
+	taken.add(id);
+	return id;
+};
+function createLibraryWrites(ctx, { events, binaries, assetEngine }) {
+	const { libraryChanged, libraryCreated, libraryUpdated, libraryDeleted, assetCreated } = events;
+	const { binaries: assetBinaries, libraryBinaries, ghostRenders, mutateLibrary } = binaries;
+	const { openAssetDocument, renderThumbnail } = assetEngine;
+	const createLibrary = async (name, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const kind = options?.kind ?? "stamps";
+		const taken = new Set(Object.keys(ctx.state.get().libraries));
+		const id = allocateId(options?.id, "stamp-lib", taken);
+		const doc = await ctx.cancellable(signal, openAssetDocument(blankLibraryPdf()));
 		let bytes;
 		try {
-			requireCanonicalServices(doc);
 			await doc.metadata.update({ title: name });
 			await doc.pieceInfo.update(STAMP_LIBRARY_PIECEINFO_APP, stampLibraryPieceInfo(id, {
 				kind,
-				categories: opts?.categories
+				categories: options?.categories
 			}));
 			bytes = await doc.download();
 		} finally {
 			await doc.close();
 		}
+		throwIfCancelled(signal);
+		const library = {
+			id,
+			name,
+			kind,
+			assetIds: [],
+			...options?.categories ? { categories: options.categories } : {}
+		};
 		libraryBinaries.set(id, bytes);
-		ctx.dispatch({
-			type: "LIBRARY_ADDED",
-			library: {
-				id,
-				name,
-				kind,
-				assetIds: [],
-				...opts?.categories ? { categories: opts.categories } : {}
-			}
-		});
+		ctx.state.update(addLibrary, library);
 		libraryChanged.emit({
 			libraryId: id,
 			reason: "created"
 		});
-		return id;
-	};
-	const requireCanonicalServices = (doc) => {
-		if (!doc.pieceInfo) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need an asset engine with pieceInfo");
-		if (!doc.pages.setName || !doc.pages.removeName) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need an asset engine with named pages (pages.setName)");
+		libraryCreated.emit({
+			libraryId: id,
+			library
+		});
+		return { library };
 	};
-	const importLibraryPdf = async (source, opts) => {
-		const resolved = await resolveBinarySource(source);
-		if (sniffBinaryMetadata(resolved.bytes)?.mimeType !== "application/pdf") throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] importLibraryPdf needs PDF bytes (use addAsset for a raster image)");
-		const doc = await openAssetDocument(new Uint8Array(resolved.bytes));
+	const importLibrary = async (source, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const resolved = await ctx.cancellable(signal, resolveBinarySource(source));
+		if (sniffBinaryMetadata(resolved.bytes)?.mimeType !== "application/pdf") throw stampError("invalid-input", "importLibrary needs PDF bytes (use createAsset for a raster image)");
+		const doc = await ctx.cancellable(signal, openAssetDocument(new Uint8Array(resolved.bytes)));
 		let imported;
 		try {
-			requireCanonicalServices(doc);
 			const layout = await doc.pages.list();
-			if (layout.pageCount === 0) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] a canonical stamp library PDF must contain at least one page");
-			const byPon = new Map(layout.pages.map((page) => [page.pageObjectNumber, page]));
-			const catalogEntries = (await doc.pieceInfo.read("EMBD_StampLibrary"))?.entries ?? {};
-			const state = ctx.getState();
-			const takenLibraryIds = new Set(Object.keys(state.libraries));
+			if (layout.pageCount === 0) throw stampError("invalid-input", "a canonical stamp library PDF must contain at least one page");
+			const pagesByObjectNumber = new Map(layout.pages.map((page) => [page.ref.objectNumber, page]));
+			const catalogEntries = (await doc.pieceInfo.get("EMBD_StampLibrary"))?.entries ?? {};
+			const takenLibraryIds = new Set(Object.keys(ctx.state.get().libraries));
 			const libraryId = allocateId(entryString(catalogEntries, "Id"), "stamp-lib", takenLibraryIds);
-			const docMeta = await doc.metadata.read();
-			const libraryName = (docMeta.title && docMeta.title.length > 0 ? docMeta.title : void 0) ?? entryString(catalogEntries, "Name") ?? opts?.name ?? "Stamps";
+			const docMeta = await doc.metadata.get();
+			const libraryName = (docMeta.title && docMeta.title.length > 0 ? docMeta.title : void 0) ?? entryString(catalogEntries, "Name") ?? options?.name ?? "Stamps";
 			if (!docMeta.title) await doc.metadata.update({ title: libraryName });
-			const libraryCategories = opts?.categories ?? entryStringArray(catalogEntries, "Categories");
+			const libraryCategories = options?.categories ?? entryStringArray(catalogEntries, "Categories");
 			const libraryLocale = entryString(catalogEntries, "Locale");
-			const libraryKind = opts?.libraryKind ?? libraryKindFromPdfName(entryName(catalogEntries, "Kind"));
+			const libraryKind = options?.libraryKind ?? libraryKindFromPdfName(entryName(catalogEntries, "Kind"));
 			const registry = (layout.namedPages ?? []).filter((entry) => entry.target.kind === "page");
 			const hidden = (layout.namedPages ?? []).filter((entry) => entry.target.kind !== "page");
 			if (hidden.length > 0) globalThis.console?.warn(`[stamp] library '${libraryName}' carries ${hidden.length} hidden-template or dangling registration(s); they are not stamps and were ignored`);
@@ -239,35 +813,35 @@ function createStampCapability(ctx, config = {}) {
 				const seen = /* @__PURE__ */ new Set();
 				descriptors = registry.map((entry) => {
 					const { name, label } = parseStampKey(entry.name);
-					if (!name) throw new EngineError(EngineErrorCode.InvalidArg, `[stamp] library '${libraryName}': empty stamp identifier in key '${entry.name}'`);
-					if (seen.has(name)) throw new EngineError(EngineErrorCode.InvalidArg, `[stamp] library '${libraryName}': duplicate stamp identifier '${name}'`);
+					if (!name) throw stampError("invalid-input", `library '${libraryName}': empty stamp identifier in key '${entry.name}'`);
+					if (seen.has(name)) throw stampError("invalid-input", `library '${libraryName}': duplicate stamp identifier '${name}'`);
 					seen.add(name);
-					const page = byPon.get(entry.target.pageObjectNumber);
+					const page = pagesByObjectNumber.get(entry.target.page.objectNumber);
 					return {
-						pageObjectNumber: page.pageObjectNumber,
+						page: page.ref,
 						index: page.index,
 						name,
 						label
 					};
 				});
-				descriptors.sort((a, b) => a.index - b.index);
-			} else if (layout.namedPages === void 0) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] the asset engine reports no named-page registry (an older engine); upgrade it to import libraries");
+				descriptors.sort((left, right) => left.index - right.index);
+			} else if (layout.namedPages === void 0) throw stampError("unsupported", "the asset engine reports no named-page registry; an engine with named pages is needed to import libraries");
 			else {
 				descriptors = [];
 				for (const page of layout.pages) {
-					const v1 = (await doc.page(page.pageObjectNumber).pieceInfo?.read(STAMP_PIECEINFO_APP))?.entries;
-					const name = (v1 && entryString(v1, "Name")) ?? `Stamp${page.index + 1}`;
-					const label = (v1 && entryString(v1, "Subject")) ?? opts?.assetName?.(page.index) ?? name;
+					const version1Entries = (await doc.page(page.ref).pieceInfo.get(STAMP_PIECEINFO_APP))?.entries;
+					const name = (version1Entries && entryString(version1Entries, "Name")) ?? `Stamp${page.index + 1}`;
+					const label = (version1Entries && entryString(version1Entries, "Subject")) ?? options?.assetName?.(page.index) ?? name;
 					descriptors.push({
-						pageObjectNumber: page.pageObjectNumber,
+						page: page.ref,
 						index: page.index,
 						name,
 						label
 					});
 				}
-				for (const d of descriptors) await doc.pages.setName({
-					name: stampKey(d.name, d.label),
-					pageObjectNumber: d.pageObjectNumber
+				for (const descriptor of descriptors) await doc.pages.setName({
+					name: stampKey(descriptor.name, descriptor.label),
+					page: descriptor.page
 				});
 			}
 			await doc.pieceInfo.update(STAMP_LIBRARY_PIECEINFO_APP, stampLibraryPieceInfo(libraryId, {
@@ -276,25 +850,24 @@ function createStampCapability(ctx, config = {}) {
 				locale: libraryLocale
 			}));
 			const assets = [];
-			for (const d of descriptors) {
-				const handle = doc.page(d.pageObjectNumber);
-				if (!handle.pieceInfo) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need page pieceInfo support");
-				const entries = (await handle.pieceInfo.read("EMBD_Stamp"))?.entries ?? {};
-				const kind = opts?.kind ?? kindFromPdfName(entryName(entries, "Kind")) ?? "stamp";
+			for (const descriptor of descriptors) {
+				const handle = doc.page(descriptor.page);
+				const entries = (await handle.pieceInfo.get("EMBD_Stamp"))?.entries ?? {};
+				const kind = options?.kind ?? kindFromPdfName(entryName(entries, "Kind")) ?? "stamp";
 				const subject = entryString(entries, "SubjectOverride");
 				const categories = entryStringArray(entries, "Categories");
-				const page = byPon.get(d.pageObjectNumber);
+				const page = pagesByObjectNumber.get(descriptor.page.objectNumber);
 				const asset = {
-					id: assetIdFor(libraryId, d.name),
+					id: assetIdFor(libraryId, descriptor.name),
 					libraryId,
 					kind,
-					name: d.name,
-					label: d.label,
+					name: descriptor.name,
+					label: descriptor.label,
 					size: {
 						width: page.size.width,
 						height: page.size.height
 					},
-					pageObjectNumber: d.pageObjectNumber,
+					page: descriptor.page,
 					...subject !== void 0 ? { subject } : {},
 					...categories !== void 0 ? { categories } : {}
 				};
@@ -302,7 +875,7 @@ function createStampCapability(ctx, config = {}) {
 					subject,
 					categories
 				}));
-				const bytes = await doc.pages.extract([d.pageObjectNumber]);
+				const bytes = await doc.pages.extract([descriptor.page]);
 				assets.push({
 					asset,
 					bytes,
@@ -324,321 +897,71 @@ function createStampCapability(ctx, config = {}) {
 		} finally {
 			await doc.close();
 		}
+		throwIfCancelled(signal);
 		libraryBinaries.set(imported.library.id, imported.canonicalBytes);
-		ctx.dispatch({
-			type: "LIBRARY_ADDED",
-			library: imported.library
-		});
+		ctx.state.update(addLibrary, imported.library);
 		for (const { asset, bytes, preview } of imported.assets) {
-			binaries.set(asset.id, {
+			assetBinaries.set(asset.id, {
 				bytes,
 				preview
 			});
-			ctx.dispatch({
-				type: "ASSET_ADDED",
-				asset
-			});
+			ctx.state.update(addAsset, asset);
 		}
 		libraryChanged.emit({
 			libraryId: imported.library.id,
-			reason: "imported"
-		});
-		return imported.library.id;
-	};
-	/**
-	* A drawn or typed mark rendered to a one-page PDF: the annotation is
-	* authored on a scratch page and exported the way "stamp from selection"
-	* exports — a fresh page the size of the mark, paths kept as paths, the
-	* font subset-embedded. Self-contained and Acrobat-readable.
-	*/
-	const renderMark = async (mark) => {
-		const doc = await openAssetDocument(blankLibraryPdf());
-		try {
-			const scratch = (await doc.pages.list()).pages[0];
-			if (!scratch) throw new EngineError(EngineErrorCode.Unknown, "[stamp] no scratch page");
-			const page = doc.page(scratch.pageObjectNumber);
-			if (!page.annotations.exportAppearance) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] authoring a mark needs an asset engine that can export annotation appearances");
-			const color = hexColor(mark.color ?? "#1d2b53");
-			const created = mark.kind === "ink" ? await page.annotations.create({
-				subtype: "ink",
-				inkList: mark.strokes.map((stroke) => stroke.map(({ x, y }) => ({
-					x,
-					y
-				}))),
-				rect: inkBounds(mark.strokes, mark.strokeWidth ?? 2),
-				color,
-				strokeWidth: mark.strokeWidth ?? 2
-			}) : await page.annotations.create({
-				subtype: "free-text",
-				intent: "free-text",
-				contents: mark.text,
-				fontFamily: mark.fontFamily,
-				fontSize: mark.fontSize ?? 36,
-				textAlign: "left",
-				rect: textBounds(mark.text, mark.fontSize ?? 36),
-				fontColor: color,
-				strokeWidth: 0
-			});
-			return new Uint8Array(await page.annotations.exportAppearance([created.created.ref]));
-		} finally {
-			await doc.close();
-		}
-	};
-	/** One page of a PDF as a single-page PDF (a `pdf` mark with `pageIndex`). */
-	const extractPage = async (bytes, pageIndex) => {
-		const doc = await openAssetDocument(bytes);
-		try {
-			const layout = await doc.pages.list();
-			const page = layout.pages[pageIndex];
-			if (!page) throw new EngineError(EngineErrorCode.InvalidArg, `[stamp] the PDF has no page ${pageIndex} (${layout.pageCount} pages)`);
-			return await doc.pages.extract([page.pageObjectNumber]);
-		} finally {
-			await doc.close();
-		}
-	};
-	/** The bytes an asset is made from: the caller's `source`, or its `mark` authored into one. */
-	const resolveAssetSource = async (input) => {
-		if (input.source === void 0 === (input.mark === void 0)) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] addAsset takes exactly one of `source` / `mark`");
-		if (input.source !== void 0) return resolveBinarySource(input.source);
-		const mark = input.mark;
-		switch (mark.kind) {
-			case "image": return resolveBinarySource(mark.source);
-			case "pdf": {
-				const resolved = await resolveBinarySource(mark.source);
-				if (mark.pageIndex === void 0) return resolved;
-				return { bytes: toArrayBuffer(await extractPage(new Uint8Array(resolved.bytes), mark.pageIndex)) };
-			}
-			case "ink":
-			case "text": return { bytes: toArrayBuffer(await renderMark(mark)) };
-		}
-	};
-	const addAsset = async (input) => {
-		if (input.libraryId && !ctx.getState().libraries[input.libraryId]) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown library '${input.libraryId}'`);
-		const resolved = await resolveAssetSource(input);
-		const meta = sniffBinaryMetadata(resolved.bytes);
-		if (!meta) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] asset source must be PNG, JPEG, or single-page PDF bytes");
-		const isPdf = meta.mimeType === "application/pdf";
-		const name = input.name ?? customStampName();
-		const label = input.label ?? name;
-		if (name.length === 0 || name.includes("=")) throw new EngineError(EngineErrorCode.InvalidArg, `[stamp] invalid stamp identifier '${name}': must be non-empty and contain no '='`);
-		const rasterSize = input.size ?? ("width" in meta ? {
-			width: meta.width,
-			height: meta.height
-		} : null);
-		if (!isPdf && (!rasterSize || rasterSize.width <= 0 || rasterSize.height <= 0)) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] a raster asset needs a positive `size` (its page size in points)");
-		let suppliedPreview = null;
-		if (input.preview) {
-			const preview = await resolveBinarySource(input.preview);
-			suppliedPreview = {
-				bytes: new Uint8Array(preview.bytes),
-				mimeType: preview.mimeType ?? "image/png"
-			};
-		}
-		const libraryId = input.libraryId ?? await createLibrary(label);
-		return mutateLibrary(libraryId, async () => {
-			const liveLibrary = ctx.getState().libraries[libraryId];
-			if (!liveLibrary) throw new EngineError(EngineErrorCode.NotFound, `[stamp] library '${libraryId}' no longer exists`);
-			const assetId = assetIdFor(liveLibrary.id, name);
-			if (ctx.getState().assets[assetId]) throw new EngineError(EngineErrorCode.InvalidArg, `[stamp] library '${liveLibrary.name}' already has a stamp named '${name}'`);
-			const canonicalBytes = libraryBinaries.get(liveLibrary.id);
-			if (!canonicalBytes) throw new EngineError(EngineErrorCode.Unknown, `[stamp] canonical bytes are missing for library '${liveLibrary.id}'`);
-			const doc = await openAssetDocument(canonicalBytes);
-			let appended;
-			try {
-				requireCanonicalServices(doc);
-				let pageObjectNumber;
-				if (isPdf) {
-					const result = await doc.pages.insert(new Uint8Array(resolved.bytes));
-					if (result.insertedPageObjectNumbers.length !== 1) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] a library asset must be a single-page PDF");
-					pageObjectNumber = result.insertedPageObjectNumbers[0];
-				} else {
-					if (!doc.pages.flatten) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] raster assets need an asset engine with pages.flatten");
-					pageObjectNumber = (await doc.pages.insertBlank({ size: rasterSize })).insertedPageObjectNumbers[0];
-					await doc.page(pageObjectNumber).annotations.create({
-						subtype: "stamp",
-						rect: {
-							left: 0,
-							bottom: 0,
-							right: rasterSize.width,
-							top: rasterSize.height
-						},
-						source: new Uint8Array(resolved.bytes),
-						fit: "fill"
-					});
-					if ((await doc.pages.flatten([pageObjectNumber], "display")).results.some(({ status }) => status !== "applied")) throw new EngineError(EngineErrorCode.Unknown, "[stamp] flattening the raster into its page failed");
-				}
-				const layout = (await doc.pages.list()).pages.find((candidate) => candidate.pageObjectNumber === pageObjectNumber);
-				const page = doc.page(pageObjectNumber);
-				if (!layout || !page.pieceInfo) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need page layout and pieceInfo support");
-				await doc.pages.setName({
-					name: stampKey(name, label),
-					pageObjectNumber
-				});
-				const asset = {
-					id: assetId,
-					libraryId: liveLibrary.id,
-					kind: input.kind ?? "stamp",
-					name,
-					label,
-					size: {
-						width: layout.size.width,
-						height: layout.size.height
-					},
-					pageObjectNumber,
-					...input.subject !== void 0 ? { subject: input.subject } : {},
-					...input.categories !== void 0 ? { categories: input.categories } : {}
-				};
-				await page.pieceInfo.update(STAMP_PIECEINFO_APP, stampPieceInfo(asset.kind, {
-					subject: asset.subject,
-					categories: asset.categories
-				}));
-				appended = {
-					asset,
-					bytes: await doc.pages.extract([pageObjectNumber]),
-					preview: suppliedPreview ?? await renderThumbnail(page),
-					canonical: await doc.download()
-				};
-			} finally {
-				await doc.close();
-			}
-			libraryBinaries.set(liveLibrary.id, appended.canonical);
-			binaries.set(appended.asset.id, {
-				bytes: appended.bytes,
-				preview: appended.preview
-			});
-			ctx.dispatch({
-				type: "ASSET_ADDED",
-				asset: appended.asset
-			});
-			libraryChanged.emit({
-				libraryId: liveLibrary.id,
-				reason: "asset-added"
-			});
-			return appended.asset.id;
-		});
-	};
-	const addAssetFromAnnotations = async (documentId, pageObjectNumber, refs, input) => {
-		const doc = ctx.documentHandle(documentId);
-		if (!doc) throw new EngineError(EngineErrorCode.NotFound, `[stamp] target document '${documentId}' is not open`);
-		const page = doc.page(pageObjectNumber);
-		if (!page.annotations.exportAppearance) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] this document's engine cannot export annotation appearances");
-		const source = await page.annotations.exportAppearance(refs);
-		return addAsset({
-			...input,
-			source
-		});
-	};
-	const dropLibrary = (id) => {
-		const library = ctx.getState().libraries[id];
-		if (library) for (const assetId of library.assetIds) {
-			binaries.delete(assetId);
-			ghostRenders.delete(assetId);
-		}
-		libraryBinaries.delete(id);
-		ctx.dispatch({
-			type: "LIBRARY_REMOVED",
-			libraryId: id
-		});
-	};
-	const removeAsset = async (id) => {
-		const initialAsset = ctx.getState().assets[id];
-		if (!initialAsset) return;
-		return mutateLibrary(initialAsset.libraryId, async () => {
-			const asset = ctx.getState().assets[id];
-			if (!asset) return;
-			const library = ctx.getState().libraries[asset.libraryId];
-			if (!library) return;
-			const canonicalBytes = libraryBinaries.get(library.id);
-			if (!canonicalBytes) throw new EngineError(EngineErrorCode.Unknown, `[stamp] canonical bytes are missing for library '${library.id}'`);
-			const doc = await openAssetDocument(canonicalBytes);
-			let rewritten;
-			try {
-				await doc.pages.delete([asset.pageObjectNumber]);
-				rewritten = await doc.download();
-			} finally {
-				await doc.close();
-			}
-			libraryBinaries.set(library.id, rewritten);
-			binaries.delete(id);
-			ghostRenders.delete(id);
-			ctx.dispatch({
-				type: "ASSET_REMOVED",
-				assetId: id
-			});
-			libraryChanged.emit({
-				libraryId: library.id,
-				reason: "asset-removed"
-			});
+			reason: "imported"
+		});
+		libraryCreated.emit({
+			libraryId: imported.library.id,
+			library: imported.library
 		});
+		for (const { asset } of imported.assets) assetCreated.emit({
+			assetId: asset.id,
+			libraryId: imported.library.id,
+			asset
+		});
+		return { library: ctx.state.get().libraries[imported.library.id] ?? imported.library };
+	};
+	const dropLibrary = (id) => {
+		const library = ctx.state.get().libraries[id];
+		if (library) for (const assetId of library.assetIds) {
+			assetBinaries.delete(assetId);
+			ghostRenders.delete(assetId);
+		}
+		libraryBinaries.delete(id);
+		ctx.state.update(removeLibrary, id);
 	};
-	const removeLibrary = (id) => mutateLibrary(id, async () => {
-		const existed = ctx.getState().libraries[id] !== void 0;
+	const deleteLibrary = (id, options) => mutateLibrary(id, async () => {
+		const existed = ctx.state.get().libraries[id] !== void 0;
 		dropLibrary(id);
-		if (existed) libraryChanged.emit({
-			libraryId: id,
-			reason: "removed"
-		});
-	});
-	const updateAsset = async (id, patch) => {
-		const initial = ctx.getState().assets[id];
-		if (!initial) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown asset '${id}'`);
-		return mutateLibrary(initial.libraryId, async () => {
-			const asset = ctx.getState().assets[id];
-			const library = asset ? ctx.getState().libraries[asset.libraryId] : void 0;
-			if (!asset || !library) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown asset '${id}'`);
-			const next = {
-				...asset,
-				...patch.label !== void 0 ? { label: patch.label } : {},
-				...patch.categories !== void 0 ? { categories: patch.categories } : {}
-			};
-			if (patch.subject === null) delete next.subject;
-			else if (patch.subject !== void 0) next.subject = patch.subject;
-			const canonicalBytes = libraryBinaries.get(library.id);
-			if (!canonicalBytes) throw new EngineError(EngineErrorCode.Unknown, `[stamp] canonical bytes are missing for library '${library.id}'`);
-			const doc = await openAssetDocument(canonicalBytes);
-			let rewritten;
-			try {
-				requireCanonicalServices(doc);
-				if (next.label !== asset.label) await doc.pages.setName({
-					name: stampKey(asset.name, next.label),
-					pageObjectNumber: asset.pageObjectNumber,
-					replace: stampKey(asset.name, asset.label)
-				});
-				await doc.page(asset.pageObjectNumber).pieceInfo?.update(STAMP_PIECEINFO_APP, stampPieceInfo(next.kind, {
-					subject: next.subject,
-					categories: next.categories
-				}));
-				rewritten = await doc.download();
-			} finally {
-				await doc.close();
-			}
-			libraryBinaries.set(library.id, rewritten);
-			ctx.dispatch({
-				type: "ASSET_UPDATED",
-				asset: next
-			});
+		if (existed) {
 			libraryChanged.emit({
-				libraryId: library.id,
-				reason: "asset-updated"
+				libraryId: id,
+				reason: "removed"
 			});
-		});
-	};
-	const updateLibrary = async (id, patch) => {
-		if (!ctx.getState().libraries[id]) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown library '${id}'`);
+			libraryDeleted.emit({
+				libraryId: id,
+				library: null
+			});
+		}
+	}, options?.signal);
+	const updateLibrary = async (id, patch, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		if (!ctx.state.get().libraries[id]) throw notFound("library", id);
 		return mutateLibrary(id, async () => {
-			const library = ctx.getState().libraries[id];
-			if (!library) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown library '${id}'`);
+			const library = ctx.state.get().libraries[id];
+			if (!library) throw notFound("library", id);
 			const canonicalBytes = libraryBinaries.get(id);
-			if (!canonicalBytes) throw new EngineError(EngineErrorCode.Unknown, `[stamp] canonical bytes are missing for library '${id}'`);
+			if (!canonicalBytes) throw stampError("operation-failed", `canonical bytes are missing for library '${id}'`);
 			const next = {
 				...library,
 				...patch.name !== void 0 ? { name: patch.name } : {},
 				...patch.categories !== void 0 ? { categories: patch.categories } : {}
 			};
-			const doc = await openAssetDocument(canonicalBytes);
+			const doc = await ctx.cancellable(signal, openAssetDocument(canonicalBytes));
 			let rewritten;
 			try {
-				requireCanonicalServices(doc);
 				if (next.name !== library.name) await doc.metadata.update({ title: next.name });
 				await doc.pieceInfo.update(STAMP_LIBRARY_PIECEINFO_APP, stampLibraryPieceInfo(id, {
 					kind: next.kind,
@@ -649,72 +972,229 @@ function createStampCapability(ctx, config = {}) {
 			} finally {
 				await doc.close();
 			}
+			throwIfCancelled(signal);
 			libraryBinaries.set(id, rewritten);
-			ctx.dispatch({
-				type: "LIBRARY_UPDATED",
-				library: next
-			});
+			ctx.state.update(setLibrary, next);
 			libraryChanged.emit({
 				libraryId: id,
 				reason: "updated"
 			});
-		});
+			libraryUpdated.emit({
+				libraryId: id,
+				library: next
+			});
+			return { library: next };
+		}, signal);
+	};
+	return {
+		createLibrary,
+		api: {
+			createLibrary: verb(createLibrary),
+			updateLibrary: verb(updateLibrary),
+			importLibrary: verb(importLibrary),
+			deleteLibrary: verb(deleteLibrary)
+		}
+	};
+}
+//#endregion
+//#region src/write/marks.ts
+/**
+* Authoring: a drawn or typed mark rendered to a one-page PDF (the
+* annotation is authored on a scratch page and exported the way "stamp from
+* selection" exports), a page of a PDF as a single-page PDF, and the bytes
+* an asset is made from.
+*/
+/** A mark's `#rrggbb` color, checked before anything is drawn. */
+const hexColor = (hex) => {
+	const color = hex.trim();
+	if (!/^#[0-9a-f]{6}$/i.test(color)) throw stampError("invalid-input", `mark color must be #rrggbb, got '${hex}'`);
+	return color;
+};
+/** An exact ArrayBuffer over a view (the engine's binary idiom). */
+const toArrayBuffer = (bytes) => {
+	const buffer = new ArrayBuffer(bytes.byteLength);
+	new Uint8Array(buffer).set(bytes);
+	return buffer;
+};
+/** An ink mark's strokes, as the engine takes them; a mark needs at least one point. */
+const inkListOf = (strokes) => {
+	if (!strokes.some((stroke) => stroke.length > 0)) throw stampError("invalid-input", "an ink mark needs at least one point");
+	return strokes.map((stroke) => stroke.map(({ x, y }) => ({
+		x,
+		y
+	})));
+};
+/**
+* A generous box for typed text. The export keeps the whole box, so the
+* text is centered in it: the mark then sits in the middle of a preview
+* or a signature field.
+*/
+const textBounds = (text, fontSize) => ({
+	x: 0,
+	y: 0,
+	width: Math.max(1, text.length) * fontSize * .75 + fontSize,
+	height: fontSize * 1.6
+});
+function createMarks({ assetEngine }) {
+	const { openAssetDocument } = assetEngine;
+	/**
+	* A drawn or typed mark rendered to a one-page PDF: the annotation is
+	* authored on a scratch page and exported the way "stamp from selection"
+	* exports — a fresh page the size of the mark, paths kept as paths, the
+	* font subset-embedded. Self-contained and Acrobat-readable.
+	*/
+	const renderMark = async (mark) => {
+		const doc = await openAssetDocument(blankLibraryPdf());
+		try {
+			const scratch = (await doc.pages.list()).pages[0];
+			if (!scratch) throw stampError("operation-failed", "the scratch document has no page");
+			const page = doc.page(scratch.ref);
+			const color = hexColor(mark.color ?? "#1d2b53");
+			const created = mark.kind === "ink" ? await page.annotations.create({
+				subtype: "ink",
+				inkList: inkListOf(mark.strokes),
+				color,
+				strokeWidth: mark.strokeWidth ?? 2
+			}) : await page.annotations.create({
+				subtype: "free-text",
+				intent: "free-text",
+				contents: mark.text,
+				fontFamily: mark.fontFamily,
+				fontSize: mark.fontSize ?? 36,
+				textAlign: "center",
+				verticalAlign: "middle",
+				box: textBounds(mark.text, mark.fontSize ?? 36),
+				fontColor: color,
+				strokeWidth: 0
+			});
+			return new Uint8Array(await page.annotations.exportAppearance([created.annotation.ref]));
+		} finally {
+			await doc.close();
+		}
+	};
+	/** One page of a PDF as a single-page PDF (a `pdf` mark with `pageIndex`). */
+	const extractPage = async (bytes, pageIndex) => {
+		const doc = await openAssetDocument(bytes);
+		try {
+			const layout = await doc.pages.list();
+			const page = layout.pages[pageIndex];
+			if (!page) throw stampError("invalid-input", `the PDF has no page ${pageIndex} (${layout.pageCount} pages)`);
+			return await doc.pages.extract([page.ref]);
+		} finally {
+			await doc.close();
+		}
+	};
+	/** The bytes an asset is made from: the caller's `source`, or its `mark` authored into one. */
+	const resolveAssetSource = async (input) => {
+		if (input.source === void 0 === (input.mark === void 0)) throw stampError("invalid-input", "createAsset takes exactly one of `source` / `mark`");
+		if (input.source !== void 0) return resolveBinarySource(input.source);
+		const mark = input.mark;
+		switch (mark.kind) {
+			case "image": return resolveBinarySource(mark.source);
+			case "pdf": {
+				const resolved = await resolveBinarySource(mark.source);
+				if (mark.pageIndex === void 0) return resolved;
+				return { bytes: toArrayBuffer(await extractPage(new Uint8Array(resolved.bytes), mark.pageIndex)) };
+			}
+			case "ink":
+			case "text": return { bytes: toArrayBuffer(await renderMark(mark)) };
+		}
 	};
+	return { resolveAssetSource };
+}
+//#endregion
+//#region src/write/placement.ts
+/**
+* Placement: arm an asset on a document (the next click places) or place it
+* without the pointer. Form-backed stamps are executable templates only
+* until placement — they are evaluated on an isolated copy under the target
+* document's detached script realm, so neither the canonical library nor
+* its reusable per-page extraction becomes target/user/time specific.
+*/
+function createPlacement(ctx, { binaries, assetEngine, ghosts, targets }, { canPlace }) {
+	const { binaries: assetBinaries, libraryBinaries } = binaries;
+	const { openAssetDocument, imageToPreview } = assetEngine;
+	const { ghostProvider } = ghosts;
+	const { documentIdOf, targetOf, pageOf } = targets;
+	const settings = ctx.settings();
+	const droppedArms = () => Object.keys(ctx.state.get().armed).filter((documentId) => !ctx.tryForDocument(AnnotationToken$1, documentId)?.stamps.isArmed()).join("\n");
+	ctx.watch(droppedArms, (dropped) => {
+		if (dropped) ctx.state.update(disarmDocuments, dropped.split("\n"));
+	});
+	/** The one payload both entry points hand the annotation plugin: artwork,
+	*  a resolution-aware ghost, true size, and the identity a placement
+	*  writes (`/Name` = identifier, `/Subj` = the subject override or label). */
+	const stampPayload = (asset, placement, materialized) => ({
+		source: placement.bytes,
+		preview: ghostProvider(placement.bytes, placement.preview, materialized ? null : asset.id),
+		intrinsicSize: asset.size,
+		name: asset.name,
+		subject: asset.subject ?? asset.label
+	});
 	/**
 	* Form-backed stamps are executable templates only until placement. Work
 	* on an isolated copy so neither the canonical library nor its reusable
 	* per-page extraction becomes target/user/time specific.
 	*
-	* The realm comes from the TARGET document's actions plugin — a detached
-	* realm under that document's policy and environment (WP4: its own
-	* sandbox, none of the viewer realm's globals). No actions plugin, or
-	* scripting off, or `dynamic: false` → the template is armed as-is.
+	* The realm comes from the target document's actions plugin: a detached
+	* realm under that document's policy and environment, with its own
+	* sandbox and none of the viewer realm's globals. No actions plugin,
+	* scripting off, or `dynamic: false`: the template is armed as-is.
 	*/
-	const materializeForPlacement = async (documentId, asset, bin) => {
-		if (config.dynamic === false) return bin;
-		const actions = ctx.tryForDocument(ActionsToken, documentId);
+	const materializeForPlacement = async (documentId, asset, binary) => {
+		if (!settings.get().dynamic) return binary;
+		const actions = ctx.tryForDocument(ActionsToken$1, documentId);
 		const mintRealm = actions?.createDetachedScriptRealm;
-		if (!actions || !mintRealm) return bin;
-		const targetMeta = ctx.core().documents[documentId] ?? null;
-		if (!targetMeta) throw new EngineError(EngineErrorCode.NotFound, `[stamp] target document '${documentId}' is not open`);
+		if (!actions || !mintRealm) return binary;
+		const documents = ctx.get(DocumentsToken);
+		const target = documents.get(documentId);
+		if (target?.status !== "ready") throw stampError("not-found", `document '${documentId}' is not open`);
+		const targetDocument = {
+			name: target.name,
+			pageCount: target.pageCount,
+			pages: documents.listPages(documentId)
+		};
 		const canonicalBytes = libraryBinaries.get(asset.libraryId);
-		const sourceBytes = canonicalBytes ?? bin.bytes;
+		const sourceBytes = canonicalBytes ?? binary.bytes;
 		const doc = await openAssetDocument(new Uint8Array(sourceBytes));
 		let realm = null;
 		let scripting = null;
 		try {
 			const layout = await doc.pages.list();
-			const selectedPage = asset.pageObjectNumber === void 0 ? layout.pageCount === 1 ? layout.pages[0] : void 0 : layout.pages.find(({ pageObjectNumber }) => pageObjectNumber === asset.pageObjectNumber);
-			if (!selectedPage) throw new EngineError(EngineErrorCode.InvalidArg, canonicalBytes ? `[stamp] canonical page ${asset.pageObjectNumber ?? "unknown"} no longer exists` : "[stamp] a loose dynamic stamp asset must contain exactly one page");
-			if (!(await doc.forms.list()).fields.some((field) => field.widgets.some(({ pageObjectNumber }) => pageObjectNumber === selectedPage.pageObjectNumber))) return bin;
-			if (!doc.pages.flatten || !doc.pages.extract) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] dynamic PDF stamps need an asset engine with pages.flatten and pages.extract");
+			const selectedPage = asset.page === void 0 ? layout.pageCount === 1 ? layout.pages[0] : void 0 : layout.pages.find(({ ref }) => ref.objectNumber === asset.page.objectNumber);
+			if (!selectedPage) throw stampError("invalid-input", canonicalBytes ? `canonical page ${asset.page?.objectNumber ?? "unknown"} no longer exists` : "a loose dynamic stamp asset must contain exactly one page");
+			const snapshot = await doc.forms.list();
+			if (!snapshot.fields.some((field) => field.widgets.some(({ page }) => page?.objectNumber === selectedPage.ref.objectNumber))) return binary;
+			if (!doc.pages.flatten || !doc.pages.extract) throw stampError("unsupported", "dynamic PDF stamps need an asset engine with pages.flatten and pages.extract");
 			realm = mintRealm.call(actions, {
 				doc,
-				document: () => targetMeta,
+				document: () => targetDocument,
 				bootSources: async () => {
-					return (doc.actions ? await doc.actions.read() : null)?.nameTreeScripts.map(({ action }) => javaScriptProgramFromActionTree(action)) ?? [];
+					return (doc.actions ? await doc.actions.get() : null)?.nameTreeScripts.map(({ action }) => javaScriptProgramFromActionTree(action)) ?? [];
 				}
 			});
 			scripting = createFormScriptingController({
-				doc,
-				document: () => targetMeta,
+				document: () => targetDocument,
 				transaction: realm.transaction.bind(realm),
 				budget: realm.budget
 			});
-			const result = await scripting.recalculate();
+			const result = await scripting.transaction(async (scripts) => {
+				const calculated = await scripts.recalculate(snapshot);
+				if (calculated.status === "accepted" && calculated.effects.length > 0) await doc.apply({ ops: formEffectOps(calculated.effects) });
+				return calculated;
+			});
 			actions.surfaceScriptCommit(result, {
 				origin: "user",
 				realm: "detached"
 			});
-			if (result.status === "failed") throw new EngineError(EngineErrorCode.Unknown, `[stamp] dynamic stamp scripting failed: ${result.error?.message ?? "native form effect failed"}`);
-			const pageObjectNumber = selectedPage.pageObjectNumber;
-			const failed = (await doc.pages.flatten([pageObjectNumber], "display")).results.find(({ status }) => status === "failed" || status === "skipped");
-			if (failed) throw new EngineError(EngineErrorCode.Unknown, `[stamp] dynamic stamp flatten failed for page ${failed.pageObjectNumber}`);
-			const bytes = await doc.pages.extract([pageObjectNumber]);
-			const image = await doc.page(pageObjectNumber).render.image({
+			if (result.status === "failed") throw stampError("operation-failed", `dynamic stamp scripting failed: ${result.error?.message ?? "native form effect failed"}`);
+			const page = selectedPage.ref;
+			await doc.pages.flatten([page], { usage: "display" });
+			const bytes = await doc.pages.extract([page]);
+			const image = await doc.page(page).render.image({
 				viewport: {
 					kind: "width",
-					width: config.previewWidth ?? DEFAULT_PREVIEW_WIDTH
+					width: settings.get().previewWidth
 				},
 				background: "transparent",
 				includeAnnotations: false,
@@ -730,242 +1210,199 @@ function createStampCapability(ctx, config = {}) {
 			await doc.close();
 		}
 	};
-	const armAsset = async (documentId, assetId, opts) => {
-		const asset = ctx.getState().assets[assetId];
-		const bin = binaries.get(assetId);
-		if (!asset || !bin) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown asset '${assetId}'`);
-		const placement = await materializeForPlacement(documentId, asset, bin);
-		await ctx.forDocument(AnnotationToken, documentId).armStamp({
-			...stampPayload(asset, placement, placement !== bin),
-			targetWidth: opts?.targetWidth
-		});
-		armedByDocument.set(documentId, assetId);
+	/** An asset and its bytes, or `not-found`. */
+	const assetOf = (assetId) => {
+		const asset = ctx.state.get().assets[assetId];
+		const binary = assetBinaries.get(assetId);
+		if (!asset || !binary) throw notFound("asset", assetId);
+		return {
+			asset,
+			binary
+		};
 	};
-	/** Which asset this plugin armed per document. The annotation plugin owns
-	*  the arm itself (a tool switch disarms it), so the answer is checked
-	*  against it and forgotten once it no longer holds one. */
-	const armedByDocument = /* @__PURE__ */ new Map();
-	const armedAsset = (documentId) => {
-		const assetId = armedByDocument.get(documentId);
-		if (assetId === void 0) return null;
-		if (!ctx.tryForDocument(AnnotationToken$1, documentId)?.hasArmedStamp()) {
-			armedByDocument.delete(documentId);
-			return null;
-		}
-		return ctx.getState().assets[assetId] ?? null;
+	/** Placing is annotation work: refused where the document's annotation plugin refuses a create. */
+	const assertMayPlace = (documentId, operation) => {
+		if (!canPlace(documentId)) throw permissionDenied("annotations:create", operation);
 	};
-	/**
-	* Ghost renders, one per size bucket per asset, rendered lazily on the
-	* asset engine the first time the ghost is shown at that size and kept
-	* until the asset goes away. Materialized (dynamic) placements are
-	* user/time specific and cache only for their own arm (`cacheKey` null).
-	*/
-	const ghostRenders = /* @__PURE__ */ new Map();
-	const renderGhost = async (bytes, devicePixelWidth) => {
-		const doc = await openAssetDocument(new Uint8Array(bytes));
-		try {
-			const page = (await doc.pages.list()).pages[0];
-			if (!page) return null;
-			return imageToPreview(await doc.page(page.pageObjectNumber).render.image({
-				viewport: {
-					kind: "width",
-					width: devicePixelWidth
-				},
-				background: "transparent",
-				includeAnnotations: true,
-				format: "png"
-			}));
-		} finally {
-			await doc.close();
-		}
+	const armAsset$1 = async (assetId, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const documentId = targetOf(options);
+		const { asset, binary } = assetOf(assetId);
+		assertMayPlace(documentId, "stamp.armAsset");
+		const placement = await ctx.cancellable(signal, materializeForPlacement(documentId, asset, binary));
+		throwIfCancelled(signal);
+		await ctx.forDocument(AnnotationToken, documentId).stamps.arm({
+			...stampPayload(asset, placement, placement !== binary),
+			targetWidth: options?.targetWidth
+		}, { signal });
+		ctx.state.update(armAsset, documentId, assetId);
 	};
-	/** A resolution-aware ghost source for placement bytes: the page renders
-	*  at the requested width, cached per bucket under `cacheKey` when given. */
-	const ghostProvider = (bytes, fallback, cacheKey) => {
-		const local = cacheKey ? ghostRenders.get(cacheKey) ?? /* @__PURE__ */ new Map() : /* @__PURE__ */ new Map();
-		if (cacheKey) ghostRenders.set(cacheKey, local);
-		return (devicePixelWidth) => {
-			let pending = local.get(devicePixelWidth);
-			if (!pending) {
-				pending = renderGhost(bytes, devicePixelWidth).catch((error) => {
-					globalThis.console?.warn("[stamp] ghost render failed, using the thumbnail:", error);
-					return fallback;
-				});
-				local.set(devicePixelWidth, pending);
-			}
-			return pending;
-		};
+	const getArmedAsset = (documentId) => {
+		const id = documentIdOf(documentId);
+		const assetId = id === null ? void 0 : ctx.state.get().armed[id];
+		if (id === null || assetId === void 0) return null;
+		if (!ctx.tryForDocument(AnnotationToken$1, id)?.stamps.isArmed()) return null;
+		return ctx.state.get().assets[assetId] ?? null;
 	};
-	/** The one payload both entry points hand the annotation plugin: artwork,
-	*  a resolution-aware ghost, true size, and the identity a placement
-	*  writes (`/Name` = identifier, `/Subj` = the subject override or label). */
-	const stampPayload = (asset, placement, materialized) => ({
-		source: placement.bytes,
-		preview: ghostProvider(placement.bytes, placement.preview, materialized ? null : asset.id),
-		intrinsicSize: asset.size,
-		name: asset.name,
-		subject: asset.subject ?? asset.label
-	});
-	const placeAsset = async (documentId, assetId, placement) => {
-		const asset = ctx.getState().assets[assetId];
-		const bin = binaries.get(assetId);
-		if (!asset || !bin) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown asset '${assetId}'`);
-		const materialized = await materializeForPlacement(documentId, asset, bin);
-		return ctx.forDocument(AnnotationToken, documentId).placeStamp(stampPayload(asset, materialized, materialized !== bin), placement);
+	const disarm = (documentId) => {
+		const id = documentIdOf(documentId);
+		if (id === null) return;
+		ctx.tryForDocument(AnnotationToken, id)?.stamps.disarm();
+		ctx.state.update(disarmDocuments, [id]);
 	};
-	ctx.cleanup(() => {
-		binaries.clear();
-		ghostRenders.clear();
-		libraryBinaries.clear();
-		libraryMutationTails.clear();
-		const ownedAssetEngine = typeof config.assetEngine === "function" ? assetEngineRef : null;
-		assetEngineRef = null;
-		if (ownedAssetEngine) Promise.resolve(ownedAssetEngine).then((engine) => engine.destroy()).catch(() => {});
-	});
-	return {
-		libraries: (query) => {
-			const s = ctx.getState();
-			const kinds = query?.kind === void 0 ? null : new Set(typeof query.kind === "string" ? [query.kind] : query.kind);
-			return s.libraryOrder.map((id) => s.libraries[id]).filter((l) => l != null && (kinds === null || kinds.has(l.kind)));
-		},
-		library: (id) => ctx.getState().libraries[id] ?? null,
-		assets: (libraryId) => {
-			const s = ctx.getState();
-			if (libraryId) {
-				const library = s.libraries[libraryId];
-				return library ? library.assetIds.map((id) => s.assets[id]).filter((a) => a != null) : [];
-			}
-			return s.libraryOrder.flatMap((lid) => (s.libraries[lid]?.assetIds ?? []).map((id) => s.assets[id]).filter((a) => a != null));
-		},
-		asset: (id) => ctx.getState().assets[id] ?? null,
-		assetPreview: (id) => binaries.get(id)?.preview ?? null,
-		assetBytes: (id) => binaries.get(id)?.bytes ?? null,
-		exportLibrary: (id) => libraryBinaries.get(id) ?? null,
-		onLibraryChanged: libraryChanged.on,
-		createLibrary,
-		updateLibrary,
-		importLibraryPdf,
-		addAsset,
-		addAssetFromAnnotations,
-		updateAsset,
-		removeAsset,
-		removeLibrary,
-		armAsset,
-		placeAsset,
-		disarm: (documentId) => {
-			armedByDocument.delete(documentId);
-			ctx.forDocument(AnnotationToken, documentId).disarmStamp();
-		},
-		armedAsset
+	/** Place on one document, its permission already checked. */
+	const placeOn = async (documentId, assetId, placement, signal) => {
+		const { asset, binary } = assetOf(assetId);
+		const materialized = await ctx.cancellable(signal, materializeForPlacement(documentId, asset, binary));
+		throwIfCancelled(signal);
+		return ctx.forDocument(AnnotationToken, documentId).stamps.place(stampPayload(asset, materialized, materialized !== binary), placement, { signal });
+	};
+	const placeAsset = async (assetId, placement, options) => {
+		throwIfCancelled(options?.signal);
+		const documentId = targetOf(options);
+		assetOf(assetId);
+		assertMayPlace(documentId, "stamp.placeAsset");
+		return placeOn(documentId, assetId, placement, options?.signal);
 	};
+	const placeAssetOnPages = async (assetId, pages, placement, options) => {
+		const signal = options?.signal;
+		throwIfCancelled(signal);
+		const documentId = targetOf(options);
+		assetOf(assetId);
+		assertMayPlace(documentId, "stamp.placeAssetOnPages");
+		const targetPages = pages === "all" ? ctx.get(DocumentsToken).listPages(documentId).map((page) => page.ref) : pages.map((page) => pageOf(documentId, page).ref);
+		const applied = [];
+		const failed = [];
+		for (const page of targetPages) try {
+			const placed = await placeOn(documentId, assetId, {
+				...placement,
+				page
+			}, signal);
+			applied.push(placed.annotation);
+		} catch (error) {
+			const refused = toPluginError("stamp", error);
+			if (refused.code === "operation-cancelled") throw refused;
+			failed.push({
+				ref: page,
+				error: toPluginErrorInfo(refused)
+			});
+		}
+		return {
+			applied,
+			skipped: [],
+			failed
+		};
+	};
+	return { api: {
+		armAsset: verb(armAsset$1),
+		disarm,
+		getArmedAsset,
+		placeAsset: verb(placeAsset),
+		placeAssetOnPages: verb(placeAssetOnPages)
+	} };
 }
 //#endregion
-//#region src/reducer.ts
-const initialStampState = () => ({
-	libraries: {},
-	libraryOrder: [],
-	assets: {}
-});
-/** Pure and serializable (kernel rule 1) — descriptors only; the bytes and
-*  previews live in the capability and never enter the store. */
-const stampReducer = (state, action) => {
-	switch (action.type) {
-		case "LIBRARY_ADDED": return {
-			...state,
-			libraries: {
-				...state.libraries,
-				[action.library.id]: action.library
-			},
-			libraryOrder: [...state.libraryOrder, action.library.id]
-		};
-		case "LIBRARY_UPDATED": return state.libraries[action.library.id] ? {
-			...state,
-			libraries: {
-				...state.libraries,
-				[action.library.id]: action.library
-			}
-		} : state;
-		case "LIBRARY_REMOVED": {
-			const library = state.libraries[action.libraryId];
-			if (!library) return state;
-			const libraries = { ...state.libraries };
-			delete libraries[action.libraryId];
-			const assets = { ...state.assets };
-			for (const id of library.assetIds) delete assets[id];
-			return {
-				...state,
-				libraries,
-				libraryOrder: state.libraryOrder.filter((id) => id !== action.libraryId),
-				assets
-			};
-		}
-		case "ASSET_ADDED": {
-			const library = state.libraries[action.asset.libraryId];
-			if (!library) return state;
-			return {
-				...state,
-				assets: {
-					...state.assets,
-					[action.asset.id]: action.asset
-				},
-				libraries: {
-					...state.libraries,
-					[library.id]: {
-						...library,
-						assetIds: [...library.assetIds, action.asset.id]
-					}
-				}
-			};
+//#region src/controller.ts
+/**
+* The stamp controller: the composition root. It builds the plugin's
+* services once, wires each area with the services it declares, and
+* assembles the capability from the areas' API slices. Every verb and read
+* has a home in `read/` or `write/`; the one state-change event is derived
+* here.
+*/
+function createStampController(ctx) {
+	const services = createServices(ctx);
+	const { events } = services;
+	const settings = ctx.settings();
+	ctx.state.onChange(({ previous, next }) => {
+		if (previous.armed === next.armed) return;
+		const documentIds = /* @__PURE__ */ new Set([...Object.keys(previous.armed), ...Object.keys(next.armed)]);
+		for (const documentId of documentIds) {
+			const assetId = next.armed[documentId];
+			if (previous.armed[documentId] === assetId) continue;
+			events.armChanged.emit({
+				documentId,
+				asset: assetId === void 0 ? null : next.assets[assetId] ?? null
+			});
 		}
-		case "ASSET_UPDATED": return state.assets[action.asset.id] ? {
-			...state,
-			assets: {
-				...state.assets,
-				[action.asset.id]: action.asset
-			}
-		} : state;
-		case "ASSET_REMOVED": {
-			const asset = state.assets[action.assetId];
-			if (!asset) return state;
-			const assets = { ...state.assets };
-			delete assets[action.assetId];
-			const library = state.libraries[asset.libraryId];
-			return {
-				...state,
-				assets,
-				libraries: library ? {
-					...state.libraries,
-					[library.id]: {
-						...library,
-						assetIds: library.assetIds.filter((id) => id !== action.assetId)
-					}
-				} : state.libraries
-			};
+	});
+	const catalog = createCatalog(ctx, services);
+	const marks = createMarks(services);
+	const libraries = createLibraryWrites(ctx, services);
+	const assets = createAssetWrites(ctx, services, marks, libraries, catalog);
+	const placement = createPlacement(ctx, services, catalog);
+	return { api: composeApi("stamp", [
+		settings.api,
+		catalog.api,
+		libraries.api,
+		assets.api,
+		placement.api,
+		{
+			onLibraryChanged: events.libraryChanged.on,
+			onLibraryCreated: events.libraryCreated.on,
+			onLibraryUpdated: events.libraryUpdated.on,
+			onLibraryDeleted: events.libraryDeleted.on,
+			onAssetCreated: events.assetCreated.on,
+			onAssetUpdated: events.assetUpdated.on,
+			onAssetDeleted: events.assetDeleted.on,
+			onArmChanged: events.armChanged.on
 		}
-		default: return state;
-	}
-};
+	]) };
+}
 //#endregion
 //#region src/stamp.plugin.ts
 /**
-* The stamp plugin. WORKSPACE-scoped: libraries are shared across every open
-* document; placement names its document explicitly (`armAsset(documentId, …)`)
-* and delegates to that document's annotation plugin — no hard `requires`,
-* because the annotation token is document-scoped and resolved lazily per
-* placement (a viewer without the annotation plugin fails at the arm call,
-* with the kernel's own missing-capability error).
+* Stamp libraries and assets. Workspace-scoped: libraries outlive any one
+* document; placement targets a document through its annotation plugin.
+* `config` is the settings the app registers, over {@link STAMP_DEFAULTS}.
 */
-const stampPlugin = (config = {}) => definePlugin({
+const stampPlugin = (config) => definePlugin({
 	id: "stamp",
 	token: StampToken,
 	scope: "workspace",
-	initialState: initialStampState,
-	reduce: stampReducer,
-	capability: (ctx) => createStampCapability(ctx, config)
+	optional: [AnnotationToken, ActionsToken],
+	state: initialStampState,
+	settings: {
+		defaults: STAMP_DEFAULTS,
+		registered: config,
+		whole: ["assetEngine"]
+	},
+	create: createStampController,
+	inScope: (stamp, documentId) => {
+		const scoped = (options) => ({
+			...options,
+			documentId: options?.documentId ?? documentId
+		});
+		return {
+			...stamp,
+			createAssetFromAnnotations: (page, refs, input, options) => stamp.createAssetFromAnnotations(page, refs, input, scoped(options)),
+			armAsset: (assetId, options) => stamp.armAsset(assetId, scoped(options)),
+			disarm: (target = documentId) => stamp.disarm(target),
+			getArmedAsset: (target = documentId) => stamp.getArmedAsset(target),
+			placeAsset: (assetId, placement, options) => stamp.placeAsset(assetId, placement, scoped(options)),
+			placeAssetOnPages: (assetId, pages, placement, options) => stamp.placeAssetOnPages(assetId, pages, placement, scoped(options)),
+			canPlace: (target = documentId) => stamp.canPlace(target),
+			canCreateFromAnnotations: (target = documentId) => stamp.canCreateFromAnnotations(target)
+		};
+	}
+});
+//#endregion
+//#region src/state.ts
+/**
+* The stamps page's State table as code: what `useStampState()` returns, and
+* the same fields in every other framework. It reads the document in scope,
+* else the active one. The libraries and their stamps are not here:
+* `useStampLibraries()` and `useStampAssets()` read them, so a component that
+* only shows the armed stamp doesn't re-render when a library changes.
+*/
+const stampState = defineState(StampToken, {
+	read: (stamp) => ({ armedAsset: stamp.getArmedAsset() }),
+	empty: { armedAsset: null }
 });
 //#endregion
 //#region src/persistence.ts
-/** An in-memory store — tests and SSR. */
+/** An in-memory store, for tests and SSR. */
 function memoryStampStore() {
 	const rows = /* @__PURE__ */ new Map();
 	return {
@@ -983,58 +1420,66 @@ function memoryStampStore() {
 }
 /**
 * Bring every stored library back: each PDF is imported as-is (its title,
-* registry, and PieceInfo id come from the file — the store's key is only a
+* registry, and PieceInfo id come from the file; the store's key is only a
 * hint). Call once at boot, before seeding defaults, so "already has
 * libraries" means the user's own.
 */
 async function restoreStampLibraries(stamp, store) {
 	const restored = [];
 	for (const { id, bytes } of await store.list()) try {
-		restored.push(await stamp.importLibraryPdf(bytes));
+		restored.push((await stamp.importLibrary(bytes)).library.id);
 	} catch (error) {
 		globalThis.console?.warn(`[stamp] stored library '${id}' could not be restored:`, error);
 	}
 	return restored;
 }
 /**
-* Keep the store in sync from now on: every canonical change writes the
-* library's PDF (coalesced per library so a burst of edits saves once),
-* a removal deletes it. `except` names libraries never to persist — the
-* bundled default set, typically. Returns the unsubscribe.
+* Keep the store in sync from now on: every canonical change saves the
+* library's PDF, a removal deletes it. `except` names libraries never to
+* persist (the bundled default set, typically). Returns the unsubscribe;
+* work already asked for still finishes.
+*
+* Each library has one line of store work, so saves never overlap and a
+* delete never lands under a late save. The changes of one burst (one call
+* into the plugin) are one save; the changes made while a save runs are one
+* more after it.
 */
-function persistStampLibraries(stamp, store, opts = {}) {
-	const except = new Set(opts.except ?? []);
-	const timers = /* @__PURE__ */ new Map();
-	const write = (libraryId) => {
-		timers.delete(libraryId);
-		const bytes = stamp.exportLibrary(libraryId);
-		if (!bytes) return;
-		store.put(libraryId, bytes).catch((error) => {
-			globalThis.console?.warn(`[stamp] persisting library '${libraryId}' failed:`, error);
+function persistStampLibraries(stamp, store, options = {}) {
+	const except = new Set(options.except ?? []);
+	/** Per library: the store step waiting or running, and the one to follow it. */
+	const lines = /* @__PURE__ */ new Map();
+	const run = (libraryId, step) => {
+		const line = lines.get(libraryId);
+		if (line) {
+			if (line.started) line.next = step;
+			else line.step = step;
+			return;
+		}
+		const fresh = {
+			step,
+			started: false,
+			next: null
+		};
+		lines.set(libraryId, fresh);
+		Promise.resolve().then(async () => {
+			fresh.started = true;
+			try {
+				if (fresh.step === "save") await store.put(libraryId, await stamp.exportLibrary(libraryId));
+				else await store.delete(libraryId);
+			} catch (error) {
+				const doing = fresh.step === "save" ? "persisting" : "deleting stored";
+				globalThis.console?.warn(`[stamp] ${doing} library '${libraryId}' failed:`, error);
+			}
+			lines.delete(libraryId);
+			if (fresh.next) run(libraryId, fresh.next);
 		});
 	};
-	const off = stamp.onLibraryChanged(({ libraryId, reason }) => {
+	return stamp.onLibraryChanged(({ libraryId, reason }) => {
 		if (except.has(libraryId)) return;
-		const pending = timers.get(libraryId);
-		if (pending) clearTimeout(pending);
-		if (reason === "removed") {
-			timers.delete(libraryId);
-			store.delete(libraryId).catch((error) => {
-				globalThis.console?.warn(`[stamp] deleting stored library '${libraryId}' failed:`, error);
-			});
-			return;
-		}
-		timers.set(libraryId, setTimeout(() => write(libraryId), opts.debounceMs ?? 250));
+		run(libraryId, reason === "removed" ? "delete" : "save");
 	});
-	return () => {
-		off();
-		for (const [libraryId, timer] of timers) {
-			clearTimeout(timer);
-			write(libraryId);
-		}
-	};
 }
 //#endregion
-export { DEFAULT_LIBRARY_KIND, STAMP_LIBRARY_PIECEINFO_APP, STAMP_PIECEINFO_APP, STAMP_PIECEINFO_VERSION, StampToken, assetIdFor, customStampName, libraryKindFromPdfName, libraryKindToPdfName, memoryStampStore, parseStampKey, persistStampLibraries, restoreStampLibraries, stampKey, stampKindToPdfName, stampLibraryPieceInfo, stampPieceInfo, stampPlugin };
+export { DEFAULT_LIBRARY_KIND, STAMP_DEFAULTS, StampToken, memoryStampStore, persistStampLibraries, restoreStampLibraries, stampPlugin, stampState };
 
 //# sourceMappingURL=index.js.map