@embedpdf/plugin-stamp 3.0.0-next.11 → 3.0.0-next.12

package/dist/index.js

@@ -1,13 +1,42 @@
-import { t as StampToken } from "./contract-CkPaVNAJ.js";
-import { definePlugin } from "@embedpdf/core";
+import { a as assetIdFor, c as stampKey, d as stampPieceInfo, i as STAMP_PIECEINFO_VERSION, l as stampKindToPdfName, n as STAMP_LIBRARY_PIECEINFO_APP, o as customStampName, r as STAMP_PIECEINFO_APP, s as parseStampKey, t as StampToken, u as stampLibraryPieceInfo } from "./contract-BFCBVNRX.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 { AnnotationToken } from "@embedpdf/plugin-annotation/contract";
 import { createFormScriptingController } from "@embedpdf/plugin-form/scripting";
+//#region src/blank-library.ts
+/**
+* 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
+* blank is that page. It is never an asset, never placed, never listed.
+*/
+const BLANK_OBJECTS = [
+	"<< /Type /Catalog /Pages 2 0 R >>",
+	"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+	"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>"
+];
+let cached = null;
+function blankLibraryPdf() {
+	if (cached) return new Uint8Array(cached);
+	let body = "%PDF-1.7\n";
+	const offsets = [];
+	BLANK_OBJECTS.forEach((object, index) => {
+		offsets.push(body.length);
+		body += `${index + 1} 0 obj\n${object}\nendobj\n`;
+	});
+	const xref = body.length;
+	body += `xref\n0 ${BLANK_OBJECTS.length + 1}\n0000000000 65535 f \n`;
+	for (const offset of offsets) body += `${String(offset).padStart(10, "0")} 00000 n \n`;
+	body += `trailer\n<< /Size ${BLANK_OBJECTS.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`;
+	cached = new TextEncoder().encode(body);
+	return new Uint8Array(cached);
+}
+//#endregion
 //#region src/capability.ts
 const DEFAULT_PREVIEW_WIDTH = 256;
-const LIBRARY_PIECEINFO_APP = "EMBD_StampLibrary";
-const STAMP_PIECEINFO_APP = "EMBD_Stamp";
-const STAMP_SCHEMA_VERSION = 1;
 /** 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;
@@ -24,7 +53,6 @@ const entryStringArray = (entries, key) => {
 	const entry = entries[key];
 	return entry?.type === "string-array" ? [...entry.value] : void 0;
 };
-const kindToPdfName = (kind) => kind === "signature" ? "Signature" : kind === "initials" ? "Initials" : "Stamp";
 const kindFromPdfName = (name) => {
 	switch (name?.toLowerCase()) {
 		case "stamp": return "stamp";
@@ -33,21 +61,6 @@ const kindFromPdfName = (name) => {
 		default: return;
 	}
 };
-const metadataPatch = (id, name, kind, subject, categories) => ({
-	Version: STAMP_SCHEMA_VERSION,
-	Id: id,
-	Name: name,
-	Kind: { name: kindToPdfName(kind) },
-	Subject: subject ?? null,
-	Categories: categories ?? null
-});
-const libraryMetadataPatch = (id, name, categories) => ({
-	Version: STAMP_SCHEMA_VERSION,
-	Id: id,
-	Name: name,
-	Kind: { name: "StampLibrary" },
-	Categories: categories ?? null
-});
 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). */
@@ -74,16 +87,13 @@ function createStampCapability(ctx, config = {}) {
 		}
 		return assetEngineRef;
 	};
-	const openAssetDocument = async (bytes, identity) => {
+	const openAssetDocument = async (bytes) => {
 		try {
 			return await (await assetEngine()).open({
 				kind: "bytes",
 				id: uid("stamp-import"),
 				bytes
-			}, {
-				scope: ["*"],
-				...identity ? { identity } : {}
-			});
+			}, { 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;
@@ -106,94 +116,151 @@ function createStampCapability(ctx, config = {}) {
 		taken.add(id);
 		return id;
 	};
-	const createLooseLibrary = (name) => {
-		const id = uid("stamp-lib");
+	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 taken = new Set(Object.keys(ctx.getState().libraries));
+		const id = allocateId(opts?.id, "stamp-lib", taken);
+		const doc = await openAssetDocument(blankLibraryPdf());
+		let bytes;
+		try {
+			requireCanonicalServices(doc);
+			await doc.metadata.update({ title: name });
+			await doc.pieceInfo.update(STAMP_LIBRARY_PIECEINFO_APP, stampLibraryPieceInfo(id, { categories: opts?.categories }));
+			bytes = await doc.download();
+		} finally {
+			await doc.close();
+		}
+		libraryBinaries.set(id, bytes);
 		ctx.dispatch({
 			type: "LIBRARY_ADDED",
 			library: {
 				id,
 				name,
-				storage: "loose",
-				assetIds: []
+				assetIds: [],
+				...opts?.categories ? { categories: opts.categories } : {}
 			}
 		});
+		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)");
+	};
 	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));
 		let imported;
 		try {
-			if (!doc.pieceInfo) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need an asset engine with pieceInfo");
-			const snapshot = await doc.pages.list();
-			if (snapshot.pageCount === 0) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] a canonical stamp library PDF must contain at least one page");
-			const pages = snapshot.pages.map((layout) => {
-				const handle = doc.page(layout.pageObjectNumber);
-				if (!handle.pieceInfo) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need page pieceInfo support");
-				return {
-					layout,
-					handle,
-					metadata: null
-				};
-			});
-			const catalogMetadata = await doc.pieceInfo.read(LIBRARY_PIECEINFO_APP);
-			for (const page of pages) page.metadata = await page.handle.pieceInfo.read(STAMP_PIECEINFO_APP);
+			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));
-			const takenAssetIds = new Set(Object.keys(state.assets));
-			const catalogEntries = catalogMetadata?.entries ?? {};
 			const libraryId = allocateId(entryString(catalogEntries, "Id"), "stamp-lib", takenLibraryIds);
-			const libraryName = opts?.name ?? entryString(catalogEntries, "Name") ?? "Stamps";
+			const docMeta = await doc.metadata.read();
+			const libraryName = (docMeta.title && docMeta.title.length > 0 ? docMeta.title : void 0) ?? entryString(catalogEntries, "Name") ?? opts?.name ?? "Stamps";
+			if (!docMeta.title) await doc.metadata.update({ title: libraryName });
 			const libraryCategories = opts?.categories ?? entryStringArray(catalogEntries, "Categories");
-			const descriptors = pages.map(({ layout, handle, metadata: pageMetadata }) => {
-				const entries = pageMetadata?.entries ?? {};
-				const id = allocateId(entryString(entries, "Id"), "stamp", takenAssetIds);
-				const kind = opts?.kind ?? kindFromPdfName(entryName(entries, "Kind")) ?? "stamp";
-				return {
-					handle,
-					asset: {
-						id,
-						libraryId,
-						kind,
-						name: opts?.assetName?.(layout.index) ?? entryString(entries, "Name") ?? `Stamp ${layout.index + 1}`,
-						size: {
-							width: layout.size.width,
-							height: layout.size.height
-						},
-						format: "pdf",
-						pageObjectNumber: layout.pageObjectNumber,
-						subject: entryString(entries, "Subject"),
-						categories: entryStringArray(entries, "Categories")
-					}
-				};
-			});
-			await doc.pieceInfo.update(LIBRARY_PIECEINFO_APP, libraryMetadataPatch(libraryId, libraryName, libraryCategories));
+			const libraryLocale = entryString(catalogEntries, "Locale");
+			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`);
+			let descriptors;
+			if (registry.length > 0) {
+				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}'`);
+					seen.add(name);
+					const page = byPon.get(entry.target.pageObjectNumber);
+					return {
+						pageObjectNumber: page.pageObjectNumber,
+						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");
+			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;
+					descriptors.push({
+						pageObjectNumber: page.pageObjectNumber,
+						index: page.index,
+						name,
+						label
+					});
+				}
+				for (const d of descriptors) await doc.pages.setName({
+					name: stampKey(d.name, d.label),
+					pageObjectNumber: d.pageObjectNumber
+				});
+			}
+			await doc.pieceInfo.update(STAMP_LIBRARY_PIECEINFO_APP, stampLibraryPieceInfo(libraryId, {
+				categories: libraryCategories,
+				locale: libraryLocale
+			}));
 			const assets = [];
-			for (const descriptor of descriptors) {
-				const { asset, handle } = descriptor;
-				await handle.pieceInfo.update(STAMP_PIECEINFO_APP, metadataPatch(asset.id, asset.name, asset.kind, asset.subject, asset.categories));
-				const bytes = await doc.pages.extract([asset.pageObjectNumber]);
-				const image = await handle.render.image({
-					viewport: {
-						kind: "width",
-						width: config.previewWidth ?? DEFAULT_PREVIEW_WIDTH
+			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";
+				const subject = entryString(entries, "SubjectOverride");
+				const categories = entryStringArray(entries, "Categories");
+				const page = byPon.get(d.pageObjectNumber);
+				const asset = {
+					id: assetIdFor(libraryId, d.name),
+					libraryId,
+					kind,
+					name: d.name,
+					label: d.label,
+					size: {
+						width: page.size.width,
+						height: page.size.height
 					},
-					background: "transparent",
-					includeAnnotations: true,
-					format: "png"
-				});
+					pageObjectNumber: d.pageObjectNumber,
+					...subject !== void 0 ? { subject } : {},
+					...categories !== void 0 ? { categories } : {}
+				};
+				await handle.pieceInfo.update(STAMP_PIECEINFO_APP, stampPieceInfo(kind, {
+					subject,
+					categories
+				}));
+				const bytes = await doc.pages.extract([d.pageObjectNumber]);
 				assets.push({
 					asset,
 					bytes,
-					preview: imageToPreview(image)
+					preview: await renderThumbnail(handle)
 				});
 			}
 			imported = {
 				library: {
 					id: libraryId,
 					name: libraryName,
-					storage: "canonical-pdf",
+					...libraryLocale ? { locale: libraryLocale } : {},
 					categories: libraryCategories,
 					assetIds: []
 				},
@@ -218,15 +285,26 @@ function createStampCapability(ctx, config = {}) {
 				asset
 			});
 		}
+		libraryChanged.emit({
+			libraryId: imported.library.id,
+			reason: "imported"
+		});
 		return imported.library.id;
 	};
 	const addAsset = async (input) => {
-		const targetLibrary = input.libraryId ? ctx.getState().libraries[input.libraryId] ?? null : null;
-		if (input.libraryId && !targetLibrary) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown library '${input.libraryId}'`);
+		if (input.libraryId && !ctx.getState().libraries[input.libraryId]) throw new EngineError(EngineErrorCode.NotFound, `[stamp] unknown library '${input.libraryId}'`);
 		const resolved = await resolveBinarySource(input.source);
 		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);
@@ -235,111 +313,106 @@ function createStampCapability(ctx, config = {}) {
 				mimeType: preview.mimeType ?? "image/png"
 			};
 		}
-		if (targetLibrary?.storage === "canonical-pdf") {
-			if (!isPdf) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] raster assets cannot be appended to a canonical PDF library");
-			return mutateLibrary(targetLibrary.id, async () => {
-				const liveLibrary = ctx.getState().libraries[targetLibrary.id];
-				if (liveLibrary?.storage !== "canonical-pdf") throw new EngineError(EngineErrorCode.NotFound, `[stamp] canonical library '${targetLibrary.id}' no longer exists`);
-				const canonicalBytes = libraryBinaries.get(liveLibrary.id);
-				if (!canonicalBytes) throw new EngineError(EngineErrorCode.Unknown, `[stamp] canonical bytes are missing for library '${liveLibrary.id}'`);
-				const assetId = uid("stamp");
-				const doc = await openAssetDocument(canonicalBytes);
-				let appended;
-				try {
+		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 canonical library asset must be a single-page PDF");
-					const pageObjectNumber = result.insertedPageObjectNumbers[0];
-					const layout = result.layout.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");
-					const asset = {
-						id: assetId,
-						libraryId: liveLibrary.id,
-						kind: input.kind ?? "stamp",
-						name: input.name,
-						size: {
-							width: layout.size.width,
-							height: layout.size.height
-						},
-						format: "pdf",
-						pageObjectNumber,
-						subject: input.subject,
-						categories: input.categories
-					};
-					await page.pieceInfo.update(STAMP_PIECEINFO_APP, metadataPatch(asset.id, asset.name, asset.kind, asset.subject, asset.categories));
-					const bytes = await doc.pages.extract([pageObjectNumber]);
-					let preview = suppliedPreview;
-					if (!preview) preview = imageToPreview(await page.render.image({
-						viewport: {
-							kind: "width",
-							width: config.previewWidth ?? DEFAULT_PREVIEW_WIDTH
+					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
 						},
-						background: "transparent",
-						includeAnnotations: true,
-						format: "png"
-					}));
-					appended = {
-						asset,
-						bytes,
-						preview,
-						canonical: await doc.download()
-					};
-				} finally {
-					await doc.close();
+						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");
 				}
-				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
+				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
 				});
-				return appended.asset.id;
-			});
-		}
-		const size = input.size ?? ("width" in meta ? {
-			width: meta.width,
-			height: meta.height
-		} : null);
-		if (!size) throw new EngineError(EngineErrorCode.InvalidArg, "[stamp] a PDF asset needs `size` (its page size in points) — PDF bytes carry no sniffable dimensions");
-		let preview = suppliedPreview;
-		if (!preview && !isPdf) preview = {
-			bytes: new Uint8Array(resolved.bytes),
-			mimeType: meta.mimeType
-		};
-		const commitLooseAsset = (libraryId) => {
-			const asset = {
-				id: uid("stamp"),
-				libraryId,
-				kind: input.kind ?? "stamp",
-				name: input.name,
-				size,
-				format: isPdf ? "pdf" : meta.mimeType === "image/png" ? "png" : "jpeg",
-				subject: input.subject,
-				categories: input.categories
-			};
-			binaries.set(asset.id, {
-				bytes: new Uint8Array(resolved.bytes),
-				preview
+				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
+				asset: appended.asset
 			});
-			return asset.id;
-		};
-		if (!targetLibrary) return commitLooseAsset(createLooseLibrary(input.name));
-		return mutateLibrary(targetLibrary.id, async () => {
-			const liveLibrary = ctx.getState().libraries[targetLibrary.id];
-			if (liveLibrary?.storage !== "loose") throw new EngineError(EngineErrorCode.NotFound, `[stamp] loose library '${targetLibrary.id}' no longer exists`);
-			return commitLooseAsset(liveLibrary.id);
+			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);
+		if (library) for (const assetId of library.assetIds) {
+			binaries.delete(assetId);
+			ghostRenders.delete(assetId);
+		}
 		libraryBinaries.delete(id);
 		ctx.dispatch({
 			type: "LIBRARY_REMOVED",
@@ -353,54 +426,103 @@ function createStampCapability(ctx, config = {}) {
 			const asset = ctx.getState().assets[id];
 			if (!asset) return;
 			const library = ctx.getState().libraries[asset.libraryId];
-			if (library?.storage === "canonical-pdf") {
-				if (library.assetIds.length === 1) {
-					dropLibrary(library.id);
-					return;
-				}
-				if (asset.pageObjectNumber === void 0) throw new EngineError(EngineErrorCode.Unknown, `[stamp] canonical asset '${id}' has no page object number`);
-				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);
+			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"
+			});
 		});
 	};
-	const removeLibrary = (id) => mutateLibrary(id, async () => dropLibrary(id));
-	const surfaceScriptingResult = (result) => {
-		try {
-			for (const effect of result.uiEffects) config.scripting?.onUiEffect?.(effect);
-			for (const diagnostic of result.diagnostics) config.scripting?.onDiagnostic?.(diagnostic);
-			if (result.error) config.scripting?.onError?.(result.error);
-		} catch (error) {
-			globalThis.console?.error("[stamp] scripting observer failed:", error);
-		}
+	const removeLibrary = (id) => mutateLibrary(id, async () => {
+		const existed = ctx.getState().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
+			});
+			libraryChanged.emit({
+				libraryId: library.id,
+				reason: "asset-updated"
+			});
+		});
 	};
 	/**
 	* 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.
 	*/
 	const materializeForPlacement = async (documentId, asset, bin) => {
-		if (asset.format !== "pdf" || !config.scripting?.enabled) return bin;
-		const targetDoc = ctx.documentHandle(documentId);
+		if (config.dynamic === false) return bin;
+		const actions = ctx.tryForDocument(ActionsToken, documentId);
+		const mintRealm = actions?.createDetachedScriptRealm;
+		if (!actions || !mintRealm) return bin;
 		const targetMeta = ctx.core().documents[documentId] ?? null;
-		if (!targetDoc || !targetMeta) throw new EngineError(EngineErrorCode.NotFound, `[stamp] target document '${documentId}' is not open`);
+		if (!targetMeta) throw new EngineError(EngineErrorCode.NotFound, `[stamp] target document '${documentId}' is not open`);
 		const canonicalBytes = libraryBinaries.get(asset.libraryId);
 		const sourceBytes = canonicalBytes ?? bin.bytes;
-		const doc = await openAssetDocument(new Uint8Array(sourceBytes), targetDoc.security.identity);
+		const doc = await openAssetDocument(new Uint8Array(sourceBytes));
+		let realm = null;
 		let scripting = null;
 		try {
 			const layout = await doc.pages.list();
@@ -408,13 +530,24 @@ function createStampCapability(ctx, config = {}) {
 			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");
+			realm = mintRealm.call(actions, {
+				doc,
+				document: () => targetMeta,
+				bootSources: async () => {
+					return (doc.actions ? await doc.actions.read() : null)?.nameTreeScripts.map(({ action }) => javaScriptProgramFromActionTree(action)) ?? [];
+				}
+			});
 			scripting = createFormScriptingController({
 				doc,
 				document: () => targetMeta,
-				config: config.scripting
+				transaction: realm.transaction.bind(realm),
+				budget: realm.budget
 			});
 			const result = await scripting.recalculate();
-			surfaceScriptingResult(result);
+			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");
@@ -435,6 +568,7 @@ function createStampCapability(ctx, config = {}) {
 			};
 		} finally {
 			scripting?.dispose();
+			realm?.dispose();
 			await doc.close();
 		}
 	};
@@ -444,17 +578,72 @@ function createStampCapability(ctx, config = {}) {
 		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({
-			source: placement.bytes,
-			preview: placement.preview ? {
-				data: placement.preview.bytes,
-				mimeType: placement.preview.mimeType
-			} : void 0,
-			intrinsicSize: asset.size,
+			...stampPayload(asset, placement, placement !== bin),
 			targetWidth: opts?.targetWidth
 		});
 	};
+	/**
+	* 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();
+		}
+	};
+	/** 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;
+		};
+	};
+	/** 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);
+	};
 	ctx.cleanup(() => {
 		binaries.clear();
+		ghostRenders.clear();
 		libraryBinaries.clear();
 		libraryMutationTails.clear();
 		const ownedAssetEngine = typeof config.assetEngine === "function" ? assetEngineRef : null;
@@ -478,12 +667,17 @@ function createStampCapability(ctx, config = {}) {
 		asset: (id) => ctx.getState().assets[id] ?? null,
 		assetPreview: (id) => binaries.get(id)?.preview ?? null,
 		assetBytes: (id) => binaries.get(id)?.bytes ?? null,
-		libraryBytes: (id) => libraryBinaries.get(id) ?? null,
+		exportLibrary: (id) => libraryBinaries.get(id) ?? null,
+		onLibraryChanged: libraryChanged.on,
+		createLibrary,
 		importLibraryPdf,
 		addAsset,
+		addAssetFromAnnotations,
+		updateAsset,
 		removeAsset,
 		removeLibrary,
 		armAsset,
+		placeAsset,
 		disarm: (documentId) => ctx.forDocument(AnnotationToken, documentId).disarmStamp()
 	};
 }
@@ -538,6 +732,13 @@ const stampReducer = (state, action) => {
 				}
 			};
 		}
+		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;
@@ -578,6 +779,77 @@ const stampPlugin = (config = {}) => definePlugin({
 	capability: (ctx) => createStampCapability(ctx, config)
 });
 //#endregion
-export { StampToken, stampPlugin };
+//#region src/persistence.ts
+/** An in-memory store — tests and SSR. */
+function memoryStampStore() {
+	const rows = /* @__PURE__ */ new Map();
+	return {
+		list: async () => [...rows.entries()].map(([id, bytes]) => ({
+			id,
+			bytes
+		})),
+		put: async (id, bytes) => {
+			rows.set(id, new Uint8Array(bytes));
+		},
+		delete: async (id) => {
+			rows.delete(id);
+		}
+	};
+}
+/**
+* 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
+* 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));
+	} 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.
+*/
+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);
+		});
+	};
+	const off = 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));
+	});
+	return () => {
+		off();
+		for (const [libraryId, timer] of timers) {
+			clearTimeout(timer);
+			write(libraryId);
+		}
+	};
+}
+//#endregion
+export { STAMP_LIBRARY_PIECEINFO_APP, STAMP_PIECEINFO_APP, STAMP_PIECEINFO_VERSION, StampToken, assetIdFor, customStampName, memoryStampStore, parseStampKey, persistStampLibraries, restoreStampLibraries, stampKey, stampKindToPdfName, stampLibraryPieceInfo, stampPieceInfo, stampPlugin };
 
 //# sourceMappingURL=index.js.map