@embedpdf/plugin-stamp 2.15.0 → 3.0.0-next.0

package/dist/index.js

@@ -1,980 +1,589 @@
-import { BasePlugin, createEmitter, createScopedEmitter } from "@embedpdf/core";
-import { PdfAnnotationSubtype, uuidV4, PdfAnnotationName, Task, PdfErrorCode } from "@embedpdf/models";
-import { applyInsertUpright, clampAnnotationToPage, defineAnnotationTool } from "@embedpdf/plugin-annotation";
-const STAMP_PLUGIN_ID = "stamp";
-const manifest = {
-  id: STAMP_PLUGIN_ID,
-  name: "Stamp Plugin",
-  version: "1.0.0",
-  provides: ["stamp"],
-  requires: ["annotation"],
-  optional: ["i18n"],
-  defaultConfig: {
-    defaultLibrary: {
-      id: "custom",
-      name: "Custom Stamps",
-      nameKey: "stamp.library.custom",
-      categories: ["custom", "sidebar"]
-    },
-    manifests: [
-      {
-        url: "https://cdn.jsdelivr.net/npm/@embedpdf/default-stamps/{locale}/manifest.json",
-        fallbackLocale: "en"
-      }
-    ]
-  }
+import { createCapabilityToken, definePlugin } from "@embedpdf/core";
+import { EngineError, EngineErrorCode, resolveBinarySource, sniffBinaryMetadata } from "@embedpdf/engine-core/runtime";
+import { AnnotationToken } from "@embedpdf/plugin-annotation";
+import { createFormScriptingController } from "@embedpdf/plugin-form";
+//#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;
+const uid = (prefix) => `${prefix}-${Date.now().toString(36)}-${(seq++).toString(36)}`;
+const entryString = (entries, key) => {
+	const entry = entries[key];
+	return entry?.type === "string" && entry.value.length > 0 ? entry.value : void 0;
 };
-const ADD_STAMP_LIBRARY = "STAMP/ADD_LIBRARY";
-const REMOVE_STAMP_LIBRARY = "STAMP/REMOVE_LIBRARY";
-function addStampLibrary(id) {
-  return { type: ADD_STAMP_LIBRARY, payload: id };
-}
-function removeStampLibrary(id) {
-  return { type: REMOVE_STAMP_LIBRARY, payload: id };
-}
-const rubberStampHandlerFactory = {
-  annotationType: PdfAnnotationSubtype.STAMP,
-  create(context) {
-    const { onPreview, onCommit, getTool, pageSize, pageRotation, getToolContext } = context;
-    return {
-      onPointerMove: (pos) => {
-        const ctx = getToolContext();
-        if (!(ctx == null ? void 0 : ctx.stampSize)) return;
-        const { width, height } = ctx.stampSize;
-        onPreview({
-          type: PdfAnnotationSubtype.STAMP,
-          bounds: {
-            origin: { x: pos.x - width / 2, y: pos.y - height / 2 },
-            size: { width, height }
-          },
-          data: {
-            rect: {
-              origin: { x: pos.x - width / 2, y: pos.y - height / 2 },
-              size: { width, height }
-            },
-            ghostUrl: ctx.ghostUrl,
-            pageRotation
-          }
-        });
-      },
-      onPointerDown: (pos) => {
-        var _a;
-        const tool = getTool();
-        const ctx = getToolContext();
-        if (!tool || !(ctx == null ? void 0 : ctx.stampSize)) return;
-        const { width, height } = ctx.stampSize;
-        const rect = {
-          origin: { x: pos.x - width / 2, y: pos.y - height / 2 },
-          size: { width, height }
-        };
-        let anno = {
-          ...tool.defaults,
-          rect,
-          type: PdfAnnotationSubtype.STAMP,
-          name: ctx.stamp.name ?? tool.defaults.name ?? PdfAnnotationName.Custom,
-          subject: ctx.stamp.subject ?? tool.defaults.subject ?? "Custom Stamp",
-          flags: tool.defaults.flags ?? ["print"],
-          pageIndex: context.pageIndex,
-          id: uuidV4(),
-          created: /* @__PURE__ */ new Date()
-        };
-        if ((_a = tool.behavior) == null ? void 0 : _a.insertUpright) {
-          anno = applyInsertUpright(anno, pageRotation, false);
-        }
-        anno = clampAnnotationToPage(anno, pageSize);
-        onCommit(anno, { appearance: ctx.appearance });
-        onPreview(null);
-      },
-      onPointerLeave: () => {
-        onPreview(null);
-      }
-    };
-  }
-};
-const RUBBER_STAMP_TOOL_ID = "rubberStamp";
-const rubberStampTool = defineAnnotationTool({
-  id: RUBBER_STAMP_TOOL_ID,
-  name: "Rubber Stamp",
-  labelKey: "stamp.rubberStamp",
-  categories: ["annotation", "stamp", "insert"],
-  matchScore: () => 0,
-  interaction: {
-    exclusive: true,
-    cursor: "copy",
-    isDraggable: true,
-    isResizable: true,
-    isRotatable: false,
-    lockAspectRatio: true,
-    isGroupDraggable: true,
-    isGroupResizable: false,
-    isGroupRotatable: false
-  },
-  defaults: {
-    type: PdfAnnotationSubtype.STAMP
-  },
-  behavior: {
-    deactivateToolAfterCreate: true,
-    selectAfterCreate: true,
-    insertUpright: true,
-    useAppearanceStream: true
-  },
-  pointerHandler: rubberStampHandlerFactory
-});
-const stampTools = [rubberStampTool];
-const ANNOTATION_NAME_MAP = {
-  Approved: PdfAnnotationName.Approved,
-  Experimental: PdfAnnotationName.Experimental,
-  NotApproved: PdfAnnotationName.NotApproved,
-  AsIs: PdfAnnotationName.AsIs,
-  Expired: PdfAnnotationName.Expired,
-  NotForPublicRelease: PdfAnnotationName.NotForPublicRelease,
-  Confidential: PdfAnnotationName.Confidential,
-  Final: PdfAnnotationName.Final,
-  Sold: PdfAnnotationName.Sold,
-  Departmental: PdfAnnotationName.Departmental,
-  ForComment: PdfAnnotationName.ForComment,
-  TopSecret: PdfAnnotationName.TopSecret,
-  Draft: PdfAnnotationName.Draft,
-  ForPublicRelease: PdfAnnotationName.ForPublicRelease,
-  Completed: PdfAnnotationName.Completed,
-  Void: PdfAnnotationName.Void,
-  PreliminaryResults: PdfAnnotationName.PreliminaryResults,
-  InformationOnly: PdfAnnotationName.InformationOnly,
-  Rejected: PdfAnnotationName.Rejected,
-  Witness: PdfAnnotationName.Witness,
-  InitialHere: PdfAnnotationName.InitialHere,
-  SignHere: PdfAnnotationName.SignHere,
-  Accepted: PdfAnnotationName.Accepted,
-  Custom: PdfAnnotationName.Custom,
-  Image: PdfAnnotationName.Image
-};
-function parseAnnotationName(name) {
-  if (!name) return PdfAnnotationName.Custom;
-  return ANNOTATION_NAME_MAP[name] ?? PdfAnnotationName.Custom;
-}
-const _StampPlugin = class _StampPlugin extends BasePlugin {
-  constructor(id, registry, config) {
-    var _a, _b;
-    super(id, registry);
-    this.config = config;
-    this.instanceId = uuidV4();
-    this.libraries = /* @__PURE__ */ new Map();
-    this.libraryChange$ = createEmitter();
-    this.activeStamp$ = createScopedEmitter((documentId, activeStamp) => ({ documentId, activeStamp }));
-    this.managedManifests = [];
-    this.annotation = null;
-    this.i18n = null;
-    this.localeUnsubscribe = null;
-    this.toolChangeUnsubscribe = null;
-    this.currentGhostUrl = null;
-    this.annotation = ((_a = registry.getPlugin("annotation")) == null ? void 0 : _a.provides()) ?? null;
-    if (this.annotation) {
-      for (const tool of stampTools) {
-        this.annotation.addTool(tool);
-      }
-      this.toolChangeUnsubscribe = this.annotation.onActiveToolChange(({ documentId, tool }) => {
-        if ((tool == null ? void 0 : tool.id) !== RUBBER_STAMP_TOOL_ID) {
-          if (this.currentGhostUrl) {
-            URL.revokeObjectURL(this.currentGhostUrl);
-            this.currentGhostUrl = null;
-          }
-          this.activeStamp$.emit(documentId, null);
-        }
-      });
-    }
-    this.i18n = ((_b = registry.getPlugin("i18n")) == null ? void 0 : _b.provides()) ?? null;
-  }
-  async initialize() {
-    if (this.config.libraries) {
-      for (const libConfig of this.config.libraries) {
-        await this.loadLibraryInternal(libConfig).toPromise();
-      }
-    }
-    if (this.config.manifests && this.config.manifests.length > 0) {
-      await this.initializeManifests();
-    }
-  }
-  buildCapability() {
-    return {
-      getLibraries: () => this.getLibraries(),
-      getStampsByCategory: (category) => this.getStampsByCategory(category),
-      renderStamp: (libraryId, pageIndex, width, dpr) => this.renderStamp(libraryId, pageIndex, width, dpr),
-      loadLibrary: (config) => this.loadLibrary(config),
-      loadLibraryFromManifest: (url) => this.loadLibraryFromManifest(url),
-      createNewLibrary: (name, options) => this.createNewLibrary(name, options),
-      addStampToLibrary: (libraryId, stamp, pdf) => this.addStampToLibrary(libraryId, stamp, pdf),
-      removeStampFromLibrary: (libraryId, stampId) => this.removeStampFromLibrary(libraryId, stampId),
-      updateStamp: (libraryId, stampId, updates) => this.updateStamp(libraryId, stampId, updates),
-      updateLibrary: (libraryId, updates) => this.updateLibrary(libraryId, updates),
-      removeLibrary: (id) => this.removeLibrary(id),
-      exportLibrary: (id) => this.exportLibrary(id),
-      forDocument: (documentId) => this.createStampScope(documentId),
-      onActiveStampChange: this.activeStamp$.onGlobal,
-      onLibraryChange: this.libraryChange$.on
-    };
-  }
-  getLibraries() {
-    return Array.from(this.libraries.values());
-  }
-  getStampsByCategory(category) {
-    var _a, _b;
-    const results = [];
-    for (const library of this.libraries.values()) {
-      const libraryMatches = ((_a = library.categories) == null ? void 0 : _a.includes(category)) ?? false;
-      for (const stamp of library.stamps) {
-        const stampMatches = ((_b = stamp.categories) == null ? void 0 : _b.includes(category)) ?? false;
-        if (libraryMatches || stampMatches) {
-          results.push({ library, stamp });
-        }
-      }
-    }
-    return results;
-  }
-  renderStamp(libraryId, pageIndex, width, dpr) {
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      const task = new Task();
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    const page = library.document.pages[pageIndex];
-    if (!page) {
-      const task = new Task();
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Page ${pageIndex} not found in stamp library: ${libraryId}`
-      });
-      return task;
-    }
-    const scaleFactor = width / page.size.width;
-    return this.engine.renderPageRect(
-      library.document,
-      page,
-      { origin: { x: 0, y: 0 }, size: page.size },
-      {
-        scaleFactor,
-        dpr: dpr ?? 1,
-        withAnnotations: true,
-        rotation: page.rotation,
-        transparentBackground: true
-      }
-    );
-  }
-  loadLibrary(config) {
-    return this.loadLibraryInternal(config);
-  }
-  createNewLibrary(name, options) {
-    const task = new Task();
-    const libraryId = (options == null ? void 0 : options.id) ?? this.generateLibraryId();
-    const documentId = this.getLibraryDocumentId(libraryId);
-    this.engine.createDocument(documentId).wait(
-      (doc) => {
-        const library = {
-          id: libraryId,
-          name,
-          nameKey: options == null ? void 0 : options.nameKey,
-          document: doc,
-          stamps: [],
-          categories: options == null ? void 0 : options.categories,
-          readonly: (options == null ? void 0 : options.readonly) ?? false
-        };
-        this.libraries.set(libraryId, library);
-        this.dispatch(addStampLibrary(libraryId));
-        this.emitLibraryChange();
-        task.resolve(libraryId);
-      },
-      (error) => {
-        this.logger.error(
-          "StampPlugin",
-          "CreateNewLibrary",
-          `Failed to create library: ${name}`,
-          error
-        );
-        task.fail(error);
-      }
-    );
-    return task;
-  }
-  addStampToLibrary(libraryId, stamp, pdf) {
-    const task = new Task();
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    if (library.readonly) {
-      task.reject({
-        code: PdfErrorCode.NotSupport,
-        message: `Cannot add stamps to readonly library: ${libraryId}`
-      });
-      return task;
-    }
-    const tempDocId = `stamp-temp-${Date.now()}`;
-    this.engine.openDocumentBuffer({ id: tempDocId, content: pdf }).wait(
-      (tempDoc) => {
-        this.engine.importPages(library.document, tempDoc, [0]).wait(
-          (newPages) => {
-            const newPage = newPages[0];
-            library.document.pages.push(newPage);
-            library.document.pageCount = library.document.pages.length;
-            const stampDef = {
-              ...stamp,
-              id: uuidV4(),
-              pageIndex: newPage.index
-            };
-            library.stamps.push(stampDef);
-            this.engine.closeDocument(tempDoc).wait(
-              () => {
-                this.emitLibraryChange();
-                task.resolve();
-              },
-              () => {
-                this.emitLibraryChange();
-                task.resolve();
-              }
-            );
-          },
-          (error) => {
-            this.logger.error("StampPlugin", "AddStampToLibrary", "Failed to import page", error);
-            this.engine.closeDocument(tempDoc).wait(
-              () => task.fail(error),
-              () => task.fail(error)
-            );
-          }
-        );
-      },
-      (error) => {
-        this.logger.error(
-          "StampPlugin",
-          "AddStampToLibrary",
-          "Failed to open temp document",
-          error
-        );
-        task.fail(error);
-      }
-    );
-    return task;
-  }
-  createStampScope(documentId) {
-    return {
-      createStampFromAnnotation: (annotation, stamp, libraryId) => this.createStampFromAnnotation(documentId, annotation, stamp, libraryId),
-      createStampFromAnnotations: (annotations, stamp, libraryId) => this.createStampFromAnnotations(documentId, annotations, stamp, libraryId),
-      activateStampPlacement: (libraryId, stamp) => this.activateStampPlacement(documentId, libraryId, stamp),
-      activateStampPlacementById: (libraryId, stampId) => this.activateStampPlacementById(documentId, libraryId, stampId),
-      getActiveStamp: () => this.getActiveStamp(documentId),
-      onActiveStampChange: this.activeStamp$.forScope(documentId)
-    };
-  }
-  activateStampPlacementById(documentId, libraryId, stampId) {
-    const task = new Task();
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    const stamp = library.stamps.find((s) => s.id === stampId);
-    if (!stamp) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp ${stampId} not found in library: ${libraryId}`
-      });
-      return task;
-    }
-    return this.activateStampPlacement(documentId, libraryId, stamp);
-  }
-  getActiveStamp(documentId) {
-    return this.activeStamp$.getValue(documentId) ?? null;
-  }
-  activateStampPlacement(documentId, libraryId, stamp) {
-    const task = new Task();
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    const page = library.document.pages[stamp.pageIndex];
-    if (!page) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Page ${stamp.pageIndex} not found in library`
-      });
-      return task;
-    }
-    const stampSize = page.size;
-    this.engine.extractPages(library.document, [stamp.pageIndex]).wait(
-      (appearance) => {
-        this.renderStamp(libraryId, stamp.pageIndex, stampSize.width, 2).wait(
-          (blob) => {
-            var _a;
-            if (this.currentGhostUrl) {
-              URL.revokeObjectURL(this.currentGhostUrl);
-            }
-            const ghostUrl = URL.createObjectURL(blob);
-            this.currentGhostUrl = ghostUrl;
-            (_a = this.annotation) == null ? void 0 : _a.setActiveTool(RUBBER_STAMP_TOOL_ID, {
-              appearance,
-              ghostUrl,
-              stampSize,
-              libraryId,
-              stamp
-            });
-            this.activeStamp$.emit(documentId, { libraryId, stamp });
-            task.resolve();
-          },
-          (error) => {
-            this.logger.error(
-              "StampPlugin",
-              "ActivateStampPlacement",
-              "Failed to render stamp preview",
-              error
-            );
-            task.fail(error);
-          }
-        );
-      },
-      (error) => {
-        this.logger.error(
-          "StampPlugin",
-          "ActivateStampPlacement",
-          "Failed to extract stamp page",
-          error
-        );
-        task.fail(error);
-      }
-    );
-    return task;
-  }
-  createStampFromAnnotation(documentId, annotation, stamp, libraryId) {
-    const task = new Task();
-    const docState = this.getCoreDocument(documentId);
-    if (!(docState == null ? void 0 : docState.document)) {
-      task.reject({ code: PdfErrorCode.DocNotOpen, message: "document is not open" });
-      return task;
-    }
-    const doc = docState.document;
-    const page = doc.pages[annotation.pageIndex];
-    if (!page) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `page ${annotation.pageIndex} not found`
-      });
-      return task;
-    }
-    this.resolveTargetLibrary(libraryId).wait(
-      (targetId) => {
-        this.engine.exportAnnotationAppearanceAsPdf(doc, page, annotation).wait(
-          (pdf) => {
-            this.addStampToLibrary(targetId, stamp, pdf).wait(
-              () => task.resolve(),
-              (error) => task.fail(error)
-            );
-          },
-          (error) => {
-            this.logger.error(
-              "StampPlugin",
-              "CreateStampFromAnnotation",
-              "Failed to export annotation",
-              error
-            );
-            task.fail(error);
-          }
-        );
-      },
-      (error) => task.fail(error)
-    );
-    return task;
-  }
-  createStampFromAnnotations(documentId, annotations, stamp, libraryId) {
-    const task = new Task();
-    if (annotations.length === 0) {
-      task.reject({ code: PdfErrorCode.NotFound, message: "no annotations provided" });
-      return task;
-    }
-    const docState = this.getCoreDocument(documentId);
-    if (!(docState == null ? void 0 : docState.document)) {
-      task.reject({ code: PdfErrorCode.DocNotOpen, message: "document is not open" });
-      return task;
-    }
-    const doc = docState.document;
-    const page = doc.pages[annotations[0].pageIndex];
-    if (!page) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `page ${annotations[0].pageIndex} not found`
-      });
-      return task;
-    }
-    this.resolveTargetLibrary(libraryId).wait(
-      (targetId) => {
-        this.engine.exportAnnotationsAppearanceAsPdf(doc, page, annotations).wait(
-          (pdf) => {
-            this.addStampToLibrary(targetId, stamp, pdf).wait(
-              () => task.resolve(),
-              (error) => task.fail(error)
-            );
-          },
-          (error) => {
-            this.logger.error(
-              "StampPlugin",
-              "CreateStampFromAnnotations",
-              "Failed to export annotations",
-              error
-            );
-            task.fail(error);
-          }
-        );
-      },
-      (error) => task.fail(error)
-    );
-    return task;
-  }
-  resolveTargetLibrary(libraryId) {
-    if (libraryId && this.libraries.has(libraryId)) {
-      const task = new Task();
-      task.resolve(libraryId);
-      return task;
-    }
-    const defaults = this.config.defaultLibrary;
-    if (this.config.defaultLibrary === false || !defaults) {
-      const task = new Task();
-      task.reject({
-        code: PdfErrorCode.NotSupport,
-        message: "Default library creation is disabled"
-      });
-      return task;
-    }
-    const defaultId = defaults.id ?? "custom";
-    if (this.libraries.has(defaultId)) {
-      const task = new Task();
-      task.resolve(defaultId);
-      return task;
-    }
-    return this.createNewLibrary(defaults.name ?? "Custom Stamps", {
-      id: defaultId,
-      nameKey: defaults.nameKey,
-      categories: defaults.categories
-    });
-  }
-  removeLibrary(id) {
-    const task = new Task();
-    const library = this.libraries.get(id);
-    if (!library) {
-      task.resolve();
-      return task;
-    }
-    this.engine.closeDocument(library.document).wait(
-      () => {
-        this.libraries.delete(id);
-        this.dispatch(removeStampLibrary(id));
-        this.emitLibraryChange();
-        task.resolve();
-      },
-      () => {
-        this.logger.warn(
-          "StampPlugin",
-          "RemoveLibrary",
-          `Failed to close document for library: ${id}`
-        );
-        this.libraries.delete(id);
-        this.dispatch(removeStampLibrary(id));
-        this.emitLibraryChange();
-        task.resolve();
-      }
-    );
-    return task;
-  }
-  exportLibrary(id) {
-    const task = new Task();
-    const library = this.libraries.get(id);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${id}`
-      });
-      return task;
-    }
-    this.engine.saveAsCopy(library.document).wait(
-      (pdf) => {
-        task.resolve({
-          name: library.name,
-          pdf,
-          stamps: library.stamps,
-          categories: library.categories
-        });
-      },
-      (error) => {
-        this.logger.error("StampPlugin", "ExportLibrary", `Failed to export library: ${id}`, error);
-        task.fail(error);
-      }
-    );
-    return task;
-  }
-  loadLibraryInternal(config) {
-    const task = new Task();
-    const libraryId = config.id ?? this.generateLibraryId();
-    const documentId = this.getLibraryDocumentId(libraryId);
-    const engineTask = typeof config.pdf === "string" ? this.engine.openDocumentUrl({ id: documentId, url: config.pdf }) : this.engine.openDocumentBuffer({ id: documentId, content: config.pdf });
-    engineTask.wait(
-      (doc) => {
-        const stamps = config.stamps.map((s) => s.id ? s : { ...s, id: uuidV4() });
-        const library = {
-          id: libraryId,
-          name: config.name,
-          nameKey: config.nameKey,
-          document: doc,
-          stamps,
-          categories: config.categories,
-          readonly: config.readonly ?? false
-        };
-        this.libraries.set(libraryId, library);
-        this.dispatch(addStampLibrary(libraryId));
-        this.emitLibraryChange();
-        task.resolve(libraryId);
-      },
-      (error) => {
-        this.logger.error(
-          "StampPlugin",
-          "LoadLibrary",
-          `Failed to load stamp library: ${config.name}`,
-          error
-        );
-        task.fail(error);
-      }
-    );
-    return task;
-  }
-  removeStampFromLibrary(libraryId, stampId) {
-    const task = new Task();
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    if (library.readonly) {
-      task.reject({
-        code: PdfErrorCode.NotSupport,
-        message: `Cannot remove stamps from readonly library: ${libraryId}`
-      });
-      return task;
-    }
-    const stampIdx = library.stamps.findIndex((s) => s.id === stampId);
-    if (stampIdx === -1) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp ${stampId} not found in library: ${libraryId}`
-      });
-      return task;
-    }
-    const pageIndex = library.stamps[stampIdx].pageIndex;
-    this.engine.deletePage(library.document, pageIndex).wait(
-      () => {
-        library.stamps.splice(stampIdx, 1);
-        library.document.pages.splice(pageIndex, 1);
-        library.document.pageCount = library.document.pages.length;
-        for (const s of library.stamps) {
-          if (s.pageIndex > pageIndex) {
-            s.pageIndex--;
-          }
-        }
-        for (let i = 0; i < library.document.pages.length; i++) {
-          library.document.pages[i].index = i;
-        }
-        this.emitLibraryChange();
-        task.resolve();
-      },
-      (error) => {
-        this.logger.error(
-          "StampPlugin",
-          "RemoveStampFromLibrary",
-          `Failed to delete page for stamp ${stampId}`,
-          error
-        );
-        task.fail(error);
-      }
-    );
-    return task;
-  }
-  updateStamp(libraryId, stampId, updates) {
-    const task = new Task();
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    if (library.readonly) {
-      task.reject({
-        code: PdfErrorCode.NotSupport,
-        message: `Cannot update stamps in readonly library: ${libraryId}`
-      });
-      return task;
-    }
-    const stamp = library.stamps.find((s) => s.id === stampId);
-    if (!stamp) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp ${stampId} not found in library: ${libraryId}`
-      });
-      return task;
-    }
-    Object.assign(stamp, updates);
-    this.emitLibraryChange();
-    task.resolve();
-    return task;
-  }
-  updateLibrary(libraryId, updates) {
-    const task = new Task();
-    const library = this.libraries.get(libraryId);
-    if (!library) {
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Stamp library not found: ${libraryId}`
-      });
-      return task;
-    }
-    if (library.readonly) {
-      task.reject({
-        code: PdfErrorCode.NotSupport,
-        message: `Cannot update readonly library: ${libraryId}`
-      });
-      return task;
-    }
-    if (updates.name !== void 0) library.name = updates.name;
-    if (updates.nameKey !== void 0) library.nameKey = updates.nameKey;
-    if (updates.categories !== void 0) library.categories = updates.categories;
-    if (updates.readonly !== void 0) library.readonly = updates.readonly;
-    this.emitLibraryChange();
-    task.resolve();
-    return task;
-  }
-  loadLibraryFromManifest(url) {
-    return this.loadManifestUrl(url, true);
-  }
-  async initializeManifests() {
-    var _a;
-    const currentLocale = ((_a = this.i18n) == null ? void 0 : _a.getLocale()) ?? "en";
-    for (const source of this.config.manifests) {
-      const localeAware = source.url.includes("{locale}");
-      const locale = localeAware ? currentLocale : "";
-      const resolvedUrl = source.url.replace("{locale}", locale || currentLocale);
-      const managed = {
-        source,
-        localeAware,
-        currentLocale: localeAware ? currentLocale : "",
-        libraryId: null
-      };
-      this.managedManifests.push(managed);
-      try {
-        const libraryId = await this.loadManifestUrl(resolvedUrl, true).toPromise();
-        managed.libraryId = libraryId;
-      } catch {
-        if (localeAware && source.fallbackLocale && source.fallbackLocale !== currentLocale) {
-          const fallbackUrl = source.url.replace("{locale}", source.fallbackLocale);
-          try {
-            const libraryId = await this.loadManifestUrl(fallbackUrl, true).toPromise();
-            managed.libraryId = libraryId;
-            managed.currentLocale = source.fallbackLocale;
-          } catch {
-            this.logger.warn(
-              "StampPlugin",
-              "InitManifests",
-              `Failed to load manifest (including fallback): ${source.url}`
-            );
-          }
-        } else {
-          this.logger.warn(
-            "StampPlugin",
-            "InitManifests",
-            `Failed to load manifest: ${resolvedUrl}`
-          );
-        }
-      }
-    }
-    if (this.i18n) {
-      this.localeUnsubscribe = this.i18n.onLocaleChange((event) => {
-        this.handleLocaleChange(event.currentLocale);
-      });
-    }
-  }
-  async handleLocaleChange(newLocale) {
-    for (const managed of this.managedManifests) {
-      if (!managed.localeAware || managed.currentLocale === newLocale) {
-        continue;
-      }
-      if (managed.libraryId) {
-        try {
-          await this.removeLibrary(managed.libraryId).toPromise();
-        } catch {
-        }
-        managed.libraryId = null;
-      }
-      const resolvedUrl = managed.source.url.replace("{locale}", newLocale);
-      try {
-        const libraryId = await this.loadManifestUrl(resolvedUrl, true).toPromise();
-        managed.libraryId = libraryId;
-        managed.currentLocale = newLocale;
-      } catch {
-        const fallback = managed.source.fallbackLocale ?? "en";
-        if (fallback !== newLocale) {
-          const fallbackUrl = managed.source.url.replace("{locale}", fallback);
-          try {
-            const libraryId = await this.loadManifestUrl(fallbackUrl, true).toPromise();
-            managed.libraryId = libraryId;
-            managed.currentLocale = fallback;
-          } catch {
-            this.logger.warn(
-              "StampPlugin",
-              "LocaleChange",
-              `Failed to load manifest for locale ${newLocale} (including fallback): ${managed.source.url}`
-            );
-          }
-        } else {
-          this.logger.warn(
-            "StampPlugin",
-            "LocaleChange",
-            `Failed to load manifest for locale ${newLocale}: ${managed.source.url}`
-          );
-        }
-      }
-    }
-  }
-  loadManifestUrl(url, readonly) {
-    const task = new Task();
-    fetch(url).then((response) => {
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-      return response.json();
-    }).then((manifest2) => {
-      const pdfUrl = this.resolveManifestPdfUrl(url, manifest2.pdf);
-      const stamps = manifest2.stamps.map((entry) => ({
-        id: entry.id ?? uuidV4(),
-        pageIndex: entry.pageIndex,
-        name: parseAnnotationName(entry.name),
-        subject: entry.subject,
-        subjectKey: entry.subjectKey,
-        label: entry.label,
-        categories: entry.categories
-      }));
-      const config = {
-        id: manifest2.id,
-        name: manifest2.name,
-        nameKey: manifest2.nameKey,
-        pdf: pdfUrl,
-        stamps,
-        categories: manifest2.categories,
-        readonly
-      };
-      this.loadLibraryInternal(config).wait(
-        (libraryId) => task.resolve(libraryId),
-        (error) => task.fail(error)
-      );
-    }).catch((error) => {
-      this.logger.error("StampPlugin", "LoadManifest", `Failed to fetch manifest: ${url}`, error);
-      task.reject({
-        code: PdfErrorCode.NotFound,
-        message: `Failed to load stamp manifest: ${url}`
-      });
-    });
-    return task;
-  }
-  resolveManifestPdfUrl(manifestUrl, pdfPath) {
-    if (pdfPath.startsWith("http://") || pdfPath.startsWith("https://") || pdfPath.startsWith("/")) {
-      return pdfPath;
-    }
-    const base = manifestUrl.substring(0, manifestUrl.lastIndexOf("/") + 1);
-    return base + pdfPath;
-  }
-  generateLibraryId() {
-    return uuidV4();
-  }
-  getLibraryDocumentId(libraryId) {
-    return `stamp-doc-${this.instanceId}-${libraryId}`;
-  }
-  emitLibraryChange() {
-    this.libraryChange$.emit(this.getLibraries());
-  }
-  async destroy() {
-    if (this.currentGhostUrl) {
-      URL.revokeObjectURL(this.currentGhostUrl);
-      this.currentGhostUrl = null;
-    }
-    if (this.toolChangeUnsubscribe) {
-      this.toolChangeUnsubscribe();
-      this.toolChangeUnsubscribe = null;
-    }
-    if (this.localeUnsubscribe) {
-      this.localeUnsubscribe();
-      this.localeUnsubscribe = null;
-    }
-    this.activeStamp$.clear();
-    const libs = Array.from(this.libraries.values());
-    for (const library of libs) {
-      try {
-        await this.engine.closeDocument(library.document).toPromise();
-      } catch {
-      }
-    }
-    this.libraries.clear();
-    this.managedManifests.length = 0;
-    super.destroy();
-  }
+const entryName = (entries, key) => {
+	const entry = entries[key];
+	return entry?.type === "name" && entry.value.length > 0 ? entry.value : void 0;
 };
-_StampPlugin.id = STAMP_PLUGIN_ID;
-let StampPlugin = _StampPlugin;
-const initialState = {
-  libraryIds: []
+const entryStringArray = (entries, key) => {
+	const entry = entries[key];
+	return entry?.type === "string-array" ? [...entry.value] : void 0;
 };
-const stampReducer = (state = initialState, action) => {
-  switch (action.type) {
-    case ADD_STAMP_LIBRARY:
-      return {
-        ...state,
-        libraryIds: [...state.libraryIds, action.payload]
-      };
-    case REMOVE_STAMP_LIBRARY:
-      return {
-        ...state,
-        libraryIds: state.libraryIds.filter((id) => id !== action.payload)
-      };
-    default:
-      return state;
-  }
+const kindToPdfName = (kind) => kind === "signature" ? "Signature" : kind === "initials" ? "Initials" : "Stamp";
+const kindFromPdfName = (name) => {
+	switch (name?.toLowerCase()) {
+		case "stamp": return "stamp";
+		case "signature": return "signature";
+		case "initials": return "initials";
+		default: return;
+	}
 };
-const StampPluginPackage = {
-  manifest,
-  create: (registry, config) => new StampPlugin(STAMP_PLUGIN_ID, registry, config),
-  reducer: stampReducer,
-  initialState
-};
-export {
-  ADD_STAMP_LIBRARY,
-  REMOVE_STAMP_LIBRARY,
-  RUBBER_STAMP_TOOL_ID,
-  STAMP_PLUGIN_ID,
-  StampPlugin,
-  StampPluginPackage,
-  addStampLibrary,
-  initialState,
-  manifest,
-  removeStampLibrary,
-  stampReducer
+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). */
+	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, identity) => {
+		try {
+			return await (await assetEngine()).open({
+				kind: "bytes",
+				id: uid("stamp-import"),
+				bytes
+			}, {
+				scope: ["*"],
+				...identity ? { identity } : {}
+			});
+		} 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 createLooseLibrary = (name) => {
+		const id = uid("stamp-lib");
+		ctx.dispatch({
+			type: "LIBRARY_ADDED",
+			library: {
+				id,
+				name,
+				storage: "loose",
+				assetIds: []
+			}
+		});
+		return id;
+	};
+	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 || !doc.pages.extract) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need an asset engine with pieceInfo and pages.extract");
+			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);
+			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 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 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
+					},
+					background: "transparent",
+					includeAnnotations: true,
+					format: "png"
+				});
+				assets.push({
+					asset,
+					bytes,
+					preview: imageToPreview(image)
+				});
+			}
+			imported = {
+				library: {
+					id: libraryId,
+					name: libraryName,
+					storage: "canonical-pdf",
+					categories: libraryCategories,
+					assetIds: []
+				},
+				canonicalBytes: await doc.download(),
+				assets
+			};
+		} finally {
+			await doc.close();
+		}
+		libraryBinaries.set(imported.library.id, imported.canonicalBytes);
+		ctx.dispatch({
+			type: "LIBRARY_ADDED",
+			library: imported.library
+		});
+		for (const { asset, bytes, preview } of imported.assets) {
+			binaries.set(asset.id, {
+				bytes,
+				preview
+			});
+			ctx.dispatch({
+				type: "ASSET_ADDED",
+				asset
+			});
+		}
+		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}'`);
+		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";
+		let suppliedPreview = null;
+		if (input.preview) {
+			const preview = await resolveBinarySource(input.preview);
+			suppliedPreview = {
+				bytes: new Uint8Array(preview.bytes),
+				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 {
+					if (!doc.pages.insert || !doc.pages.extract) throw new EngineError(EngineErrorCode.NotImplemented, "[stamp] appending to a canonical library needs pages.insert and pages.extract");
+					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
+						},
+						background: "transparent",
+						includeAnnotations: true,
+						format: "png"
+					}));
+					appended = {
+						asset,
+						bytes,
+						preview,
+						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
+				});
+				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
+			});
+			ctx.dispatch({
+				type: "ASSET_ADDED",
+				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);
+		});
+	};
+	const dropLibrary = (id) => {
+		const library = ctx.getState().libraries[id];
+		if (library) for (const assetId of library.assetIds) binaries.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?.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);
+			}
+			binaries.delete(id);
+			ctx.dispatch({
+				type: "ASSET_REMOVED",
+				assetId: id
+			});
+		});
+	};
+	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);
+		}
+	};
+	/**
+	* 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.
+	*/
+	const materializeForPlacement = async (documentId, asset, bin) => {
+		if (asset.format !== "pdf" || !config.scripting?.enabled) return bin;
+		const targetDoc = ctx.documentHandle(documentId);
+		const targetMeta = ctx.core().documents[documentId] ?? null;
+		if (!targetDoc || !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);
+		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");
+			const snapshot = await doc.forms.list();
+			if (!snapshot.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 scriptingConfig = config.scripting;
+			scripting = createFormScriptingController({
+				doc,
+				document: () => targetMeta,
+				config: scriptingConfig,
+				sandboxFactory: scriptingConfig.sandboxFactory ?? (() => import("@embedpdf/core-js-sandbox").then(({ createQuickJsSandbox }) => createQuickJsSandbox()))
+			});
+			const result = await scripting.recalculate(snapshot);
+			surfaceScriptingResult(result);
+			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({
+				viewport: {
+					kind: "width",
+					width: config.previewWidth ?? DEFAULT_PREVIEW_WIDTH
+				},
+				background: "transparent",
+				includeAnnotations: false,
+				format: "png"
+			});
+			return {
+				bytes,
+				preview: imageToPreview(image)
+			};
+		} finally {
+			scripting?.dispose();
+			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({
+			source: placement.bytes,
+			preview: placement.preview ? {
+				data: placement.preview.bytes,
+				mimeType: placement.preview.mimeType
+			} : void 0,
+			intrinsicSize: asset.size,
+			targetWidth: opts?.targetWidth
+		});
+	};
+	ctx.cleanup(() => {
+		binaries.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: () => {
+			const s = ctx.getState();
+			return s.libraryOrder.map((id) => s.libraries[id]).filter((l) => l != null);
+		},
+		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,
+		libraryBytes: (id) => libraryBinaries.get(id) ?? null,
+		importLibraryPdf,
+		addAsset,
+		removeAsset,
+		removeLibrary,
+		armAsset,
+		disarm: (documentId) => ctx.forDocument(AnnotationToken, documentId).disarmStamp()
+	};
+}
+//#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_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]
+					}
+				}
+			};
+		}
+		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
+			};
+		}
+		default: return state;
+	}
 };
-//# sourceMappingURL=index.js.map
+//#endregion
+//#region src/types.ts
+const StampToken = createCapabilityToken("stamp");
+//#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).
+*/
+const stampPlugin = (config = {}) => definePlugin({
+	id: "stamp",
+	token: StampToken,
+	scope: "workspace",
+	initialState: initialStampState,
+	reduce: stampReducer,
+	capability: (ctx) => createStampCapability(ctx, config)
+});
+//#endregion
+export { StampToken, stampPlugin };
+
+//# sourceMappingURL=index.js.map