@embedpdf/web 3.0.0-next.10 → 3.0.0-next.12

package/dist/index.d.cts

@@ -216,6 +216,39 @@ declare function svgCursor({ svg, hotspot, fallback }: SvgCursorOptions): string
  */
 declare function sanitizeExternalUri(uri: string, allowedSchemes?: Iterable<string>): string | null;
 //#endregion
+//#region src/actions-ui.d.ts
+/** Structural twin of plugin-actions' `ActionOrigin`. */
+type ActionsUiOrigin = 'user' | 'hover' | 'lifecycle';
+/** Structural twin of plugin-actions' `ActionUiContext`. */
+interface ActionsUiEffectContext {
+  origin: ActionsUiOrigin;
+  phase: 'boot' | 'user';
+}
+/** Structural twin of plugin-actions' `ActionUiAdapter`. */
+interface ActionsUiAdapterShape {
+  openUri(uri: string, opts: {
+    isMap: boolean;
+    origin: ActionsUiOrigin;
+  }): void;
+  print(opts?: ActionsUiEffectContext): void;
+  alert?(message: string, opts: ActionsUiEffectContext & {
+    icon: number;
+    title?: string;
+  }): void;
+  gotoPage?(page: number, opts: ActionsUiEffectContext): void;
+}
+interface DefaultActionsUiAdapterOptions {
+  /**
+   * Per-handler overrides. Pass a FUNCTION for late binding (a binding's
+   * mutable handlers ref) — it is consulted on every effect, so a fresh
+   * closure never needs a reinstall.
+   */
+  overrides?: Partial<ActionsUiAdapterShape> | (() => Partial<ActionsUiAdapterShape> | undefined);
+  /** Navigation default for script `this.pageNum = n` requests. */
+  goToPage?: (page: number) => void;
+}
+declare const createDefaultActionsUiAdapter: (options?: DefaultActionsUiAdapterOptions) => ActionsUiAdapterShape;
+//#endregion
 //#region src/painted-image.d.ts
 /** A browser image source whose object URL has an explicit lifetime. */
 interface ObjectUrlImageSource {
@@ -557,5 +590,31 @@ interface WheelSample {
 /** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
 declare function wheelZoomFactor(e: WheelSample): number;
 //#endregion
-export { type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AttachSelectionHandleOptions, type ClipboardSelectionSource, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SelectionHandleSession, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePointerKind, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type SvgCursorOptions, type ViewProjector, type WebPlatformFeedback, type WheelSample, attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createStageGestureController, createStageSurface, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
+//#region src/byte-store.d.ts
+/**
+ * A bytes-by-id store over IndexedDB — the browser's answer to "keep these
+ * blobs for me". Structurally the store port a plugin declares for its own
+ * persistence (e.g. `StampLibraryStore` in `@embedpdf/plugin-stamp`); declared
+ * here as a twin so this package stays plugin-free, per the layering law.
+ *
+ * IndexedDB rather than localStorage: a library or an image is binary, and a
+ * localStorage string store caps at a few MB. One database, one object store,
+ * keys are the caller's ids, values are the bytes as stored.
+ */
+interface ByteStore {
+  list(): Promise<Array<{
+    id: string;
+    bytes: Uint8Array;
+  }>>;
+  put(id: string, bytes: Uint8Array): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+interface IndexedDbByteStoreOptions {
+  /** Object store name inside the database. Default `'bytes'`. */
+  storeName?: string;
+}
+/** Open (creating on first use) one IndexedDB object store keyed by id. */
+declare function indexedDbByteStore(dbName: string, opts?: IndexedDbByteStoreOptions): ByteStore;
+//#endregion
+export { type ActionsUiAdapterShape, type ActionsUiEffectContext, type ActionsUiOrigin, type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AttachSelectionHandleOptions, type ByteStore, type ClipboardSelectionSource, type DefaultActionsUiAdapterOptions, type IndexedDbByteStoreOptions, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SelectionHandleSession, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePointerKind, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type SvgCursorOptions, type ViewProjector, type WebPlatformFeedback, type WheelSample, attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createDefaultActionsUiAdapter, createStageGestureController, createStageSurface, indexedDbByteStore, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -216,6 +216,39 @@ declare function svgCursor({ svg, hotspot, fallback }: SvgCursorOptions): string
  */
 declare function sanitizeExternalUri(uri: string, allowedSchemes?: Iterable<string>): string | null;
 //#endregion
+//#region src/actions-ui.d.ts
+/** Structural twin of plugin-actions' `ActionOrigin`. */
+type ActionsUiOrigin = 'user' | 'hover' | 'lifecycle';
+/** Structural twin of plugin-actions' `ActionUiContext`. */
+interface ActionsUiEffectContext {
+  origin: ActionsUiOrigin;
+  phase: 'boot' | 'user';
+}
+/** Structural twin of plugin-actions' `ActionUiAdapter`. */
+interface ActionsUiAdapterShape {
+  openUri(uri: string, opts: {
+    isMap: boolean;
+    origin: ActionsUiOrigin;
+  }): void;
+  print(opts?: ActionsUiEffectContext): void;
+  alert?(message: string, opts: ActionsUiEffectContext & {
+    icon: number;
+    title?: string;
+  }): void;
+  gotoPage?(page: number, opts: ActionsUiEffectContext): void;
+}
+interface DefaultActionsUiAdapterOptions {
+  /**
+   * Per-handler overrides. Pass a FUNCTION for late binding (a binding's
+   * mutable handlers ref) — it is consulted on every effect, so a fresh
+   * closure never needs a reinstall.
+   */
+  overrides?: Partial<ActionsUiAdapterShape> | (() => Partial<ActionsUiAdapterShape> | undefined);
+  /** Navigation default for script `this.pageNum = n` requests. */
+  goToPage?: (page: number) => void;
+}
+declare const createDefaultActionsUiAdapter: (options?: DefaultActionsUiAdapterOptions) => ActionsUiAdapterShape;
+//#endregion
 //#region src/painted-image.d.ts
 /** A browser image source whose object URL has an explicit lifetime. */
 interface ObjectUrlImageSource {
@@ -557,5 +590,31 @@ interface WheelSample {
 /** Zoom factor for a ctrl/cmd wheel event (the caller decides zoom vs pan). */
 declare function wheelZoomFactor(e: WheelSample): number;
 //#endregion
-export { type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AttachSelectionHandleOptions, type ClipboardSelectionSource, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SelectionHandleSession, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePointerKind, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type SvgCursorOptions, type ViewProjector, type WebPlatformFeedback, type WheelSample, attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createStageGestureController, createStageSurface, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
+//#region src/byte-store.d.ts
+/**
+ * A bytes-by-id store over IndexedDB — the browser's answer to "keep these
+ * blobs for me". Structurally the store port a plugin declares for its own
+ * persistence (e.g. `StampLibraryStore` in `@embedpdf/plugin-stamp`); declared
+ * here as a twin so this package stays plugin-free, per the layering law.
+ *
+ * IndexedDB rather than localStorage: a library or an image is binary, and a
+ * localStorage string store caps at a few MB. One database, one object store,
+ * keys are the caller's ids, values are the bytes as stored.
+ */
+interface ByteStore {
+  list(): Promise<Array<{
+    id: string;
+    bytes: Uint8Array;
+  }>>;
+  put(id: string, bytes: Uint8Array): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+interface IndexedDbByteStoreOptions {
+  /** Object store name inside the database. Default `'bytes'`. */
+  storeName?: string;
+}
+/** Open (creating on first use) one IndexedDB object store keyed by id. */
+declare function indexedDbByteStore(dbName: string, opts?: IndexedDbByteStoreOptions): ByteStore;
+//#endregion
+export { type ActionsUiAdapterShape, type ActionsUiEffectContext, type ActionsUiOrigin, type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type AttachSelectionHandleOptions, type ByteStore, type ClipboardSelectionSource, type DefaultActionsUiAdapterOptions, type IndexedDbByteStoreOptions, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SelectionHandleSession, type StageGestureHost, type StageGestureOptions, type StageGestureSink, type StagePointerKind, type StageSurfaceHost, type StageSurfaceHub, type StageSurfaceOptions, type StageSurfaceSample, type StageWheelSample, type SvgCursorOptions, type ViewProjector, type WebPlatformFeedback, type WheelSample, attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createDefaultActionsUiAdapter, createStageGestureController, createStageSurface, indexedDbByteStore, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -234,6 +234,56 @@ function sanitizeExternalUri(uri, allowedSchemes = DEFAULT_ALLOWED_SCHEMES) {
 	}
 }
 //#endregion
+//#region src/actions-ui.ts
+/**
+* The DEFAULT actions UI adapter — the origin×phase visibility matrix plus
+* the browser fallbacks, written ONCE here so every framework binding
+* (react, angular, …) ships the SAME policy instead of forking it per
+* framework. Types are structural twins of `@embedpdf/plugin-actions`'
+* adapter contract (declared here so this package stays plugin-free, per
+* the layering law); assignability is checked where a binding installs it.
+*
+* The matrix (defaults only — an embedder override receives EVERY effect
+* with its context attached and decides for itself):
+* - URIs open through `sanitizeExternalUri` in a new tab (the dispatcher
+*   already policy-gated the node; blocked schemes are dropped here).
+* - Print: hover/lifecycle-origin requests never open the dialog; user
+*   requests fall back to `globalThis.print`. The `doc.print` AUTHORITY
+*   gate is upstream in the plugin and not overridable.
+* - Alert: document-open nags (lifecycle origin, boot phase) never reach
+*   `window.alert` — the boot-nag gap, closed.
+* - gotoPage: delegates to the binding-supplied navigator (the stage).
+*/
+const createDefaultActionsUiAdapter = (options = {}) => {
+	const overridesOf = () => typeof options.overrides === "function" ? options.overrides() : options.overrides;
+	return {
+		openUri: (uri, opts) => {
+			const current = overridesOf();
+			if (current?.openUri) {
+				current.openUri(uri, opts);
+				return;
+			}
+			const href = sanitizeExternalUri(uri);
+			if (href && typeof window !== "undefined") window.open(href, "_blank", "noopener,noreferrer");
+		},
+		print: (opts) => {
+			const current = overridesOf();
+			if (current?.print) current.print(opts);
+			else if (opts && opts.origin !== "user") {} else if (typeof globalThis.print === "function") globalThis.print();
+		},
+		alert: (message, opts) => {
+			const current = overridesOf();
+			if (current?.alert) current.alert(message, opts);
+			else if (opts.origin === "lifecycle" || opts.phase === "boot") {} else if (typeof globalThis.alert === "function") globalThis.alert(message);
+		},
+		gotoPage: (page, opts) => {
+			const current = overridesOf();
+			if (current?.gotoPage) current.gotoPage(page, opts);
+			else options.goToPage?.(page);
+		}
+	};
+};
+//#endregion
 //#region src/painted-image.ts
 /**
 * Bind a raster source to an <img> without ever painting its incomplete-image
@@ -1069,6 +1119,44 @@ function createStageSurface(el, stage, options = {}) {
 	};
 }
 //#endregion
-export { attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createStageGestureController, createStageSurface, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
+//#region src/byte-store.ts
+/** Open (creating on first use) one IndexedDB object store keyed by id. */
+function indexedDbByteStore(dbName, opts = {}) {
+	const storeName = opts.storeName ?? "bytes";
+	const open = () => new Promise((resolve, reject) => {
+		const request = indexedDB.open(dbName, 1);
+		request.onupgradeneeded = () => {
+			if (!request.result.objectStoreNames.contains(storeName)) request.result.createObjectStore(storeName);
+		};
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexedDB.open failed"));
+	});
+	const run = async (mode, body) => {
+		const db = await open();
+		try {
+			return await new Promise((resolve, reject) => {
+				const request = body(db.transaction(storeName, mode).objectStore(storeName));
+				request.onsuccess = () => resolve(request.result);
+				request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexedDB request failed"));
+			});
+		} finally {
+			db.close();
+		}
+	};
+	return {
+		list: async () => {
+			const keys = await run("readonly", (store) => store.getAllKeys());
+			const values = await run("readonly", (store) => store.getAll());
+			return keys.map((key, i) => ({
+				id: String(key),
+				bytes: new Uint8Array(values[i])
+			}));
+		},
+		put: (id, bytes) => run("readwrite", (store) => store.put(new Uint8Array(bytes), id)).then(() => void 0),
+		delete: (id) => run("readwrite", (store) => store.delete(id)).then(() => void 0)
+	};
+}
+//#endregion
+export { attachSelectionHandle, bindPaintedImage, computeReleaseVelocity, copySelection, createDefaultActionsUiAdapter, createStageGestureController, createStageSurface, indexedDbByteStore, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, vibrationFeedback, wheelZoomFactor, wireSelectionClipboard, wkFeedback };
 
 //# sourceMappingURL=index.js.map