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

package/dist/contract-BaN6-ypU.d.cts

@@ -0,0 +1,190 @@
+import { BinarySource, Engine } from "@embedpdf/engine-core/runtime";
+import { ScriptDiagnostic, ScriptExecutionError, ScriptUiEffect } from "@embedpdf/core-acrojs";
+import { FormScriptingOptions } from "@embedpdf/plugin-form/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';
+/**
+ * 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 {
+  id: string;
+  libraryId: string;
+  kind: StampAssetKind;
+  name: string;
+  /** Intrinsic size in PDF points (the source page's crop box / image pixels 1:1). */
+  size: {
+    width: number;
+    height: number;
+  };
+  /** What the asset bytes are: a single-page vector PDF, or a raster image. */
+  format: 'pdf' | 'png' | 'jpeg';
+  /** Canonical library page identity; present for PDF-backed libraries. */
+  pageObjectNumber?: number;
+  subject?: string;
+  categories?: string[];
+}
+/** A named group of assets — one imported PDF becomes one library. */
+interface StampLibrary {
+  id: string;
+  name: string;
+  /** PDF-backed libraries own canonical bytes; loose libraries are raster/pre-sliced conveniences. */
+  storage: 'canonical-pdf' | 'loose';
+  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_REMOVED';
+  libraryId: string;
+} | {
+  type: 'ASSET_ADDED';
+  asset: StampAsset;
+} | {
+  type: 'ASSET_REMOVED';
+  assetId: string;
+};
+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 preview width in device px (import-time render). Default 256. */
+  previewWidth?: number;
+  /**
+   * Opt-in Acrobat JavaScript evaluation for form-backed PDF stamp assets.
+   * On arm, the plugin recalculates a temporary copy using the target
+   * document's identity/name/clock, flattens it, and arms the resulting
+   * static page. Canonical library and derived base bytes stay unchanged.
+   */
+  scripting?: StampScriptingOptions;
+}
+/**
+ * Stamp evaluates dynamic assets in its OWN standalone realm (a detached
+ * stamp-asset document is never the viewer document's shared host), so the
+ * opt-in switch and the script observers live HERE — deliberately not on
+ * `actionsPlugin({ javascript })`, whose port serves the viewer document.
+ */
+interface StampScriptingOptions extends FormScriptingOptions {
+  /** Explicit opt-in for evaluating dynamic (form-backed) stamp assets. */
+  enabled: boolean;
+  onUiEffect?: (effect: ScriptUiEffect) => void;
+  onDiagnostic?: (diagnostic: ScriptDiagnostic) => void;
+  onError?: (error: ScriptExecutionError) => void;
+}
+interface ImportLibraryOptions {
+  /** Library display name. Default `'Stamps'`. */
+  name?: string;
+  /** Library categories written to catalog `/PieceInfo`. */
+  categories?: string[];
+  /** Kind stamped onto every imported asset. Default `'stamp'`. */
+  kind?: StampAssetKind;
+  /** Per-page asset names; default `Stamp <n>`. */
+  assetName?: (pageIndex: number) => string;
+}
+interface AddAssetInput {
+  /** Target library; omitted → a new single-asset library named after the asset. */
+  libraryId?: string;
+  name: string;
+  kind?: StampAssetKind;
+  subject?: string;
+  categories?: string[];
+  /** Single-page PDF (vector) or PNG/JPEG bytes. */
+  source: BinarySource;
+  /**
+   * Paintable preview for pickers + the hover ghost. Loose PDF assets cannot
+   * derive one without opening the PDF; canonical libraries render it after
+   * insertion. Raster sources default to their own bytes.
+   */
+  preview?: BinarySource;
+  /** Intrinsic size in PDF points. Required for PDF sources; rasters are sniffed. */
+  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(): 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;
+  /** Canonical library PDF bytes, or null for a loose library/unknown id. */
+  libraryBytes(id: string): Uint8Array | null;
+  /**
+   * 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. A PDF added to a canonical library is inserted as a
+   * page and receives `/PieceInfo`; loose assets keep their bytes directly.
+   * Raster input cannot be appended to a canonical PDF library.
+   */
+  addAsset(input: AddAssetInput): 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>;
+  /**
+   * 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 enabled, form-backed PDFs are evaluated against that target
+   * document 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>;
+  /** Disarm the stamp tool on a document. */
+  disarm(documentId: string): void;
+}
+declare const StampToken: import("@embedpdf/core").CapabilityToken<StampCapability>;
+//#endregion
+export { StampAssetKind as a, StampConfig as c, StampToken as d, StampAsset as i, StampLibrary as l, ImportLibraryOptions as n, StampAssetPreview as o, StampAction as r, StampCapability as s, AddAssetInput as t, StampState as u };
+//# sourceMappingURL=contract-BaN6-ypU.d.cts.map

package/dist/contract-BaN6-ypU.d.ts

@@ -0,0 +1,190 @@
+import { BinarySource, Engine } from "@embedpdf/engine-core/runtime";
+import { ScriptDiagnostic, ScriptExecutionError, ScriptUiEffect } from "@embedpdf/core-acrojs";
+import { FormScriptingOptions } from "@embedpdf/plugin-form/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';
+/**
+ * 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 {
+  id: string;
+  libraryId: string;
+  kind: StampAssetKind;
+  name: string;
+  /** Intrinsic size in PDF points (the source page's crop box / image pixels 1:1). */
+  size: {
+    width: number;
+    height: number;
+  };
+  /** What the asset bytes are: a single-page vector PDF, or a raster image. */
+  format: 'pdf' | 'png' | 'jpeg';
+  /** Canonical library page identity; present for PDF-backed libraries. */
+  pageObjectNumber?: number;
+  subject?: string;
+  categories?: string[];
+}
+/** A named group of assets — one imported PDF becomes one library. */
+interface StampLibrary {
+  id: string;
+  name: string;
+  /** PDF-backed libraries own canonical bytes; loose libraries are raster/pre-sliced conveniences. */
+  storage: 'canonical-pdf' | 'loose';
+  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_REMOVED';
+  libraryId: string;
+} | {
+  type: 'ASSET_ADDED';
+  asset: StampAsset;
+} | {
+  type: 'ASSET_REMOVED';
+  assetId: string;
+};
+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 preview width in device px (import-time render). Default 256. */
+  previewWidth?: number;
+  /**
+   * Opt-in Acrobat JavaScript evaluation for form-backed PDF stamp assets.
+   * On arm, the plugin recalculates a temporary copy using the target
+   * document's identity/name/clock, flattens it, and arms the resulting
+   * static page. Canonical library and derived base bytes stay unchanged.
+   */
+  scripting?: StampScriptingOptions;
+}
+/**
+ * Stamp evaluates dynamic assets in its OWN standalone realm (a detached
+ * stamp-asset document is never the viewer document's shared host), so the
+ * opt-in switch and the script observers live HERE — deliberately not on
+ * `actionsPlugin({ javascript })`, whose port serves the viewer document.
+ */
+interface StampScriptingOptions extends FormScriptingOptions {
+  /** Explicit opt-in for evaluating dynamic (form-backed) stamp assets. */
+  enabled: boolean;
+  onUiEffect?: (effect: ScriptUiEffect) => void;
+  onDiagnostic?: (diagnostic: ScriptDiagnostic) => void;
+  onError?: (error: ScriptExecutionError) => void;
+}
+interface ImportLibraryOptions {
+  /** Library display name. Default `'Stamps'`. */
+  name?: string;
+  /** Library categories written to catalog `/PieceInfo`. */
+  categories?: string[];
+  /** Kind stamped onto every imported asset. Default `'stamp'`. */
+  kind?: StampAssetKind;
+  /** Per-page asset names; default `Stamp <n>`. */
+  assetName?: (pageIndex: number) => string;
+}
+interface AddAssetInput {
+  /** Target library; omitted → a new single-asset library named after the asset. */
+  libraryId?: string;
+  name: string;
+  kind?: StampAssetKind;
+  subject?: string;
+  categories?: string[];
+  /** Single-page PDF (vector) or PNG/JPEG bytes. */
+  source: BinarySource;
+  /**
+   * Paintable preview for pickers + the hover ghost. Loose PDF assets cannot
+   * derive one without opening the PDF; canonical libraries render it after
+   * insertion. Raster sources default to their own bytes.
+   */
+  preview?: BinarySource;
+  /** Intrinsic size in PDF points. Required for PDF sources; rasters are sniffed. */
+  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(): 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;
+  /** Canonical library PDF bytes, or null for a loose library/unknown id. */
+  libraryBytes(id: string): Uint8Array | null;
+  /**
+   * 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. A PDF added to a canonical library is inserted as a
+   * page and receives `/PieceInfo`; loose assets keep their bytes directly.
+   * Raster input cannot be appended to a canonical PDF library.
+   */
+  addAsset(input: AddAssetInput): 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>;
+  /**
+   * 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 enabled, form-backed PDFs are evaluated against that target
+   * document 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>;
+  /** Disarm the stamp tool on a document. */
+  disarm(documentId: string): void;
+}
+declare const StampToken: import("@embedpdf/core").CapabilityToken<StampCapability>;
+//#endregion
+export { StampAssetKind as a, StampConfig as c, StampToken as d, StampAsset as i, StampLibrary as l, ImportLibraryOptions as n, StampAssetPreview as o, StampAction as r, StampCapability as s, AddAssetInput as t, StampState as u };
+//# sourceMappingURL=contract-BaN6-ypU.d.ts.map

package/dist/contract-CkPaVNAJ.js

@@ -0,0 +1,7 @@
+import { createCapabilityToken } from "@embedpdf/core";
+//#region src/types.ts
+const StampToken = createCapabilityToken("stamp");
+//#endregion
+export { StampToken as t };
+
+//# sourceMappingURL=contract-CkPaVNAJ.js.map

package/dist/contract-CkPaVNAJ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-CkPaVNAJ.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type { BinarySource, Engine } from '@embedpdf/engine-core/runtime';\nimport { createCapabilityToken } from '@embedpdf/core';\nimport type {\n  ScriptDiagnostic,\n  ScriptExecutionError,\n  ScriptUiEffect,\n} from '@embedpdf/core-acrojs';\nimport type { FormScriptingOptions } from '@embedpdf/plugin-form/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 * 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  id: string;\n  libraryId: string;\n  kind: StampAssetKind;\n  name: string;\n  /** Intrinsic size in PDF points (the source page's crop box / image pixels 1:1). */\n  size: { width: number; height: number };\n  /** What the asset bytes are: a single-page vector PDF, or a raster image. */\n  format: 'pdf' | 'png' | 'jpeg';\n  /** Canonical library page identity; present for PDF-backed libraries. */\n  pageObjectNumber?: number;\n  subject?: string;\n  categories?: string[];\n}\n\n/** A named group of assets — one imported PDF becomes one library. */\nexport interface StampLibrary {\n  id: string;\n  name: string;\n  /** PDF-backed libraries own canonical bytes; loose libraries are raster/pre-sliced conveniences. */\n  storage: 'canonical-pdf' | 'loose';\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_REMOVED'; libraryId: string }\n  | { type: 'ASSET_ADDED'; asset: StampAsset }\n  | { type: 'ASSET_REMOVED'; assetId: string };\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 preview width in device px (import-time render). Default 256. */\n  previewWidth?: number;\n  /**\n   * Opt-in Acrobat JavaScript evaluation for form-backed PDF stamp assets.\n   * On arm, the plugin recalculates a temporary copy using the target\n   * document's identity/name/clock, flattens it, and arms the resulting\n   * static page. Canonical library and derived base bytes stay unchanged.\n   */\n  scripting?: StampScriptingOptions;\n}\n\n/**\n * Stamp evaluates dynamic assets in its OWN standalone realm (a detached\n * stamp-asset document is never the viewer document's shared host), so the\n * opt-in switch and the script observers live HERE — deliberately not on\n * `actionsPlugin({ javascript })`, whose port serves the viewer document.\n */\nexport interface StampScriptingOptions extends FormScriptingOptions {\n  /** Explicit opt-in for evaluating dynamic (form-backed) stamp assets. */\n  enabled: boolean;\n  onUiEffect?: (effect: ScriptUiEffect) => void;\n  onDiagnostic?: (diagnostic: ScriptDiagnostic) => void;\n  onError?: (error: ScriptExecutionError) => void;\n}\n\nexport interface ImportLibraryOptions {\n  /** Library display name. Default `'Stamps'`. */\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  /** Per-page asset names; default `Stamp <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  name: string;\n  kind?: StampAssetKind;\n  subject?: string;\n  categories?: string[];\n  /** Single-page PDF (vector) or PNG/JPEG bytes. */\n  source: BinarySource;\n  /**\n   * Paintable preview for pickers + the hover ghost. Loose PDF assets cannot\n   * derive one without opening the PDF; canonical libraries render it after\n   * insertion. Raster sources default to their own bytes.\n   */\n  preview?: BinarySource;\n  /** Intrinsic size in PDF points. Required for PDF sources; rasters are sniffed. */\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(): 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  /** Canonical library PDF bytes, or null for a loose library/unknown id. */\n  libraryBytes(id: string): Uint8Array | null;\n  // ── library intents ──\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. A PDF added to a canonical library is inserted as a\n   * page and receives `/PieceInfo`; loose assets keep their bytes directly.\n   * Raster input cannot be appended to a canonical PDF library.\n   */\n  addAsset(input: AddAssetInput): 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  // ── 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 enabled, form-backed PDFs are evaluated against that target\n   * document and 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  /** Disarm the stamp tool on a document. */\n  disarm(documentId: string): void;\n}\n\nexport const StampToken = createCapabilityToken<StampCapability>('stamp');\n"],"mappings":";;AA+LA,MAAa,aAAa,sBAAuC,OAAO"}

package/dist/contract-DmQ4peF2.cjs

@@ -0,0 +1,11 @@
+//#region src/types.ts
+const StampToken = (0, require("@embedpdf/core").createCapabilityToken)("stamp");
+//#endregion
+Object.defineProperty(exports, "StampToken", {
+	enumerable: true,
+	get: function() {
+		return StampToken;
+	}
+});
+
+//# sourceMappingURL=contract-DmQ4peF2.cjs.map

package/dist/contract-DmQ4peF2.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-DmQ4peF2.cjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type { BinarySource, Engine } from '@embedpdf/engine-core/runtime';\nimport { createCapabilityToken } from '@embedpdf/core';\nimport type {\n  ScriptDiagnostic,\n  ScriptExecutionError,\n  ScriptUiEffect,\n} from '@embedpdf/core-acrojs';\nimport type { FormScriptingOptions } from '@embedpdf/plugin-form/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 * 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  id: string;\n  libraryId: string;\n  kind: StampAssetKind;\n  name: string;\n  /** Intrinsic size in PDF points (the source page's crop box / image pixels 1:1). */\n  size: { width: number; height: number };\n  /** What the asset bytes are: a single-page vector PDF, or a raster image. */\n  format: 'pdf' | 'png' | 'jpeg';\n  /** Canonical library page identity; present for PDF-backed libraries. */\n  pageObjectNumber?: number;\n  subject?: string;\n  categories?: string[];\n}\n\n/** A named group of assets — one imported PDF becomes one library. */\nexport interface StampLibrary {\n  id: string;\n  name: string;\n  /** PDF-backed libraries own canonical bytes; loose libraries are raster/pre-sliced conveniences. */\n  storage: 'canonical-pdf' | 'loose';\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_REMOVED'; libraryId: string }\n  | { type: 'ASSET_ADDED'; asset: StampAsset }\n  | { type: 'ASSET_REMOVED'; assetId: string };\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 preview width in device px (import-time render). Default 256. */\n  previewWidth?: number;\n  /**\n   * Opt-in Acrobat JavaScript evaluation for form-backed PDF stamp assets.\n   * On arm, the plugin recalculates a temporary copy using the target\n   * document's identity/name/clock, flattens it, and arms the resulting\n   * static page. Canonical library and derived base bytes stay unchanged.\n   */\n  scripting?: StampScriptingOptions;\n}\n\n/**\n * Stamp evaluates dynamic assets in its OWN standalone realm (a detached\n * stamp-asset document is never the viewer document's shared host), so the\n * opt-in switch and the script observers live HERE — deliberately not on\n * `actionsPlugin({ javascript })`, whose port serves the viewer document.\n */\nexport interface StampScriptingOptions extends FormScriptingOptions {\n  /** Explicit opt-in for evaluating dynamic (form-backed) stamp assets. */\n  enabled: boolean;\n  onUiEffect?: (effect: ScriptUiEffect) => void;\n  onDiagnostic?: (diagnostic: ScriptDiagnostic) => void;\n  onError?: (error: ScriptExecutionError) => void;\n}\n\nexport interface ImportLibraryOptions {\n  /** Library display name. Default `'Stamps'`. */\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  /** Per-page asset names; default `Stamp <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  name: string;\n  kind?: StampAssetKind;\n  subject?: string;\n  categories?: string[];\n  /** Single-page PDF (vector) or PNG/JPEG bytes. */\n  source: BinarySource;\n  /**\n   * Paintable preview for pickers + the hover ghost. Loose PDF assets cannot\n   * derive one without opening the PDF; canonical libraries render it after\n   * insertion. Raster sources default to their own bytes.\n   */\n  preview?: BinarySource;\n  /** Intrinsic size in PDF points. Required for PDF sources; rasters are sniffed. */\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(): 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  /** Canonical library PDF bytes, or null for a loose library/unknown id. */\n  libraryBytes(id: string): Uint8Array | null;\n  // ── library intents ──\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. A PDF added to a canonical library is inserted as a\n   * page and receives `/PieceInfo`; loose assets keep their bytes directly.\n   * Raster input cannot be appended to a canonical PDF library.\n   */\n  addAsset(input: AddAssetInput): 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  // ── 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 enabled, form-backed PDFs are evaluated against that target\n   * document and 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  /** Disarm the stamp tool on a document. */\n  disarm(documentId: string): void;\n}\n\nexport const StampToken = createCapabilityToken<StampCapability>('stamp');\n"],"mappings":";AA+LA,MAAa,cAAA,2BAAA,CAAA,CAAA,sBAAA,CAAoD,OAAO"}

package/dist/contract.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("./contract-DmQ4peF2.cjs");
+exports.StampToken = require_contract.StampToken;

package/dist/contract.d.cts

@@ -0,0 +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 };

package/dist/contract.d.ts

@@ -0,0 +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 };

package/dist/contract.js

@@ -0,0 +1,2 @@
+import { t as StampToken } from "./contract-CkPaVNAJ.js";
+export { StampToken };

package/dist/index.cjs

@@ -1,8 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("./contract-DmQ4peF2.cjs");
 let _embedpdf_core = require("@embedpdf/core");
 let _embedpdf_engine_core_runtime = require("@embedpdf/engine-core/runtime");
-let _embedpdf_plugin_annotation = require("@embedpdf/plugin-annotation");
-let _embedpdf_plugin_form = require("@embedpdf/plugin-form");
+let _embedpdf_plugin_annotation_contract = require("@embedpdf/plugin-annotation/contract");
+let _embedpdf_plugin_form_scripting = require("@embedpdf/plugin-form/scripting");
 //#region src/capability.ts
 const DEFAULT_PREVIEW_WIDTH = 256;
 const LIBRARY_PIECEINFO_APP = "EMBD_StampLibrary";
@@ -125,7 +126,7 @@ function createStampCapability(ctx, config = {}) {
 		const doc = await openAssetDocument(new Uint8Array(resolved.bytes));
 		let imported;
 		try {
-			if (!doc.pieceInfo || !doc.pages.extract) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need an asset engine with pieceInfo and pages.extract");
+			if (!doc.pieceInfo) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "[stamp] canonical PDF libraries need an asset engine with pieceInfo");
 			const snapshot = await doc.pages.list();
 			if (snapshot.pageCount === 0) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "[stamp] a canonical stamp library PDF must contain at least one page");
 			const pages = snapshot.pages.map((layout) => {
@@ -246,7 +247,6 @@ function createStampCapability(ctx, config = {}) {
 				const doc = await openAssetDocument(canonicalBytes);
 				let appended;
 				try {
-					if (!doc.pages.insert || !doc.pages.extract) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.InvalidArg, "[stamp] a canonical library asset must be a single-page PDF");
 					const pageObjectNumber = result.insertedPageObjectNumbers[0];
@@ -407,17 +407,14 @@ function createStampCapability(ctx, config = {}) {
 			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 _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.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 (!(await doc.forms.list()).fields.some((field) => field.widgets.some(({ pageObjectNumber }) => pageObjectNumber === selectedPage.pageObjectNumber))) return bin;
 			if (!doc.pages.flatten || !doc.pages.extract) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotImplemented, "[stamp] dynamic PDF stamps need an asset engine with pages.flatten and pages.extract");
-			const scriptingConfig = config.scripting;
-			scripting = (0, _embedpdf_plugin_form.createFormScriptingController)({
+			scripting = (0, _embedpdf_plugin_form_scripting.createFormScriptingController)({
 				doc,
 				document: () => targetMeta,
-				config: scriptingConfig,
-				sandboxFactory: scriptingConfig.sandboxFactory ?? (() => import("@embedpdf/core-js-sandbox").then(({ createQuickJsSandbox }) => createQuickJsSandbox()))
+				config: config.scripting
 			});
-			const result = await scripting.recalculate(snapshot);
+			const result = await scripting.recalculate();
 			surfaceScriptingResult(result);
 			if (result.status === "failed") throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.Unknown, `[stamp] dynamic stamp scripting failed: ${result.error?.message ?? "native form effect failed"}`);
 			const pageObjectNumber = selectedPage.pageObjectNumber;
@@ -447,7 +444,7 @@ function createStampCapability(ctx, config = {}) {
 		const bin = binaries.get(assetId);
 		if (!asset || !bin) throw new _embedpdf_engine_core_runtime.EngineError(_embedpdf_engine_core_runtime.EngineErrorCode.NotFound, `[stamp] unknown asset '${assetId}'`);
 		const placement = await materializeForPlacement(documentId, asset, bin);
-		await ctx.forDocument(_embedpdf_plugin_annotation.AnnotationToken, documentId).armStamp({
+		await ctx.forDocument(_embedpdf_plugin_annotation_contract.AnnotationToken, documentId).armStamp({
 			source: placement.bytes,
 			preview: placement.preview ? {
 				data: placement.preview.bytes,
@@ -488,7 +485,7 @@ function createStampCapability(ctx, config = {}) {
 		removeAsset,
 		removeLibrary,
 		armAsset,
-		disarm: (documentId) => ctx.forDocument(_embedpdf_plugin_annotation.AnnotationToken, documentId).disarmStamp()
+		disarm: (documentId) => ctx.forDocument(_embedpdf_plugin_annotation_contract.AnnotationToken, documentId).disarmStamp()
 	};
 }
 //#endregion
@@ -564,9 +561,6 @@ const stampReducer = (state, action) => {
 	}
 };
 //#endregion
-//#region src/types.ts
-const StampToken = (0, _embedpdf_core.createCapabilityToken)("stamp");
-//#endregion
 //#region src/stamp.plugin.ts
 /**
 * The stamp plugin. WORKSPACE-scoped: libraries are shared across every open
@@ -578,14 +572,14 @@ const StampToken = (0, _embedpdf_core.createCapabilityToken)("stamp");
 */
 const stampPlugin = (config = {}) => (0, _embedpdf_core.definePlugin)({
 	id: "stamp",
-	token: StampToken,
+	token: require_contract.StampToken,
 	scope: "workspace",
 	initialState: initialStampState,
 	reduce: stampReducer,
 	capability: (ctx) => createStampCapability(ctx, config)
 });
 //#endregion
-exports.StampToken = StampToken;
+exports.StampToken = require_contract.StampToken;
 exports.stampPlugin = stampPlugin;
 
 //# sourceMappingURL=index.cjs.map