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

package/dist/contract-T-v5KaYd.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-T-v5KaYd.cjs","names":[],"sources":["../src/convention.ts","../src/types.ts"],"sourcesContent":["/**\n * Acrobat's stamp-library convention, interpreted in ONE place. A library is\n * a PDF whose `/Names /Pages` registry names each stamp page with a key of\n * the form `identifier=label`:\n *\n *   - `identifier` (before the first `=`) is the stamp's durable identity\n *     and becomes the placed annotation's `/Name` — a standard name such as\n *     `Approved`, or a custom one such as Acrobat's `#LBGiYhk8V_oAfmqAPENiwD`;\n *   - `label` (after it) is what the picker shows and the placed\n *     annotation's default `/Subj`.\n *\n * The engine never interprets key text; this module does. A key without\n * `=` is its own label. `#` is never stripped — it is part of the identity.\n */\nimport type { PieceInfoPatch } from '@embedpdf/engine-core/runtime';\nimport type { StampAssetKind } from './types';\n\nexport interface StampKey {\n  name: string;\n  label: string;\n}\n\nexport function parseStampKey(key: string): StampKey {\n  const separator = key.indexOf('=');\n  if (separator < 0) return { name: key, label: key };\n  return { name: key.slice(0, separator), label: key.slice(separator + 1) };\n}\n\nexport function stampKey(name: string, label: string): string {\n  return `${name}=${label}`;\n}\n\nconst BASE62 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';\n\n/**\n * A fresh identifier for a stamp authored here, in Acrobat's own shape\n * (`#` + 22 base-62 characters) so a stamp created in this viewer keeps its\n * identity when the library is opened and placed in Acrobat.\n */\nexport function customStampName(random: () => number = Math.random): string {\n  let out = '#';\n  for (let i = 0; i < 22; i++) out += BASE62[Math.floor(random() * BASE62.length)];\n  return out;\n}\n\n/** Asset ids are derived, not allocated: library id + identifier. */\nexport function assetIdFor(libraryId: string, name: string): string {\n  return `${libraryId}:${name}`;\n}\n\n// ── PieceInfo: only what has no standard home ────────────────────────────────\n//\n// The title, the registry, and the artwork are standard PDF. What remains —\n// a durable library id, categories, a locale, a stamp's kind and an explicit\n// `/Subj` override — rides `/PieceInfo` under these application names, in\n// the shape below. Exported so a library authored outside the plugin (a\n// conversion script, a build step) writes the same dictionary the plugin\n// reads.\n\n/** Catalog `/PieceInfo` application name for library-level data. */\nexport const STAMP_LIBRARY_PIECEINFO_APP = 'EMBD_StampLibrary';\n/** Page `/PieceInfo` application name for per-stamp data. */\nexport const STAMP_PIECEINFO_APP = 'EMBD_Stamp';\n/** The `Version` both dictionaries carry. */\nexport const STAMP_PIECEINFO_VERSION = 2;\n\n/** The library kind every file has unless it says otherwise. */\nexport const DEFAULT_LIBRARY_KIND = 'stamps';\n\n/** `/Kind` names: the two the plugin defines keep their PDF spellings; others are written as given. */\nexport function libraryKindToPdfName(kind: string): string {\n  return kind === 'stamps' ? 'StampLibrary' : kind === 'signatures' ? 'SignatureLibrary' : kind;\n}\n\nexport function libraryKindFromPdfName(name: string | undefined): string {\n  if (!name || name === 'StampLibrary') return DEFAULT_LIBRARY_KIND;\n  return name === 'SignatureLibrary' ? 'signatures' : name;\n}\n\nexport function stampKindToPdfName(kind: StampAssetKind): string {\n  return kind === 'signature' ? 'Signature' : kind === 'initials' ? 'Initials' : 'Stamp';\n}\n\n/** The catalog patch: library id, categories, locale. The name is `/Title`. */\nexport function stampLibraryPieceInfo(\n  id: string,\n  opts: { kind?: string; categories?: readonly string[]; locale?: string } = {},\n): PieceInfoPatch {\n  return {\n    Version: STAMP_PIECEINFO_VERSION,\n    Id: id,\n    Kind: { name: libraryKindToPdfName(opts.kind ?? DEFAULT_LIBRARY_KIND) },\n    // v2: the name is the PDF's /Title.\n    Name: null,\n    Categories: opts.categories ?? null,\n    Locale: opts.locale ?? null,\n  };\n}\n\n/** The page patch: kind, an explicit `/Subj` override, categories. */\nexport function stampPieceInfo(\n  kind: StampAssetKind,\n  opts: { subject?: string | null; categories?: readonly string[] } = {},\n): PieceInfoPatch {\n  return {\n    Version: STAMP_PIECEINFO_VERSION,\n    Kind: { name: stampKindToPdfName(kind) },\n    // v2: the identifier and label live in the /Names /Pages key; only an\n    // explicit /Subj override has no standard home. v1 `Name`/`Subject` keys\n    // are cleared so a re-imported v1 library cannot disagree with its registry.\n    Name: null,\n    Subject: null,\n    SubjectOverride: opts.subject ?? null,\n    Categories: opts.categories ?? null,\n  };\n}\n","import type { BinarySource, Engine } from '@embedpdf/engine-core/runtime';\nimport { createCapabilityToken, type EventHook } from '@embedpdf/core';\nimport type { AnnotationRef, PageObjectNumber } from '@embedpdf/engine-core/runtime';\nimport type { StampPlacement } from '@embedpdf/plugin-annotation/contract';\n\n/**\n * The stamp plugin: a workspace-scoped ASSET substrate.\n *\n * The design law (\"documents have a home; assets ride the wire\"): imported\n * PDF libraries retain one canonical PDF whose catalog/page `/PieceInfo`\n * carries their metadata. Per-asset PDFs and previews are derived caches used\n * for placement. Standalone PNG/JPEG assets remain loose because the engine\n * intentionally has no raster-to-PDF-page authoring primitive.\n */\n\nexport type StampAssetKind = 'stamp' | 'signature' | 'initials';\n\n/**\n * What a library file is FOR — the routing key a surface queries by. Open:\n * the plugin defines `stamps` (the default) and `signatures`; an embedder\n * may define its own (`toolbar`, `legal-seals`). Persisted in the file.\n */\nexport type StampLibraryKind = string;\n\nexport interface StampLibraryQuery {\n  /** One kind or several; omitted = every library. */\n  kind?: StampLibraryKind | readonly StampLibraryKind[];\n}\n\n/**\n * How a mark is authored: drawn strokes (kept as a vector path), typed text\n * in a registered font (embedded by the flatten), a raster image, or a page\n * of a PDF. Ink strokes are in points, y-up, any origin — the asset page is\n * the mark's bounds.\n */\nexport type MarkSource =\n  | {\n      kind: 'ink';\n      strokes: ReadonlyArray<ReadonlyArray<{ x: number; y: number }>>;\n      color?: string;\n      strokeWidth?: number;\n    }\n  | { kind: 'text'; text: string; fontFamily: string; color?: string; fontSize?: number }\n  | { kind: 'image'; source: BinarySource }\n  | { kind: 'pdf'; source: BinarySource; pageIndex?: number };\n\n/**\n * One asset's SERIALIZABLE descriptor. The bytes and the cached preview are\n * deliberately NOT here — the reducer state stays pure/serializable (kernel\n * rule 1); binary lives in the capability and crosses only as call\n * arguments/returns, mirroring the engine's own BinarySource rule.\n */\nexport interface StampAsset {\n  /** Derived and stable: `${libraryId}:${name}` (never allocated). */\n  id: string;\n  libraryId: string;\n  kind: StampAssetKind;\n  /**\n   * The stamp's IDENTIFIER — the text before the first `=` in its library\n   * key, and the placed annotation's `/Name`: a standard name (`Approved`)\n   * or a custom one (`#LBGiYhk8V_oAfmqAPENiwD`). Not display text.\n   */\n  name: string;\n  /** What the picker shows and the placed annotation's default `/Subj` —\n   *  the text after `=` in the library key (`Goedgekeurd`). */\n  label: string;\n  /** Intrinsic size in PDF points (the source page's crop box / image pixels 1:1). */\n  size: { width: number; height: number };\n  /** The library page that IS this asset. Every asset is a page: a raster\n   *  added to a library becomes a page carrying the image. */\n  pageObjectNumber: number;\n  /** An explicit `/Subj` override (PieceInfo); placements use `label` otherwise. */\n  subject?: string;\n  categories?: string[];\n}\n\n/**\n * A library IS a PDF: its `/Title` is the name, its `/Names /Pages` registry\n * the assets, its pages the artwork, PieceInfo only what has no standard\n * home. One imported PDF becomes one library; `exportLibrary` returns it.\n */\nexport interface StampLibrary {\n  /** PieceInfo `Id` — stable while the title is editable. */\n  id: string;\n  name: string;\n  /** PieceInfo `Kind`: `'stamps'`, `'signatures'`, or an embedder's own. */\n  kind: StampLibraryKind;\n  /** PieceInfo `Locale` — the language of the labels, when the library says. */\n  locale?: string;\n  categories?: string[];\n  /** Asset ids in display order. */\n  assetIds: string[];\n}\n\nexport interface StampState {\n  libraries: Record<string, StampLibrary>;\n  /** Library display order (insertion order). */\n  libraryOrder: string[];\n  assets: Record<string, StampAsset>;\n}\n\nexport type StampAction =\n  | { type: 'LIBRARY_ADDED'; library: StampLibrary }\n  | { type: 'LIBRARY_UPDATED'; library: StampLibrary }\n  | { type: 'LIBRARY_REMOVED'; libraryId: string }\n  | { type: 'ASSET_ADDED'; asset: StampAsset }\n  | { type: 'ASSET_UPDATED'; asset: StampAsset }\n  | { type: 'ASSET_REMOVED'; assetId: string };\n\n/** Why a library's canonical bytes changed — the persistence signal. */\nexport interface StampLibraryChange {\n  libraryId: string;\n  reason:\n    | 'created'\n    | 'imported'\n    | 'updated'\n    | 'asset-added'\n    | 'asset-updated'\n    | 'asset-removed'\n    | 'removed';\n}\n\nexport interface StampConfig {\n  /**\n   * The ASSET ENGINE port: any `Engine` that can open `{ kind: 'bytes' }` —\n   * used only to slice an imported library PDF into per-page assets and\n   * render their previews.\n   *\n   * Omitted → the kernel's own engine is used, which is exactly right for a\n   * local deployment (same WASM instance, zero extra cost). In a CLOUD\n   * deployment the kernel engine cannot open local bytes, so pass a factory —\n   * it is called (and memoized) on the first import, never at viewer boot:\n   *\n   * ```ts\n   * stampPlugin({\n   *   assetEngine: () => import('@embedpdf/engine').then((m) => m.createLocalEngine()),\n   * })\n   * ```\n   */\n  assetEngine?: Engine | (() => Engine | Promise<Engine>);\n  /** Cached thumbnail width in device px (import-time render). Default 256. */\n  previewWidth?: number;\n  /**\n   * Evaluate form-backed (dynamic) PDF stamp assets on arm. Default `true`.\n   * Scripting itself is the workspace's ONE JavaScript switch,\n   * `actionsPlugin({ javascript: { enabled } })`: stamp has no switch of its\n   * own — it asks the target document's actions plugin for a DETACHED realm\n   * (same identity, clock, sandbox, and budget; isolated globals), and arms\n   * the template unevaluated when scripting is off or actions is absent.\n   * `false` keeps templates static even with scripting on — a product\n   * choice (a stamp's appearance must equal the reviewed template), not a\n   * trust boundary: a detached realm can only alert and spend budget.\n   */\n  dynamic?: boolean;\n}\n\nexport interface ImportLibraryOptions {\n  /**\n   * FALLBACK library name, applied only when the PDF carries no `/Title`\n   * (an Acrobat-authored or previously exported library names itself).\n   * Default `'Stamps'`.\n   */\n  name?: string;\n  /** Library categories written to catalog `/PieceInfo`. */\n  categories?: string[];\n  /** Kind stamped onto every imported asset. Default `'stamp'`. */\n  kind?: StampAssetKind;\n  /** What the file is for; overrides what the file says (an Acrobat-authored set imported for a toolbar). */\n  libraryKind?: StampLibraryKind;\n  /**\n   * FALLBACK per-page labels for a plain PDF (no `/Names /Pages` registry):\n   * every page becomes a stamp named `Stamp<n>` with this label. Ignored\n   * when the PDF registers its stamps itself.\n   */\n  assetName?: (pageIndex: number) => string;\n}\n\nexport interface AddAssetInput {\n  /** Target library; omitted → a new single-asset library named after the asset. */\n  libraryId?: string;\n  /** The identifier (placed `/Name`). Omit to mint an Acrobat-style `#…` one. */\n  name?: string;\n  /** Picker text and default `/Subj`. Defaults to `name`. */\n  label?: string;\n  kind?: StampAssetKind;\n  subject?: string;\n  categories?: string[];\n  /**\n   * Single-page PDF (vector) or PNG/JPEG bytes. A raster becomes a PAGE of\n   * the library sized to `size` (default: its pixels as points, 1:1) with the\n   * image flattened into it — so every asset is a page and every library a\n   * complete PDF.\n   */\n  /** PNG, JPEG, or single-page PDF bytes. Exactly one of `source` / `mark`. */\n  source?: BinarySource;\n  /** An authored mark — drawn, typed, an image, or a PDF page. Exactly one of `source` / `mark`. */\n  mark?: MarkSource;\n  /** Thumbnail override for pickers (PNG/JPEG); rendered from the page otherwise. */\n  preview?: BinarySource;\n  /** Page size in PDF points for a RASTER source. Ignored for PDF sources (the page has one). */\n  size?: { width: number; height: number };\n}\n\n/** A cached, browser-paintable render of an asset (PNG from import; raster assets as-is). */\nexport interface StampAssetPreview {\n  bytes: Uint8Array;\n  mimeType: string;\n}\n\nexport interface StampCapability {\n  // ── selectors (pure reads over serializable state) ──\n  libraries(query?: StampLibraryQuery): StampLibrary[];\n  library(id: string): StampLibrary | null;\n  /** Assets of one library, in library order — or every asset when omitted. */\n  assets(libraryId?: string): StampAsset[];\n  asset(id: string): StampAsset | null;\n  // ── binary reads (capability-held, never store state) ──\n  /** The asset's paintable preview, or null while none is cached. */\n  assetPreview(id: string): StampAssetPreview | null;\n  /** Placement bytes; derived from the canonical page for PDF-backed libraries. */\n  assetBytes(id: string): Uint8Array | null;\n  // ── library intents ──\n  /**\n   * A new, empty library: a PDF with the given title and no registered\n   * stamps yet (like Acrobat, it carries one unregistered blank page so it\n   * is a valid file from the start). Resolves to the library id; feed it to\n   * `addAsset({ libraryId })` to fill it.\n   */\n  createLibrary(\n    name: string,\n    opts?: { id?: string; kind?: StampLibraryKind; categories?: string[] },\n  ): Promise<string>;\n  /** Rename (the PDF's `/Title`) or re-categorise a library. */\n  updateLibrary(id: string, patch: { name?: string; categories?: string[] }): Promise<void>;\n  /**\n   * Import a PDF as a stamp library: every page becomes one vector asset\n   * (single-page PDF bytes + a cached preview render). Uses the asset\n   * engine; in a cloud deployment without one configured this rejects with\n   * an actionable error. Resolves to the new library id.\n   */\n  importLibraryPdf(source: BinarySource, opts?: ImportLibraryOptions): Promise<string>;\n  /**\n   * Add a single asset as a page of its library (a raster is flattened into\n   * a fresh page first) and register it under `identifier=label`. Without\n   * `libraryId`, a new library named after the label is created for it.\n   */\n  addAsset(input: AddAssetInput): Promise<string>;\n  /**\n   * Turn selected annotations of an open document into an asset: their\n   * appearances are exported by the engine as ONE single-page PDF sized to\n   * their union rect (vector, positions preserved — exactly what the page\n   * shows) and added like any PDF asset. The identifier defaults to an\n   * Acrobat-style `#…` one so the stamp keeps its identity in Acrobat.\n   * Rejects when any ref is not on `pageObjectNumber`, is hidden, or has no\n   * appearance (all-or-nothing: a stamp missing a part is worse than an error).\n   */\n  addAssetFromAnnotations(\n    documentId: string,\n    pageObjectNumber: PageObjectNumber,\n    refs: AnnotationRef[],\n    input: Omit<AddAssetInput, 'source' | 'size'>,\n  ): Promise<string>;\n  /** Remove an asset, deleting its canonical page before state changes when PDF-backed. */\n  removeAsset(id: string): Promise<void>;\n  /** Remove a library and every asset in it, ordered with in-flight library mutations. */\n  removeLibrary(id: string): Promise<void>;\n  /**\n   * Relabel an asset (the registry key is renamed in one job), set or clear\n   * its `/Subj` override, or replace its categories. The identifier never\n   * changes — it is the asset's identity and every placed stamp's `/Name`.\n   */\n  updateAsset(\n    id: string,\n    patch: { label?: string; subject?: string | null; categories?: string[] },\n  ): Promise<void>;\n  /**\n   * The library as a PDF — its title, its named pages, its artwork: the\n   * complete, Acrobat-readable file. This IS the persistence format: store\n   * these bytes wherever you like and `importLibraryPdf` them back.\n   */\n  exportLibrary(id: string): Uint8Array | null;\n  /** Fires after every change to a library's canonical bytes — subscribe to persist. */\n  onLibraryChanged: EventHook<StampLibraryChange>;\n  // ── placement (delegates to the annotation plugin of the named document) ──\n  /**\n   * Arm an asset on a document: the next click on that document's pages\n   * places it (and the hover ghost previews the exact placement). With\n   * scripting on (the actions plugin's `javascript` switch), form-backed\n   * PDFs are evaluated against that target document in a detached realm and\n   * flattened first. Rides `annotation.armStamp` — bytes,\n   * preview, and intrinsic size all travel along, so vector stamps keep\n   * their true aspect.\n   */\n  armAsset(documentId: string, assetId: string, opts?: { targetWidth?: number }): Promise<void>;\n  /**\n   * Place an asset WITHOUT the pointer: the same materialization, name,\n   * subject, fit, and page clamp a click after `armAsset` would produce —\n   * one placement law, two entry points. Resolves to the new annotation.\n   */\n  placeAsset(\n    documentId: string,\n    assetId: string,\n    placement: StampPlacement,\n  ): Promise<AnnotationRef>;\n  /** Disarm the stamp tool on a document. */\n  disarm(documentId: string): void;\n  /** The asset armed on a document through {@link armAsset}, while the annotation plugin still holds it. */\n  armedAsset(documentId: string): StampAsset | null;\n}\n\nexport const StampToken = createCapabilityToken<StampCapability>('stamp');\n"],"mappings":";;AAsBA,SAAgB,cAAc,KAAuB;CACnD,MAAM,YAAY,IAAI,QAAQ,GAAG;CACjC,IAAI,YAAY,GAAG,OAAO;EAAE,MAAM;EAAK,OAAO;CAAI;CAClD,OAAO;EAAE,MAAM,IAAI,MAAM,GAAG,SAAS;EAAG,OAAO,IAAI,MAAM,YAAY,CAAC;CAAE;AAC1E;AAEA,SAAgB,SAAS,MAAc,OAAuB;CAC5D,OAAO,GAAG,KAAK,GAAG;AACpB;AAEA,MAAM,SAAS;;;;;;AAOf,SAAgB,gBAAgB,SAAuB,KAAK,QAAgB;CAC1E,IAAI,MAAM;CACV,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,KAAK,OAAO,OAAO,KAAK,MAAM,OAAO,IAAI,EAAa;CAC9E,OAAO;AACT;;AAGA,SAAgB,WAAW,WAAmB,MAAsB;CAClE,OAAO,GAAG,UAAU,GAAG;AACzB;;AAYA,MAAa,8BAA8B;;AAE3C,MAAa,sBAAsB;;AAEnC,MAAa,0BAA0B;;AAGvC,MAAa,uBAAuB;;AAGpC,SAAgB,qBAAqB,MAAsB;CACzD,OAAO,SAAS,WAAW,iBAAiB,SAAS,eAAe,qBAAqB;AAC3F;AAEA,SAAgB,uBAAuB,MAAkC;CACvE,IAAI,CAAC,QAAQ,SAAS,gBAAgB,OAAO;CAC7C,OAAO,SAAS,qBAAqB,eAAe;AACtD;AAEA,SAAgB,mBAAmB,MAA8B;CAC/D,OAAO,SAAS,cAAc,cAAc,SAAS,aAAa,aAAa;AACjF;;AAGA,SAAgB,sBACd,IACA,OAA2E,CAAC,GAC5D;CAChB,OAAO;EACL,SAAA;EACA,IAAI;EACJ,MAAM,EAAE,MAAM,qBAAqB,KAAK,QAAA,QAA4B,EAAE;EAEtE,MAAM;EACN,YAAY,KAAK,cAAc;EAC/B,QAAQ,KAAK,UAAU;CACzB;AACF;;AAGA,SAAgB,eACd,MACA,OAAoE,CAAC,GACrD;CAChB,OAAO;EACL,SAAA;EACA,MAAM,EAAE,MAAM,mBAAmB,IAAI,EAAE;EAIvC,MAAM;EACN,SAAS;EACT,iBAAiB,KAAK,WAAW;EACjC,YAAY,KAAK,cAAc;CACjC;AACF;;;ACmMA,MAAa,cAAA,GAAA,eAAA,sBAAA,CAAoD,OAAO"}

package/dist/contract-VuCLK5Sr.d.ts

@@ -0,0 +1,384 @@
+import { EventHook } from "@embedpdf/core";
+import { AnnotationRef, BinarySource, Engine, PageObjectNumber, PieceInfoPatch } from "@embedpdf/engine-core/runtime";
+import { StampPlacement } from "@embedpdf/plugin-annotation/contract";
+//#region src/types.d.ts
+/**
+ * The stamp plugin: a workspace-scoped ASSET substrate.
+ *
+ * The design law ("documents have a home; assets ride the wire"): imported
+ * PDF libraries retain one canonical PDF whose catalog/page `/PieceInfo`
+ * carries their metadata. Per-asset PDFs and previews are derived caches used
+ * for placement. Standalone PNG/JPEG assets remain loose because the engine
+ * intentionally has no raster-to-PDF-page authoring primitive.
+ */
+type StampAssetKind = 'stamp' | 'signature' | 'initials';
+/**
+ * What a library file is FOR — the routing key a surface queries by. Open:
+ * the plugin defines `stamps` (the default) and `signatures`; an embedder
+ * may define its own (`toolbar`, `legal-seals`). Persisted in the file.
+ */
+type StampLibraryKind = string;
+interface StampLibraryQuery {
+  /** One kind or several; omitted = every library. */
+  kind?: StampLibraryKind | readonly StampLibraryKind[];
+}
+/**
+ * How a mark is authored: drawn strokes (kept as a vector path), typed text
+ * in a registered font (embedded by the flatten), a raster image, or a page
+ * of a PDF. Ink strokes are in points, y-up, any origin — the asset page is
+ * the mark's bounds.
+ */
+type MarkSource = {
+  kind: 'ink';
+  strokes: ReadonlyArray<ReadonlyArray<{
+    x: number;
+    y: number;
+  }>>;
+  color?: string;
+  strokeWidth?: number;
+} | {
+  kind: 'text';
+  text: string;
+  fontFamily: string;
+  color?: string;
+  fontSize?: number;
+} | {
+  kind: 'image';
+  source: BinarySource;
+} | {
+  kind: 'pdf';
+  source: BinarySource;
+  pageIndex?: number;
+};
+/**
+ * One asset's SERIALIZABLE descriptor. The bytes and the cached preview are
+ * deliberately NOT here — the reducer state stays pure/serializable (kernel
+ * rule 1); binary lives in the capability and crosses only as call
+ * arguments/returns, mirroring the engine's own BinarySource rule.
+ */
+interface StampAsset {
+  /** Derived and stable: `${libraryId}:${name}` (never allocated). */
+  id: string;
+  libraryId: string;
+  kind: StampAssetKind;
+  /**
+   * The stamp's IDENTIFIER — the text before the first `=` in its library
+   * key, and the placed annotation's `/Name`: a standard name (`Approved`)
+   * or a custom one (`#LBGiYhk8V_oAfmqAPENiwD`). Not display text.
+   */
+  name: string;
+  /** What the picker shows and the placed annotation's default `/Subj` —
+   *  the text after `=` in the library key (`Goedgekeurd`). */
+  label: string;
+  /** Intrinsic size in PDF points (the source page's crop box / image pixels 1:1). */
+  size: {
+    width: number;
+    height: number;
+  };
+  /** The library page that IS this asset. Every asset is a page: a raster
+   *  added to a library becomes a page carrying the image. */
+  pageObjectNumber: number;
+  /** An explicit `/Subj` override (PieceInfo); placements use `label` otherwise. */
+  subject?: string;
+  categories?: string[];
+}
+/**
+ * A library IS a PDF: its `/Title` is the name, its `/Names /Pages` registry
+ * the assets, its pages the artwork, PieceInfo only what has no standard
+ * home. One imported PDF becomes one library; `exportLibrary` returns it.
+ */
+interface StampLibrary {
+  /** PieceInfo `Id` — stable while the title is editable. */
+  id: string;
+  name: string;
+  /** PieceInfo `Kind`: `'stamps'`, `'signatures'`, or an embedder's own. */
+  kind: StampLibraryKind;
+  /** PieceInfo `Locale` — the language of the labels, when the library says. */
+  locale?: string;
+  categories?: string[];
+  /** Asset ids in display order. */
+  assetIds: string[];
+}
+interface StampState {
+  libraries: Record<string, StampLibrary>;
+  /** Library display order (insertion order). */
+  libraryOrder: string[];
+  assets: Record<string, StampAsset>;
+}
+type StampAction = {
+  type: 'LIBRARY_ADDED';
+  library: StampLibrary;
+} | {
+  type: 'LIBRARY_UPDATED';
+  library: StampLibrary;
+} | {
+  type: 'LIBRARY_REMOVED';
+  libraryId: string;
+} | {
+  type: 'ASSET_ADDED';
+  asset: StampAsset;
+} | {
+  type: 'ASSET_UPDATED';
+  asset: StampAsset;
+} | {
+  type: 'ASSET_REMOVED';
+  assetId: string;
+};
+/** Why a library's canonical bytes changed — the persistence signal. */
+interface StampLibraryChange {
+  libraryId: string;
+  reason: 'created' | 'imported' | 'updated' | 'asset-added' | 'asset-updated' | 'asset-removed' | 'removed';
+}
+interface StampConfig {
+  /**
+   * The ASSET ENGINE port: any `Engine` that can open `{ kind: 'bytes' }` —
+   * used only to slice an imported library PDF into per-page assets and
+   * render their previews.
+   *
+   * Omitted → the kernel's own engine is used, which is exactly right for a
+   * local deployment (same WASM instance, zero extra cost). In a CLOUD
+   * deployment the kernel engine cannot open local bytes, so pass a factory —
+   * it is called (and memoized) on the first import, never at viewer boot:
+   *
+   * ```ts
+   * stampPlugin({
+   *   assetEngine: () => import('@embedpdf/engine').then((m) => m.createLocalEngine()),
+   * })
+   * ```
+   */
+  assetEngine?: Engine | (() => Engine | Promise<Engine>);
+  /** Cached thumbnail width in device px (import-time render). Default 256. */
+  previewWidth?: number;
+  /**
+   * Evaluate form-backed (dynamic) PDF stamp assets on arm. Default `true`.
+   * Scripting itself is the workspace's ONE JavaScript switch,
+   * `actionsPlugin({ javascript: { enabled } })`: stamp has no switch of its
+   * own — it asks the target document's actions plugin for a DETACHED realm
+   * (same identity, clock, sandbox, and budget; isolated globals), and arms
+   * the template unevaluated when scripting is off or actions is absent.
+   * `false` keeps templates static even with scripting on — a product
+   * choice (a stamp's appearance must equal the reviewed template), not a
+   * trust boundary: a detached realm can only alert and spend budget.
+   */
+  dynamic?: boolean;
+}
+interface ImportLibraryOptions {
+  /**
+   * FALLBACK library name, applied only when the PDF carries no `/Title`
+   * (an Acrobat-authored or previously exported library names itself).
+   * Default `'Stamps'`.
+   */
+  name?: string;
+  /** Library categories written to catalog `/PieceInfo`. */
+  categories?: string[];
+  /** Kind stamped onto every imported asset. Default `'stamp'`. */
+  kind?: StampAssetKind;
+  /** What the file is for; overrides what the file says (an Acrobat-authored set imported for a toolbar). */
+  libraryKind?: StampLibraryKind;
+  /**
+   * FALLBACK per-page labels for a plain PDF (no `/Names /Pages` registry):
+   * every page becomes a stamp named `Stamp<n>` with this label. Ignored
+   * when the PDF registers its stamps itself.
+   */
+  assetName?: (pageIndex: number) => string;
+}
+interface AddAssetInput {
+  /** Target library; omitted → a new single-asset library named after the asset. */
+  libraryId?: string;
+  /** The identifier (placed `/Name`). Omit to mint an Acrobat-style `#…` one. */
+  name?: string;
+  /** Picker text and default `/Subj`. Defaults to `name`. */
+  label?: string;
+  kind?: StampAssetKind;
+  subject?: string;
+  categories?: string[];
+  /**
+   * Single-page PDF (vector) or PNG/JPEG bytes. A raster becomes a PAGE of
+   * the library sized to `size` (default: its pixels as points, 1:1) with the
+   * image flattened into it — so every asset is a page and every library a
+   * complete PDF.
+   */
+  /** PNG, JPEG, or single-page PDF bytes. Exactly one of `source` / `mark`. */
+  source?: BinarySource;
+  /** An authored mark — drawn, typed, an image, or a PDF page. Exactly one of `source` / `mark`. */
+  mark?: MarkSource;
+  /** Thumbnail override for pickers (PNG/JPEG); rendered from the page otherwise. */
+  preview?: BinarySource;
+  /** Page size in PDF points for a RASTER source. Ignored for PDF sources (the page has one). */
+  size?: {
+    width: number;
+    height: number;
+  };
+}
+/** A cached, browser-paintable render of an asset (PNG from import; raster assets as-is). */
+interface StampAssetPreview {
+  bytes: Uint8Array;
+  mimeType: string;
+}
+interface StampCapability {
+  libraries(query?: StampLibraryQuery): StampLibrary[];
+  library(id: string): StampLibrary | null;
+  /** Assets of one library, in library order — or every asset when omitted. */
+  assets(libraryId?: string): StampAsset[];
+  asset(id: string): StampAsset | null;
+  /** The asset's paintable preview, or null while none is cached. */
+  assetPreview(id: string): StampAssetPreview | null;
+  /** Placement bytes; derived from the canonical page for PDF-backed libraries. */
+  assetBytes(id: string): Uint8Array | null;
+  /**
+   * A new, empty library: a PDF with the given title and no registered
+   * stamps yet (like Acrobat, it carries one unregistered blank page so it
+   * is a valid file from the start). Resolves to the library id; feed it to
+   * `addAsset({ libraryId })` to fill it.
+   */
+  createLibrary(name: string, opts?: {
+    id?: string;
+    kind?: StampLibraryKind;
+    categories?: string[];
+  }): Promise<string>;
+  /** Rename (the PDF's `/Title`) or re-categorise a library. */
+  updateLibrary(id: string, patch: {
+    name?: string;
+    categories?: string[];
+  }): Promise<void>;
+  /**
+   * Import a PDF as a stamp library: every page becomes one vector asset
+   * (single-page PDF bytes + a cached preview render). Uses the asset
+   * engine; in a cloud deployment without one configured this rejects with
+   * an actionable error. Resolves to the new library id.
+   */
+  importLibraryPdf(source: BinarySource, opts?: ImportLibraryOptions): Promise<string>;
+  /**
+   * Add a single asset as a page of its library (a raster is flattened into
+   * a fresh page first) and register it under `identifier=label`. Without
+   * `libraryId`, a new library named after the label is created for it.
+   */
+  addAsset(input: AddAssetInput): Promise<string>;
+  /**
+   * Turn selected annotations of an open document into an asset: their
+   * appearances are exported by the engine as ONE single-page PDF sized to
+   * their union rect (vector, positions preserved — exactly what the page
+   * shows) and added like any PDF asset. The identifier defaults to an
+   * Acrobat-style `#…` one so the stamp keeps its identity in Acrobat.
+   * Rejects when any ref is not on `pageObjectNumber`, is hidden, or has no
+   * appearance (all-or-nothing: a stamp missing a part is worse than an error).
+   */
+  addAssetFromAnnotations(documentId: string, pageObjectNumber: PageObjectNumber, refs: AnnotationRef[], input: Omit<AddAssetInput, 'source' | 'size'>): Promise<string>;
+  /** Remove an asset, deleting its canonical page before state changes when PDF-backed. */
+  removeAsset(id: string): Promise<void>;
+  /** Remove a library and every asset in it, ordered with in-flight library mutations. */
+  removeLibrary(id: string): Promise<void>;
+  /**
+   * Relabel an asset (the registry key is renamed in one job), set or clear
+   * its `/Subj` override, or replace its categories. The identifier never
+   * changes — it is the asset's identity and every placed stamp's `/Name`.
+   */
+  updateAsset(id: string, patch: {
+    label?: string;
+    subject?: string | null;
+    categories?: string[];
+  }): Promise<void>;
+  /**
+   * The library as a PDF — its title, its named pages, its artwork: the
+   * complete, Acrobat-readable file. This IS the persistence format: store
+   * these bytes wherever you like and `importLibraryPdf` them back.
+   */
+  exportLibrary(id: string): Uint8Array | null;
+  /** Fires after every change to a library's canonical bytes — subscribe to persist. */
+  onLibraryChanged: EventHook<StampLibraryChange>;
+  /**
+   * Arm an asset on a document: the next click on that document's pages
+   * places it (and the hover ghost previews the exact placement). With
+   * scripting on (the actions plugin's `javascript` switch), form-backed
+   * PDFs are evaluated against that target document in a detached realm and
+   * flattened first. Rides `annotation.armStamp` — bytes,
+   * preview, and intrinsic size all travel along, so vector stamps keep
+   * their true aspect.
+   */
+  armAsset(documentId: string, assetId: string, opts?: {
+    targetWidth?: number;
+  }): Promise<void>;
+  /**
+   * Place an asset WITHOUT the pointer: the same materialization, name,
+   * subject, fit, and page clamp a click after `armAsset` would produce —
+   * one placement law, two entry points. Resolves to the new annotation.
+   */
+  placeAsset(documentId: string, assetId: string, placement: StampPlacement): Promise<AnnotationRef>;
+  /** Disarm the stamp tool on a document. */
+  disarm(documentId: string): void;
+  /** The asset armed on a document through {@link armAsset}, while the annotation plugin still holds it. */
+  armedAsset(documentId: string): StampAsset | null;
+}
+declare const StampToken: import("@embedpdf/core").CapabilityToken<StampCapability>;
+//#endregion
+//#region src/convention.d.ts
+interface StampKey {
+  name: string;
+  label: string;
+}
+declare function parseStampKey(key: string): StampKey;
+declare function stampKey(name: string, label: string): string;
+/**
+ * A fresh identifier for a stamp authored here, in Acrobat's own shape
+ * (`#` + 22 base-62 characters) so a stamp created in this viewer keeps its
+ * identity when the library is opened and placed in Acrobat.
+ */
+declare function customStampName(random?: () => number): string;
+/** Asset ids are derived, not allocated: library id + identifier. */
+declare function assetIdFor(libraryId: string, name: string): string;
+/** Catalog `/PieceInfo` application name for library-level data. */
+declare const STAMP_LIBRARY_PIECEINFO_APP = "EMBD_StampLibrary";
+/** Page `/PieceInfo` application name for per-stamp data. */
+declare const STAMP_PIECEINFO_APP = "EMBD_Stamp";
+/** The `Version` both dictionaries carry. */
+declare const STAMP_PIECEINFO_VERSION = 2;
+/** The library kind every file has unless it says otherwise. */
+declare const DEFAULT_LIBRARY_KIND = "stamps";
+/** `/Kind` names: the two the plugin defines keep their PDF spellings; others are written as given. */
+declare function libraryKindToPdfName(kind: string): string;
+declare function libraryKindFromPdfName(name: string | undefined): string;
+declare function stampKindToPdfName(kind: StampAssetKind): string;
+/** The catalog patch: library id, categories, locale. The name is `/Title`. */
+declare function stampLibraryPieceInfo(id: string, opts?: {
+  kind?: string;
+  categories?: readonly string[];
+  locale?: string;
+}): PieceInfoPatch;
+/** The page patch: kind, an explicit `/Subj` override, categories. */
+declare function stampPieceInfo(kind: StampAssetKind, opts?: {
+  subject?: string | null;
+  categories?: readonly string[];
+}): PieceInfoPatch;
+//#endregion
+//#region src/persistence.d.ts
+/** The persistence port: bytes by library id. */
+interface StampLibraryStore {
+  list(): Promise<Array<{
+    id: string;
+    bytes: Uint8Array;
+  }>>;
+  put(id: string, bytes: Uint8Array): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+/** An in-memory store — tests and SSR. */
+declare function memoryStampStore(): StampLibraryStore;
+/**
+ * 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.
+ */
+declare function restoreStampLibraries(stamp: StampCapability, store: StampLibraryStore): Promise<string[]>;
+/**
+ * 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.
+ */
+declare function persistStampLibraries(stamp: StampCapability, store: StampLibraryStore, opts?: {
+  except?: readonly string[];
+  debounceMs?: number;
+}): () => void;
+//#endregion
+export { StampLibraryKind as A, StampAsset as C, StampConfig as D, StampCapability as E, StampState as M, StampToken as N, StampLibrary as O, StampAction as S, StampAssetPreview as T, stampLibraryPieceInfo as _, DEFAULT_LIBRARY_KIND as a, ImportLibraryOptions as b, STAMP_PIECEINFO_VERSION as c, customStampName as d, libraryKindFromPdfName as f, stampKindToPdfName as g, stampKey as h, restoreStampLibraries as i, StampLibraryQuery as j, StampLibraryChange as k, StampKey as l, parseStampKey as m, memoryStampStore as n, STAMP_LIBRARY_PIECEINFO_APP as o, libraryKindToPdfName as p, persistStampLibraries as r, STAMP_PIECEINFO_APP as s, StampLibraryStore as t, assetIdFor as u, stampPieceInfo as v, StampAssetKind as w, MarkSource as x, AddAssetInput as y };
+//# sourceMappingURL=contract-VuCLK5Sr.d.ts.map

package/dist/contract.cjs

@@ -1,3 +1,16 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-DmQ4peF2.cjs");
+const require_contract = require("./contract-T-v5KaYd.cjs");
+exports.DEFAULT_LIBRARY_KIND = require_contract.DEFAULT_LIBRARY_KIND;
+exports.STAMP_LIBRARY_PIECEINFO_APP = require_contract.STAMP_LIBRARY_PIECEINFO_APP;
+exports.STAMP_PIECEINFO_APP = require_contract.STAMP_PIECEINFO_APP;
+exports.STAMP_PIECEINFO_VERSION = require_contract.STAMP_PIECEINFO_VERSION;
 exports.StampToken = require_contract.StampToken;
+exports.assetIdFor = require_contract.assetIdFor;
+exports.customStampName = require_contract.customStampName;
+exports.libraryKindFromPdfName = require_contract.libraryKindFromPdfName;
+exports.libraryKindToPdfName = require_contract.libraryKindToPdfName;
+exports.parseStampKey = require_contract.parseStampKey;
+exports.stampKey = require_contract.stampKey;
+exports.stampKindToPdfName = require_contract.stampKindToPdfName;
+exports.stampLibraryPieceInfo = require_contract.stampLibraryPieceInfo;
+exports.stampPieceInfo = require_contract.stampPieceInfo;

package/dist/contract.d.cts

@@ -1,2 +1,2 @@
-import { a as StampAssetKind, c as StampConfig, d as StampToken, i as StampAsset, l as StampLibrary, n as ImportLibraryOptions, o as StampAssetPreview, s as StampCapability, t as AddAssetInput, u as StampState } from "./contract-BaN6-ypU.cjs";
-export { type AddAssetInput, type ImportLibraryOptions, type StampAsset, type StampAssetKind, type StampAssetPreview, type StampCapability, type StampConfig, type StampLibrary, type StampState, StampToken };
+import { A as StampLibraryKind, C as StampAsset, D as StampConfig, E as StampCapability, M as StampState, N as StampToken, O as StampLibrary, T as StampAssetPreview, _ as stampLibraryPieceInfo, a as DEFAULT_LIBRARY_KIND, b as ImportLibraryOptions, c as STAMP_PIECEINFO_VERSION, d as customStampName, f as libraryKindFromPdfName, g as stampKindToPdfName, h as stampKey, j as StampLibraryQuery, k as StampLibraryChange, l as StampKey, m as parseStampKey, o as STAMP_LIBRARY_PIECEINFO_APP, p as libraryKindToPdfName, s as STAMP_PIECEINFO_APP, t as StampLibraryStore, u as assetIdFor, v as stampPieceInfo, w as StampAssetKind, x as MarkSource, y as AddAssetInput } from "./contract-BS3m51Au.cjs";
+export { type AddAssetInput, DEFAULT_LIBRARY_KIND, type ImportLibraryOptions, type MarkSource, STAMP_LIBRARY_PIECEINFO_APP, STAMP_PIECEINFO_APP, STAMP_PIECEINFO_VERSION, type StampAsset, type StampAssetKind, type StampAssetPreview, type StampCapability, type StampConfig, type StampKey, type StampLibrary, type StampLibraryChange, type StampLibraryKind, type StampLibraryQuery, type StampLibraryStore, type StampState, StampToken, assetIdFor, customStampName, libraryKindFromPdfName, libraryKindToPdfName, parseStampKey, stampKey, stampKindToPdfName, stampLibraryPieceInfo, stampPieceInfo };

package/dist/contract.d.ts

@@ -1,2 +1,2 @@
-import { a as StampAssetKind, c as StampConfig, d as StampToken, i as StampAsset, l as StampLibrary, n as ImportLibraryOptions, o as StampAssetPreview, s as StampCapability, t as AddAssetInput, u as StampState } from "./contract-BaN6-ypU.js";
-export { type AddAssetInput, type ImportLibraryOptions, type StampAsset, type StampAssetKind, type StampAssetPreview, type StampCapability, type StampConfig, type StampLibrary, type StampState, StampToken };
+import { A as StampLibraryKind, C as StampAsset, D as StampConfig, E as StampCapability, M as StampState, N as StampToken, O as StampLibrary, T as StampAssetPreview, _ as stampLibraryPieceInfo, a as DEFAULT_LIBRARY_KIND, b as ImportLibraryOptions, c as STAMP_PIECEINFO_VERSION, d as customStampName, f as libraryKindFromPdfName, g as stampKindToPdfName, h as stampKey, j as StampLibraryQuery, k as StampLibraryChange, l as StampKey, m as parseStampKey, o as STAMP_LIBRARY_PIECEINFO_APP, p as libraryKindToPdfName, s as STAMP_PIECEINFO_APP, t as StampLibraryStore, u as assetIdFor, v as stampPieceInfo, w as StampAssetKind, x as MarkSource, y as AddAssetInput } from "./contract-VuCLK5Sr.js";
+export { type AddAssetInput, DEFAULT_LIBRARY_KIND, type ImportLibraryOptions, type MarkSource, STAMP_LIBRARY_PIECEINFO_APP, STAMP_PIECEINFO_APP, STAMP_PIECEINFO_VERSION, type StampAsset, type StampAssetKind, type StampAssetPreview, type StampCapability, type StampConfig, type StampKey, type StampLibrary, type StampLibraryChange, type StampLibraryKind, type StampLibraryQuery, type StampLibraryStore, type StampState, StampToken, assetIdFor, customStampName, libraryKindFromPdfName, libraryKindToPdfName, parseStampKey, stampKey, stampKindToPdfName, stampLibraryPieceInfo, stampPieceInfo };

package/dist/contract.js

@@ -1,2 +1,2 @@
-import { t as StampToken } from "./contract-CkPaVNAJ.js";
-export { StampToken };
+import { a as STAMP_PIECEINFO_VERSION, c as libraryKindFromPdfName, d as stampKey, f as stampKindToPdfName, i as STAMP_PIECEINFO_APP, l as libraryKindToPdfName, m as stampPieceInfo, n as DEFAULT_LIBRARY_KIND, o as assetIdFor, p as stampLibraryPieceInfo, r as STAMP_LIBRARY_PIECEINFO_APP, s as customStampName, t as StampToken, u as parseStampKey } from "./contract-B79Onij2.js";
+export { DEFAULT_LIBRARY_KIND, STAMP_LIBRARY_PIECEINFO_APP, STAMP_PIECEINFO_APP, STAMP_PIECEINFO_VERSION, StampToken, assetIdFor, customStampName, libraryKindFromPdfName, libraryKindToPdfName, parseStampKey, stampKey, stampKindToPdfName, stampLibraryPieceInfo, stampPieceInfo };