@embedpdf/plugin-page-edit 3.0.0-next.14 → 3.0.0-next.15

package/dist/contract-B4DeVaKv.cjs

@@ -0,0 +1,25 @@
+//#region src/token.ts
+/** The package token, created once here and re-exported by `contract.ts`. */
+const PageEditToken = (0, require("@embedpdf/core").createCapabilityToken)("page-edit", {
+	hint: `add pageEditPlugin() from '@embedpdf/plugin-page-edit' to your plugins list`,
+	promises: {
+		rotateBy: true,
+		setRotation: true,
+		reorder: true,
+		delete: true,
+		insertBlank: true,
+		insertFromBytes: true,
+		insertFromDocument: true,
+		duplicate: true,
+		extract: true
+	}
+});
+//#endregion
+Object.defineProperty(exports, "PageEditToken", {
+	enumerable: true,
+	get: function() {
+		return PageEditToken;
+	}
+});
+
+//# sourceMappingURL=contract-B4DeVaKv.cjs.map

package/dist/contract-B4DeVaKv.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-B4DeVaKv.cjs","names":[],"sources":["../src/token.ts"],"sourcesContent":["/** The package token, created once here and re-exported by `contract.ts`. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { PageEditCapability } from './contract';\n\nexport const PageEditToken = createCapabilityToken<PageEditCapability>('page-edit', {\n  hint: `add pageEditPlugin() from '@embedpdf/plugin-page-edit' to your plugins list`,\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    rotateBy: true,\n    setRotation: true,\n    reorder: true,\n    delete: true,\n    insertBlank: true,\n    insertFromBytes: true,\n    insertFromDocument: true,\n    duplicate: true,\n    extract: true,\n  },\n});\n"],"mappings":";;AAKA,MAAa,iBAAA,2BAAA,CAAA,CAAA,sBAAA,CAA0D,aAAa;CAClF,MAAM;CAGN,UAAU;EACR,UAAU;EACV,aAAa;EACb,SAAS;EACT,QAAQ;EACR,aAAa;EACb,iBAAiB;EACjB,oBAAoB;EACpB,WAAW;EACX,SAAS;CACX;AACF,CAAC"}

package/dist/contract-CYWYR5Pd.js

@@ -0,0 +1,21 @@
+import { createCapabilityToken } from "@embedpdf/core";
+//#region src/token.ts
+/** The package token, created once here and re-exported by `contract.ts`. */
+const PageEditToken = createCapabilityToken("page-edit", {
+	hint: `add pageEditPlugin() from '@embedpdf/plugin-page-edit' to your plugins list`,
+	promises: {
+		rotateBy: true,
+		setRotation: true,
+		reorder: true,
+		delete: true,
+		insertBlank: true,
+		insertFromBytes: true,
+		insertFromDocument: true,
+		duplicate: true,
+		extract: true
+	}
+});
+//#endregion
+export { PageEditToken as t };
+
+//# sourceMappingURL=contract-CYWYR5Pd.js.map

package/dist/contract-CYWYR5Pd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-CYWYR5Pd.js","names":[],"sources":["../src/token.ts"],"sourcesContent":["/** The package token, created once here and re-exported by `contract.ts`. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { PageEditCapability } from './contract';\n\nexport const PageEditToken = createCapabilityToken<PageEditCapability>('page-edit', {\n  hint: `add pageEditPlugin() from '@embedpdf/plugin-page-edit' to your plugins list`,\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    rotateBy: true,\n    setRotation: true,\n    reorder: true,\n    delete: true,\n    insertBlank: true,\n    insertFromBytes: true,\n    insertFromDocument: true,\n    duplicate: true,\n    extract: true,\n  },\n});\n"],"mappings":";;;AAKA,MAAa,gBAAgB,sBAA0C,aAAa;CAClF,MAAM;CAGN,UAAU;EACR,UAAU;EACV,aAAa;EACb,SAAS;EACT,QAAQ;EACR,aAAa;EACb,iBAAiB;EACjB,oBAAoB;EACpB,WAAW;EACX,SAAS;CACX;AACF,CAAC"}

package/dist/contract-dl4LfrRX.d.cts

@@ -0,0 +1,80 @@
+import { OperationOptions, PageRef, PdfRotation, PdfRotation as PdfRotation$1, PdfSize, PdfSize as PdfSize$1 } from "@embedpdf/core";
+//#region src/token.d.ts
+declare const PageEditToken: import("@embedpdf/core").CapabilityToken<PageEditCapability>;
+//#endregion
+//#region src/contract.d.ts
+/**
+ * Where pages land: right after or before a page, or at the start or the end.
+ * A page named by its index is the page at that index when the verb is
+ * called, the page the user clicked; from then on it is that page, so the
+ * placement stays right when pages are reordered before the edit runs.
+ */
+type PagePlacement = {
+  readonly after: PageRef | number;
+} | {
+  readonly before: PageRef | number;
+} | 'start' | 'end';
+/** What an insert resolves: the new pages, in the order they were inserted. */
+interface PageEditInsertResult {
+  readonly pages: readonly PageRef[];
+}
+/** Options of `insertBlank()`. */
+interface PageInsertBlankOptions extends OperationOptions {
+  /** Where the new pages go. Default `'end'`. */
+  readonly placement?: PagePlacement;
+  /** The page size, in points. Default: the size of the page the new pages are placed next to. */
+  readonly size?: PdfSize;
+  /** How many blank pages. Default 1. */
+  readonly count?: number;
+}
+/** Options of `insertFromBytes()`. */
+interface PageInsertFromBytesOptions extends OperationOptions {
+  /** Only the source PDF's pages at these indexes, in this order. Default: every page. */
+  readonly pageIndexes?: readonly number[];
+  /** Where the new pages go. Default `'end'`. */
+  readonly placement?: PagePlacement;
+}
+/** Options of the verbs that copy pages in: `insertFromDocument()` and `duplicate()`. */
+interface PagePlacementOptions extends OperationOptions {
+  readonly placement?: PagePlacement;
+}
+/**
+ * Every edit runs in the order it was called, after the edits before it.
+ * Every verb rejects `permission-denied` (with `error.permission`) when the
+ * session may not do it, `not-found` for a page the document doesn't have,
+ * `invalid-input` for no pages, and `operation-cancelled` when its `signal`
+ * fires; a refusal changes nothing.
+ */
+interface PageEditCapability {
+  /** Whether rotating, reordering, deleting and inserting pages is allowed (`doc.pages.assemble`). */
+  canEdit(): boolean;
+  /**
+   * Whether copying pages out is allowed (`doc.download`): `extract()`,
+   * `duplicate()` and `insertFromDocument()` need it.
+   */
+  canExtract(): boolean;
+  /** Turn each page by a quarter or half turn from its own rotation. */
+  rotateBy(pages: readonly (PageRef | number)[], delta: 90 | -90 | 180, options?: OperationOptions): Promise<void>;
+  /** Give every page the same rotation. */
+  setRotation(pages: readonly (PageRef | number)[], rotation: PdfRotation, options?: OperationOptions): Promise<void>;
+  /** Move pages to the placement; several pages keep their order and land together. */
+  reorder(pages: readonly (PageRef | number)[], placement: PagePlacement, options?: OperationOptions): Promise<void>;
+  /** Delete pages. Deleting every page is refused (`invalid-input`): a document keeps one. */
+  delete(pages: readonly (PageRef | number)[], options?: OperationOptions): Promise<void>;
+  /** Insert blank pages, one unless `count` says more. */
+  insertBlank(options?: PageInsertBlankOptions): Promise<PageEditInsertResult>;
+  /** Insert the pages of another PDF, or only the ones at `pageIndexes`. */
+  insertFromBytes(bytes: Uint8Array | ArrayBuffer, options?: PageInsertFromBytesOptions): Promise<PageEditInsertResult>;
+  /**
+   * Insert copies of pages from another document open in the viewer. Needs
+   * `doc.download` on that document and `doc.pages.assemble` on this one.
+   */
+  insertFromDocument(documentId: string, pages: readonly (PageRef | number)[], options?: PagePlacementOptions): Promise<PageEditInsertResult>;
+  /** Copy pages, right after the last of them unless a placement says otherwise. */
+  duplicate(pages: readonly (PageRef | number)[], options?: PagePlacementOptions): Promise<PageEditInsertResult>;
+  /** Copy pages into a new PDF and resolve its bytes. This document doesn't change. */
+  extract(pages: readonly (PageRef | number)[], options?: OperationOptions): Promise<Uint8Array>;
+}
+//#endregion
+export { PagePlacement as a, PdfSize$1 as c, PageInsertFromBytesOptions as i, PageEditToken as l, PageEditInsertResult as n, PagePlacementOptions as o, PageInsertBlankOptions as r, PdfRotation$1 as s, PageEditCapability as t };
+//# sourceMappingURL=contract-dl4LfrRX.d.cts.map

package/dist/contract-dl4LfrRX.d.ts

@@ -0,0 +1,80 @@
+import { OperationOptions, PageRef, PdfRotation, PdfRotation as PdfRotation$1, PdfSize, PdfSize as PdfSize$1 } from "@embedpdf/core";
+//#region src/token.d.ts
+declare const PageEditToken: import("@embedpdf/core").CapabilityToken<PageEditCapability>;
+//#endregion
+//#region src/contract.d.ts
+/**
+ * Where pages land: right after or before a page, or at the start or the end.
+ * A page named by its index is the page at that index when the verb is
+ * called, the page the user clicked; from then on it is that page, so the
+ * placement stays right when pages are reordered before the edit runs.
+ */
+type PagePlacement = {
+  readonly after: PageRef | number;
+} | {
+  readonly before: PageRef | number;
+} | 'start' | 'end';
+/** What an insert resolves: the new pages, in the order they were inserted. */
+interface PageEditInsertResult {
+  readonly pages: readonly PageRef[];
+}
+/** Options of `insertBlank()`. */
+interface PageInsertBlankOptions extends OperationOptions {
+  /** Where the new pages go. Default `'end'`. */
+  readonly placement?: PagePlacement;
+  /** The page size, in points. Default: the size of the page the new pages are placed next to. */
+  readonly size?: PdfSize;
+  /** How many blank pages. Default 1. */
+  readonly count?: number;
+}
+/** Options of `insertFromBytes()`. */
+interface PageInsertFromBytesOptions extends OperationOptions {
+  /** Only the source PDF's pages at these indexes, in this order. Default: every page. */
+  readonly pageIndexes?: readonly number[];
+  /** Where the new pages go. Default `'end'`. */
+  readonly placement?: PagePlacement;
+}
+/** Options of the verbs that copy pages in: `insertFromDocument()` and `duplicate()`. */
+interface PagePlacementOptions extends OperationOptions {
+  readonly placement?: PagePlacement;
+}
+/**
+ * Every edit runs in the order it was called, after the edits before it.
+ * Every verb rejects `permission-denied` (with `error.permission`) when the
+ * session may not do it, `not-found` for a page the document doesn't have,
+ * `invalid-input` for no pages, and `operation-cancelled` when its `signal`
+ * fires; a refusal changes nothing.
+ */
+interface PageEditCapability {
+  /** Whether rotating, reordering, deleting and inserting pages is allowed (`doc.pages.assemble`). */
+  canEdit(): boolean;
+  /**
+   * Whether copying pages out is allowed (`doc.download`): `extract()`,
+   * `duplicate()` and `insertFromDocument()` need it.
+   */
+  canExtract(): boolean;
+  /** Turn each page by a quarter or half turn from its own rotation. */
+  rotateBy(pages: readonly (PageRef | number)[], delta: 90 | -90 | 180, options?: OperationOptions): Promise<void>;
+  /** Give every page the same rotation. */
+  setRotation(pages: readonly (PageRef | number)[], rotation: PdfRotation, options?: OperationOptions): Promise<void>;
+  /** Move pages to the placement; several pages keep their order and land together. */
+  reorder(pages: readonly (PageRef | number)[], placement: PagePlacement, options?: OperationOptions): Promise<void>;
+  /** Delete pages. Deleting every page is refused (`invalid-input`): a document keeps one. */
+  delete(pages: readonly (PageRef | number)[], options?: OperationOptions): Promise<void>;
+  /** Insert blank pages, one unless `count` says more. */
+  insertBlank(options?: PageInsertBlankOptions): Promise<PageEditInsertResult>;
+  /** Insert the pages of another PDF, or only the ones at `pageIndexes`. */
+  insertFromBytes(bytes: Uint8Array | ArrayBuffer, options?: PageInsertFromBytesOptions): Promise<PageEditInsertResult>;
+  /**
+   * Insert copies of pages from another document open in the viewer. Needs
+   * `doc.download` on that document and `doc.pages.assemble` on this one.
+   */
+  insertFromDocument(documentId: string, pages: readonly (PageRef | number)[], options?: PagePlacementOptions): Promise<PageEditInsertResult>;
+  /** Copy pages, right after the last of them unless a placement says otherwise. */
+  duplicate(pages: readonly (PageRef | number)[], options?: PagePlacementOptions): Promise<PageEditInsertResult>;
+  /** Copy pages into a new PDF and resolve its bytes. This document doesn't change. */
+  extract(pages: readonly (PageRef | number)[], options?: OperationOptions): Promise<Uint8Array>;
+}
+//#endregion
+export { PagePlacement as a, PdfSize$1 as c, PageInsertFromBytesOptions as i, PageEditToken as l, PageEditInsertResult as n, PagePlacementOptions as o, PageInsertBlankOptions as r, PdfRotation$1 as s, PageEditCapability as t };
+//# sourceMappingURL=contract-dl4LfrRX.d.ts.map

package/dist/contract.cjs

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

package/dist/contract.d.cts

@@ -1,2 +1,2 @@
-import { n as PageEditToken, t as PageEditCapability } from "./contract-BnXi11KD.cjs";
-export { type PageEditCapability, PageEditToken };
+import { a as PagePlacement, c as PdfSize, i as PageInsertFromBytesOptions, l as PageEditToken, n as PageEditInsertResult, o as PagePlacementOptions, r as PageInsertBlankOptions, s as PdfRotation, t as PageEditCapability } from "./contract-dl4LfrRX.cjs";
+export { PageEditCapability, PageEditInsertResult, PageEditToken, PageInsertBlankOptions, PageInsertFromBytesOptions, PagePlacement, PagePlacementOptions, type PdfRotation, type PdfSize };

package/dist/contract.d.ts

@@ -1,2 +1,2 @@
-import { n as PageEditToken, t as PageEditCapability } from "./contract-BnXi11KD.js";
-export { type PageEditCapability, PageEditToken };
+import { a as PagePlacement, c as PdfSize, i as PageInsertFromBytesOptions, l as PageEditToken, n as PageEditInsertResult, o as PagePlacementOptions, r as PageInsertBlankOptions, s as PdfRotation, t as PageEditCapability } from "./contract-dl4LfrRX.js";
+export { PageEditCapability, PageEditInsertResult, PageEditToken, PageInsertBlankOptions, PageInsertFromBytesOptions, PagePlacement, PagePlacementOptions, type PdfRotation, type PdfSize };

package/dist/contract.js

@@ -1,2 +1,2 @@
-import { t as PageEditToken } from "./contract-BsNelyd8.js";
+import { t as PageEditToken } from "./contract-CYWYR5Pd.js";
 export { PageEditToken };

package/dist/index.cjs

@@ -1,116 +1,186 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-UeGRCn-t.cjs");
+const require_contract = require("./contract-B4DeVaKv.cjs");
 let _embedpdf_core = require("@embedpdf/core");
-//#region src/capability.ts
+//#region src/controller.ts
 /**
-* Authorization for structural page edits. Maps to PDF bit 11 (ASSEMBLE =
-* insert/rotate/delete pages). The engine ALSO enforces this — every
-* page-structure verb throws `PermissionDenied` without it, identically on
-* local and cloud — so `canEdit()` is the UI mirror of a real guard, not the
-* guard itself. Typed as `DocCapability` so a typo is a compile error.
+* The page-edit controller. Stateless: it turns the engine handle's page
+* service into page edits that take refs or indexes. Turning a page relative
+* to its own rotation, and fixing a placement's page, live here once instead
+* of in every app's click handler.
+*
+* A verb refuses before anything starts (permission, pages, placement), then
+* queues its edit: edits run one at a time, in the order they were called.
 */
-const ASSEMBLE_CAPABILITY = "doc.pages.assemble";
-/**
-* Forwards structural edits to the document's engine handle, addressed by PON.
-* The handle (`ctx.doc`) and the page registry (`ctx.document()`, kept in sync
-* by the kernel's event→registry bridge) are both already on the plugin
-* context — this capability is the thin layer that turns the relative rotate
-* gesture into the engine's absolute wire.
-*/
-function createPageEditCapability(ctx) {
-	const requireDoc = () => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[page-edit] no document bound");
-		return doc;
+/** Inserting, rotating and deleting pages (PDF permission bit 4 or 11). The engine enforces it too. */
+const ASSEMBLE = "doc.pages.assemble";
+/** Copying pages out of a document is a partial download. The engine enforces it too. */
+const DOWNLOAD = "doc.download";
+/** The size of a blank page when the document has no page to match: Letter, in points. */
+const LETTER_SIZE = {
+	width: 612,
+	height: 792
+};
+function createPageEditController(ctx) {
+	const enqueue = ctx.serialQueue("edits");
+	ctx.onSettle(() => enqueue.idle());
+	/** Engine calls outside the guarded `ctx.doc` (another document, a scratch document) map their errors here. */
+	const mapErrors = async (work) => {
+		try {
+			return await work();
+		} catch (error) {
+			throw (0, _embedpdf_core.toPluginError)("page-edit", error);
+		}
 	};
-	/** Current absolute rotation of a page from the registry; 0 if unknown. */
-	const rotationOf = (pon) => {
-		return (ctx.document()?.pages.find((p) => p.pageObjectNumber === pon))?.rotation ?? 0;
+	const registry = () => ctx.document()?.pages ?? [];
+	const noPages = () => new _embedpdf_core.PluginError("invalid-input", "page-edit", "no pages given");
+	/**
+	* A verb's pages as refs, checked when it is called: an index names the
+	* page at that position now, which is the page the user clicked.
+	*/
+	const refsOf = (pages) => {
+		if (pages.length === 0) throw noPages();
+		return pages.map((page) => ctx.pageOf(page).ref);
 	};
 	/**
-	* Resolve a placement to the engine's index wire, from the registry at
-	* call time — the PON anchors are why "add after this thumbnail" survives
-	* a concurrent reorder. Returns the anchor page too, so `addBlank` can
-	* default its size without a second lookup.
+	* A placement as the engine's position, its page fixed when the verb is
+	* called, like the verb's own pages. Default `'end'`.
 	*/
-	const resolvePlacement = (placement) => {
-		if (!placement) return {
-			destIndex: void 0,
-			anchor: void 0
-		};
-		if ("index" in placement) return {
-			destIndex: placement.index,
-			anchor: void 0
-		};
-		const pon = "after" in placement ? placement.after : placement.before;
-		const anchor = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);
-		if (!anchor) throw new Error(`[page-edit] placement page not found: ${pon}`);
-		return {
-			destIndex: "after" in placement ? anchor.index + 1 : anchor.index,
-			anchor
-		};
+	const positionOf = (placement) => {
+		if (!placement || placement === "start" || placement === "end") return placement ?? "end";
+		if ("after" in placement) return { after: ctx.pageOf(placement.after).ref };
+		return { before: ctx.pageOf(placement.before).ref };
 	};
 	/**
-	* Default blank-page size: the insertion point's predecessor (the page
-	* the new one will follow), else the first page, else — only reachable
-	* with an empty registry, which an open document never has — US Letter.
+	* Default blank-page size: the page the placement names, else the page the
+	* new ones go next to (the first or the last), else Letter.
 	*/
-	const neighbourSize = (destIndex) => {
-		const pages = ctx.document()?.pages ?? [];
-		if (pages.length === 0) return {
-			width: 612,
-			height: 792
-		};
-		if (destIndex === void 0) return pages[pages.length - 1].size;
-		return pages[Math.max(0, Math.min(destIndex - 1, pages.length - 1))].size;
+	const sizeAt = (position) => {
+		if (typeof position === "object") return ctx.pageOf("after" in position ? position.after : position.before).size;
+		const pages = registry();
+		if (pages.length === 0) return LETTER_SIZE;
+		return (position === "start" ? pages[0] : pages[pages.length - 1]).size;
 	};
-	return {
-		canEdit() {
-			return ctx.doc?.security.allows(ASSEMBLE_CAPABILITY) ?? false;
+	/** Insert a PDF's pages; resolves the new pages. */
+	const insertBytes = async (bytes, position, signal) => {
+		return { pages: (await ctx.cancellable(signal, ctx.doc.pages.insert(bytes, position))).insertedPages };
+	};
+	return { api: {
+		canEdit: () => ctx.allows(ASSEMBLE),
+		canExtract: () => ctx.allows(DOWNLOAD),
+		rotateBy: async (pages, delta, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.rotateBy");
+			const refs = refsOf(pages);
+			const signal = options?.signal;
+			await enqueue(async () => {
+				const groups = /* @__PURE__ */ new Map();
+				for (const ref of refs) {
+					const rotation = ((ctx.pageOf(ref).rotation + delta) % 360 + 360) % 360;
+					groups.set(rotation, [...groups.get(rotation) ?? [], ref]);
+				}
+				for (const [rotation, group] of groups) await ctx.cancellable(signal, ctx.doc.pages.rotate(group, rotation));
+			}, options);
+		},
+		setRotation: async (pages, rotation, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.setRotation");
+			const refs = refsOf(pages);
+			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.rotate(refs, rotation)), options);
 		},
-		rotateBy(pon, delta) {
-			const next = ((rotationOf(pon) + delta) % 360 + 360) % 360;
-			return requireDoc().pages.rotate([pon], next);
+		reorder: async (pages, placement, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.reorder");
+			const refs = refsOf(pages);
+			const position = positionOf(placement);
+			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.reorder(refs, position)), options);
 		},
-		setRotation(pons, rotation) {
-			return requireDoc().pages.rotate(pons, rotation);
+		delete: async (pages, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.delete");
+			const refs = refsOf(pages);
+			const deleting = new Set(refs.map((ref) => ref.objectNumber));
+			if (registry().every((page) => deleting.has(page.ref.objectNumber))) throw new _embedpdf_core.PluginError("invalid-input", "page-edit", "a document keeps at least one page");
+			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.delete(refs)), options);
 		},
-		move(pons, destIndex) {
-			return requireDoc().pages.move(pons, destIndex);
+		insertBlank: async (options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertBlank");
+			const position = positionOf(options.placement);
+			return enqueue(async () => {
+				const size = options.size ?? sizeAt(position);
+				return { pages: (await ctx.cancellable(options.signal, ctx.doc.pages.insertBlank({
+					size,
+					count: options.count
+				}, position))).insertedPages };
+			}, options);
 		},
-		delete(pons) {
-			return requireDoc().pages.delete(pons);
+		insertFromBytes: async (bytes, options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertFromBytes");
+			const position = positionOf(options.placement);
+			const { pageIndexes, signal } = options;
+			if (pageIndexes?.length === 0) throw noPages();
+			return enqueue(async () => {
+				if (!pageIndexes) return insertBytes(bytes, position, signal);
+				const source = await mapErrors(() => ctx.engine.open({
+					kind: "bytes",
+					id: `page-edit-source-${Date.now().toString(36)}`,
+					bytes: new Uint8Array(bytes)
+				}, { scope: ["*"] }));
+				try {
+					const layout = await mapErrors(() => ctx.cancellable(signal, source.pages.list()));
+					const refs = pageIndexes.map((index) => {
+						const page = layout.pages[index];
+						if (!page) throw new _embedpdf_core.PluginError("not-found", "page-edit", `the PDF has no page ${index}`);
+						return page.ref;
+					});
+					const subset = await mapErrors(() => ctx.cancellable(signal, source.pages.extract(refs)));
+					return await insertBytes(subset, position, signal);
+				} finally {
+					await source.close();
+				}
+			}, options);
 		},
-		addBlank(opts = {}) {
-			const doc = requireDoc();
-			const { destIndex, anchor } = resolvePlacement(opts.placement);
-			const size = opts.size ?? anchor?.size ?? neighbourSize(destIndex);
-			return doc.pages.insertBlank({
-				size,
-				count: opts.count
-			}, destIndex);
+		insertFromDocument: async (documentId, pages, options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertFromDocument");
+			if (pages.length === 0) throw noPages();
+			const other = ctx.documentHandle(documentId);
+			if (!other) throw new _embedpdf_core.PluginError("not-found", "page-edit", `document '${documentId}' is not open`);
+			const otherPages = ctx.get(_embedpdf_core.DocumentsToken).listPages(documentId);
+			const refs = pages.map((page) => {
+				const found = typeof page === "number" ? otherPages[page] : otherPages.find((candidate) => candidate.ref.objectNumber === page.objectNumber);
+				if (!found) throw new _embedpdf_core.PluginError("not-found", "page-edit", `document '${documentId}' has no such page`);
+				return found.ref;
+			});
+			const position = positionOf(options.placement);
+			return enqueue(async () => {
+				const bytes = await mapErrors(() => ctx.cancellable(options.signal, other.pages.extract(refs)));
+				return insertBytes(bytes, position, options.signal);
+			}, options);
 		},
-		insert(bytes, opts = {}) {
-			const doc = requireDoc();
-			const { destIndex } = resolvePlacement(opts.placement);
-			return doc.pages.insert(bytes, destIndex);
+		duplicate: async (pages, options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.duplicate");
+			ctx.assertAllowed(DOWNLOAD, "pageEdit.duplicate");
+			const refs = refsOf(pages);
+			const position = options.placement ? positionOf(options.placement) : { after: refs[refs.length - 1] };
+			return enqueue(async () => {
+				const bytes = await ctx.cancellable(options.signal, ctx.doc.pages.extract(refs));
+				return insertBytes(bytes, position, options.signal);
+			}, options);
+		},
+		extract: async (pages, options) => {
+			ctx.assertAllowed(DOWNLOAD, "pageEdit.extract");
+			const refs = refsOf(pages);
+			return enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.extract(refs)), options);
 		}
-	};
+	} };
 }
 //#endregion
 //#region src/page-edit.plugin.ts
 /**
-* Document-scoped, stateless: turns the engine handle's page service into a
-* PON-addressed edit capability. The relative→absolute rotation lives in the
-* capability so the four framework adapters never re-derive it, and this is the
-* home for client-side edit state (pending/optimistic/undo) when it lands —
-* adapters keep their thin hook over `PageEditToken` unchanged.
+* Document-scoped and stateless: the engine handle's page service as page
+* edits that take refs or indexes. Turning a page relative to its own
+* rotation lives in the controller, so no app re-derives it.
 */
 const pageEditPlugin = () => (0, _embedpdf_core.definePlugin)({
 	id: "page-edit",
 	scope: "document",
 	token: require_contract.PageEditToken,
-	capability: createPageEditCapability
+	create: createPageEditController
 });
 //#endregion
 exports.PageEditToken = require_contract.PageEditToken;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["PageEditToken"],"sources":["../src/capability.ts","../src/page-edit.plugin.ts"],"sourcesContent":["import type {\n  PluginContext,\n  PageObjectNumber,\n  PageRotation,\n  DocCapability,\n  PdfSize,\n} from '@embedpdf/core';\nimport type { PageEditCapability, PagePlacement } from './types';\n\n/**\n * Authorization for structural page edits. Maps to PDF bit 11 (ASSEMBLE =\n * insert/rotate/delete pages). The engine ALSO enforces this — every\n * page-structure verb throws `PermissionDenied` without it, identically on\n * local and cloud — so `canEdit()` is the UI mirror of a real guard, not the\n * guard itself. Typed as `DocCapability` so a typo is a compile error.\n */\nconst ASSEMBLE_CAPABILITY: DocCapability = 'doc.pages.assemble';\n\n/**\n * Forwards structural edits to the document's engine handle, addressed by PON.\n * The handle (`ctx.doc`) and the page registry (`ctx.document()`, kept in sync\n * by the kernel's event→registry bridge) are both already on the plugin\n * context — this capability is the thin layer that turns the relative rotate\n * gesture into the engine's absolute wire.\n */\nexport function createPageEditCapability(ctx: PluginContext<unknown>): PageEditCapability {\n  const requireDoc = () => {\n    const doc = ctx.doc;\n    if (!doc) throw new Error('[page-edit] no document bound');\n    return doc;\n  };\n\n  /** Current absolute rotation of a page from the registry; 0 if unknown. */\n  const rotationOf = (pon: PageObjectNumber): PageRotation => {\n    const page = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);\n    return page?.rotation ?? 0;\n  };\n\n  /**\n   * Resolve a placement to the engine's index wire, from the registry at\n   * call time — the PON anchors are why \"add after this thumbnail\" survives\n   * a concurrent reorder. Returns the anchor page too, so `addBlank` can\n   * default its size without a second lookup.\n   */\n  const resolvePlacement = (placement?: PagePlacement) => {\n    if (!placement) return { destIndex: undefined, anchor: undefined };\n    if ('index' in placement) return { destIndex: placement.index, anchor: undefined };\n    const pon = 'after' in placement ? placement.after : placement.before;\n    const anchor = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);\n    if (!anchor) throw new Error(`[page-edit] placement page not found: ${pon}`);\n    return { destIndex: 'after' in placement ? anchor.index + 1 : anchor.index, anchor };\n  };\n\n  /**\n   * Default blank-page size: the insertion point's predecessor (the page\n   * the new one will follow), else the first page, else — only reachable\n   * with an empty registry, which an open document never has — US Letter.\n   */\n  const neighbourSize = (destIndex: number | undefined): PdfSize => {\n    const pages = ctx.document()?.pages ?? [];\n    if (pages.length === 0) return { width: 612, height: 792 };\n    if (destIndex === undefined) return pages[pages.length - 1].size;\n    return pages[Math.max(0, Math.min(destIndex - 1, pages.length - 1))].size;\n  };\n\n  return {\n    canEdit() {\n      // Wildcard-aware predicate (mirrors the engine's own enforcement),\n      // identical on both engines. NOT `effectiveScope.includes(...)` — that\n      // enumeration drops the `*` admin grant, so it would hide the UI on a\n      // default admin open even though the engine allows the edit.\n      return ctx.doc?.security.allows(ASSEMBLE_CAPABILITY) ?? false;\n    },\n\n    rotateBy(pon, delta) {\n      // Wrap to [0, 360) — the double-mod keeps -90 from current 0 landing on 270.\n      const next = ((((rotationOf(pon) + delta) % 360) + 360) % 360) as PageRotation;\n      return requireDoc().pages.rotate([pon], next);\n    },\n\n    setRotation(pons, rotation) {\n      return requireDoc().pages.rotate(pons, rotation);\n    },\n\n    move(pons, destIndex) {\n      return requireDoc().pages.move(pons, destIndex);\n    },\n\n    delete(pons) {\n      return requireDoc().pages.delete(pons);\n    },\n\n    addBlank(opts = {}) {\n      const doc = requireDoc();\n      const { destIndex, anchor } = resolvePlacement(opts.placement);\n      // PON placements match the anchor the user is looking at; everything\n      // else matches the neighbour the new page will follow.\n      const size = opts.size ?? anchor?.size ?? neighbourSize(destIndex);\n      return doc.pages.insertBlank({ size, count: opts.count }, destIndex);\n    },\n\n    insert(bytes, opts = {}) {\n      const doc = requireDoc();\n      const { destIndex } = resolvePlacement(opts.placement);\n      return doc.pages.insert(bytes, destIndex);\n    },\n  };\n}\n","import { definePlugin } from '@embedpdf/core';\nimport { createPageEditCapability } from './capability';\nimport { PageEditToken } from './types';\n\n/**\n * Document-scoped, stateless: turns the engine handle's page service into a\n * PON-addressed edit capability. The relative→absolute rotation lives in the\n * capability so the four framework adapters never re-derive it, and this is the\n * home for client-side edit state (pending/optimistic/undo) when it lands —\n * adapters keep their thin hook over `PageEditToken` unchanged.\n */\nexport const pageEditPlugin = () =>\n  definePlugin({\n    id: 'page-edit',\n    scope: 'document',\n    token: PageEditToken,\n    capability: createPageEditCapability,\n  });\n"],"mappings":";;;;;;;;;;;AAgBA,MAAM,sBAAqC;;;;;;;;AAS3C,SAAgB,yBAAyB,KAAiD;CACxF,MAAM,mBAAmB;EACvB,MAAM,MAAM,IAAI;EAChB,IAAI,CAAC,KAAK,MAAM,IAAI,MAAM,+BAA+B;EACzD,OAAO;CACT;;CAGA,MAAM,cAAc,QAAwC;EAE1D,QADa,IAAI,SAAS,CAAC,EAAE,MAAM,MAAM,MAAM,EAAE,qBAAqB,GAAG,EAAA,EAC5D,YAAY;CAC3B;;;;;;;CAQA,MAAM,oBAAoB,cAA8B;EACtD,IAAI,CAAC,WAAW,OAAO;GAAE,WAAW,KAAA;GAAW,QAAQ,KAAA;EAAU;EACjE,IAAI,WAAW,WAAW,OAAO;GAAE,WAAW,UAAU;GAAO,QAAQ,KAAA;EAAU;EACjF,MAAM,MAAM,WAAW,YAAY,UAAU,QAAQ,UAAU;EAC/D,MAAM,SAAS,IAAI,SAAS,CAAC,EAAE,MAAM,MAAM,MAAM,EAAE,qBAAqB,GAAG;EAC3E,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,yCAAyC,KAAK;EAC3E,OAAO;GAAE,WAAW,WAAW,YAAY,OAAO,QAAQ,IAAI,OAAO;GAAO;EAAO;CACrF;;;;;;CAOA,MAAM,iBAAiB,cAA2C;EAChE,MAAM,QAAQ,IAAI,SAAS,CAAC,EAAE,SAAS,CAAC;EACxC,IAAI,MAAM,WAAW,GAAG,OAAO;GAAE,OAAO;GAAK,QAAQ;EAAI;EACzD,IAAI,cAAc,KAAA,GAAW,OAAO,MAAM,MAAM,SAAS,EAAE,CAAC;EAC5D,OAAO,MAAM,KAAK,IAAI,GAAG,KAAK,IAAI,YAAY,GAAG,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC;CACvE;CAEA,OAAO;EACL,UAAU;GAKR,OAAO,IAAI,KAAK,SAAS,OAAO,mBAAmB,KAAK;EAC1D;EAEA,SAAS,KAAK,OAAO;GAEnB,MAAM,SAAW,WAAW,GAAG,IAAI,SAAS,MAAO,OAAO;GAC1D,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,GAAG,IAAI;EAC9C;EAEA,YAAY,MAAM,UAAU;GAC1B,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,MAAM,QAAQ;EACjD;EAEA,KAAK,MAAM,WAAW;GACpB,OAAO,WAAW,CAAC,CAAC,MAAM,KAAK,MAAM,SAAS;EAChD;EAEA,OAAO,MAAM;GACX,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,IAAI;EACvC;EAEA,SAAS,OAAO,CAAC,GAAG;GAClB,MAAM,MAAM,WAAW;GACvB,MAAM,EAAE,WAAW,WAAW,iBAAiB,KAAK,SAAS;GAG7D,MAAM,OAAO,KAAK,QAAQ,QAAQ,QAAQ,cAAc,SAAS;GACjE,OAAO,IAAI,MAAM,YAAY;IAAE;IAAM,OAAO,KAAK;GAAM,GAAG,SAAS;EACrE;EAEA,OAAO,OAAO,OAAO,CAAC,GAAG;GACvB,MAAM,MAAM,WAAW;GACvB,MAAM,EAAE,cAAc,iBAAiB,KAAK,SAAS;GACrD,OAAO,IAAI,MAAM,OAAO,OAAO,SAAS;EAC1C;CACF;AACF;;;;;;;;;;AChGA,MAAa,wBAAA,GAAA,eAAA,aAAA,CACE;CACX,IAAI;CACJ,OAAO;CACP,OAAOA,iBAAAA;CACP,YAAY;AACd,CAAC"}
+{"version":3,"file":"index.cjs","names":["PluginError","DocumentsToken","PageEditToken"],"sources":["../src/controller.ts","../src/page-edit.plugin.ts"],"sourcesContent":["/**\n * The page-edit controller. Stateless: it turns the engine handle's page\n * service into page edits that take refs or indexes. Turning a page relative\n * to its own rotation, and fixing a placement's page, live here once instead\n * of in every app's click handler.\n *\n * A verb refuses before anything starts (permission, pages, placement), then\n * queues its edit: edits run one at a time, in the order they were called.\n */\nimport { DocumentsToken, PluginError, toPluginError } from '@embedpdf/core';\nimport type {\n  DocCapability,\n  PageInfo,\n  PagePosition,\n  PageRef,\n  PdfRotation,\n  PdfSize,\n  PluginContext,\n} from '@embedpdf/core';\n\nimport type { PageEditCapability, PageEditInsertResult, PagePlacement } from './contract';\n\n/** Inserting, rotating and deleting pages (PDF permission bit 4 or 11). The engine enforces it too. */\nconst ASSEMBLE: DocCapability = 'doc.pages.assemble';\n/** Copying pages out of a document is a partial download. The engine enforces it too. */\nconst DOWNLOAD: DocCapability = 'doc.download';\n\n/** The size of a blank page when the document has no page to match: Letter, in points. */\nconst LETTER_SIZE: PdfSize = { width: 612, height: 792 };\n\nexport function createPageEditController(ctx: PluginContext<void>) {\n  const enqueue = ctx.serialQueue('edits');\n  // A download waits for the page edits on their way.\n  ctx.onSettle(() => enqueue.idle());\n\n  /** Engine calls outside the guarded `ctx.doc` (another document, a scratch document) map their errors here. */\n  const mapErrors = async <T>(work: () => Promise<T>): Promise<T> => {\n    try {\n      return await work();\n    } catch (error) {\n      throw toPluginError('page-edit', error);\n    }\n  };\n  const registry = (): readonly PageInfo[] => ctx.document()?.pages ?? [];\n  const noPages = () => new PluginError('invalid-input', 'page-edit', 'no pages given');\n\n  /**\n   * A verb's pages as refs, checked when it is called: an index names the\n   * page at that position now, which is the page the user clicked.\n   */\n  const refsOf = (pages: readonly (PageRef | number)[]): PageRef[] => {\n    if (pages.length === 0) throw noPages();\n    return pages.map((page) => ctx.pageOf(page).ref);\n  };\n\n  /**\n   * A placement as the engine's position, its page fixed when the verb is\n   * called, like the verb's own pages. Default `'end'`.\n   */\n  const positionOf = (placement: PagePlacement | undefined): PagePosition => {\n    if (!placement || placement === 'start' || placement === 'end') return placement ?? 'end';\n    if ('after' in placement) return { after: ctx.pageOf(placement.after).ref };\n    return { before: ctx.pageOf(placement.before).ref };\n  };\n  /**\n   * Default blank-page size: the page the placement names, else the page the\n   * new ones go next to (the first or the last), else Letter.\n   */\n  const sizeAt = (position: PagePosition): PdfSize => {\n    if (typeof position === 'object') {\n      return ctx.pageOf('after' in position ? position.after : position.before).size;\n    }\n    const pages = registry();\n    if (pages.length === 0) return LETTER_SIZE;\n    return (position === 'start' ? pages[0] : pages[pages.length - 1]).size;\n  };\n\n  /** Insert a PDF's pages; resolves the new pages. */\n  const insertBytes = async (\n    bytes: Uint8Array | ArrayBuffer,\n    position: PagePosition,\n    signal: AbortSignal | undefined,\n  ): Promise<PageEditInsertResult> => {\n    const result = await ctx.cancellable(signal, ctx.doc.pages.insert(bytes, position));\n    return { pages: result.insertedPages };\n  };\n\n  const api: PageEditCapability = {\n    canEdit: () => ctx.allows(ASSEMBLE),\n    canExtract: () => ctx.allows(DOWNLOAD),\n\n    rotateBy: async (pages, delta, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.rotateBy');\n      const refs = refsOf(pages);\n      const signal = options?.signal;\n      await enqueue(async () => {\n        // The engine sets one rotation per call, so pages are grouped by where\n        // they end up. Each page's rotation is read when the edit runs, after\n        // the edits queued before it; the double modulo keeps -90 from 0 at 270.\n        const groups = new Map<PdfRotation, PageRef[]>();\n        for (const ref of refs) {\n          const turned = (ctx.pageOf(ref).rotation + delta) % 360;\n          const rotation = ((turned + 360) % 360) as PdfRotation;\n          groups.set(rotation, [...(groups.get(rotation) ?? []), ref]);\n        }\n        for (const [rotation, group] of groups) {\n          await ctx.cancellable(signal, ctx.doc.pages.rotate(group, rotation));\n        }\n      }, options);\n    },\n\n    setRotation: async (pages, rotation, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.setRotation');\n      const refs = refsOf(pages);\n      await enqueue(\n        () => ctx.cancellable(options?.signal, ctx.doc.pages.rotate(refs, rotation)),\n        options,\n      );\n    },\n\n    reorder: async (pages, placement, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.reorder');\n      const refs = refsOf(pages);\n      const position = positionOf(placement);\n      await enqueue(\n        () => ctx.cancellable(options?.signal, ctx.doc.pages.reorder(refs, position)),\n        options,\n      );\n    },\n\n    delete: async (pages, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.delete');\n      const refs = refsOf(pages);\n      const deleting = new Set(refs.map((ref) => ref.objectNumber));\n      if (registry().every((page) => deleting.has(page.ref.objectNumber))) {\n        throw new PluginError('invalid-input', 'page-edit', 'a document keeps at least one page');\n      }\n      await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.delete(refs)), options);\n    },\n\n    insertBlank: async (options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.insertBlank');\n      const position = positionOf(options.placement);\n      return enqueue(async () => {\n        const size = options.size ?? sizeAt(position);\n        const result = await ctx.cancellable(\n          options.signal,\n          ctx.doc.pages.insertBlank({ size, count: options.count }, position),\n        );\n        return { pages: result.insertedPages };\n      }, options);\n    },\n\n    insertFromBytes: async (bytes, options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.insertFromBytes');\n      const position = positionOf(options.placement);\n      const { pageIndexes, signal } = options;\n      if (pageIndexes?.length === 0) throw noPages();\n      return enqueue(async () => {\n        if (!pageIndexes) return insertBytes(bytes, position, signal);\n        // Some of the pages: open the bytes beside the document, extract them, insert those.\n        const source = await mapErrors(() =>\n          ctx.engine.open(\n            {\n              kind: 'bytes',\n              id: `page-edit-source-${Date.now().toString(36)}`,\n              bytes: new Uint8Array(bytes),\n            },\n            { scope: ['*'] },\n          ),\n        );\n        try {\n          const layout = await mapErrors(() => ctx.cancellable(signal, source.pages.list()));\n          const refs = pageIndexes.map((index) => {\n            const page = layout.pages[index];\n            if (!page) {\n              throw new PluginError('not-found', 'page-edit', `the PDF has no page ${index}`);\n            }\n            return page.ref;\n          });\n          const subset = await mapErrors(() => ctx.cancellable(signal, source.pages.extract(refs)));\n          return await insertBytes(subset, position, signal);\n        } finally {\n          await source.close();\n        }\n      }, options);\n    },\n\n    insertFromDocument: async (documentId, pages, options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.insertFromDocument');\n      if (pages.length === 0) throw noPages();\n      const other = ctx.documentHandle(documentId);\n      if (!other) {\n        throw new PluginError('not-found', 'page-edit', `document '${documentId}' is not open`);\n      }\n      // The pages are the other document's, so its page list resolves them.\n      const otherPages = ctx.get(DocumentsToken).listPages(documentId);\n      const refs = pages.map((page) => {\n        const found =\n          typeof page === 'number'\n            ? otherPages[page]\n            : otherPages.find((candidate) => candidate.ref.objectNumber === page.objectNumber);\n        if (!found) {\n          throw new PluginError(\n            'not-found',\n            'page-edit',\n            `document '${documentId}' has no such page`,\n          );\n        }\n        return found.ref;\n      });\n      const position = positionOf(options.placement);\n      return enqueue(async () => {\n        // The other document's session decides whether its pages may be copied\n        // out: the engine refuses `doc.download` there with the permission named.\n        const bytes = await mapErrors(() =>\n          ctx.cancellable(options.signal, other.pages.extract(refs)),\n        );\n        return insertBytes(bytes, position, options.signal);\n      }, options);\n    },\n\n    duplicate: async (pages, options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.duplicate');\n      ctx.assertAllowed(DOWNLOAD, 'pageEdit.duplicate');\n      const refs = refsOf(pages);\n      const position = options.placement\n        ? positionOf(options.placement)\n        : { after: refs[refs.length - 1]! };\n      return enqueue(async () => {\n        const bytes = await ctx.cancellable(options.signal, ctx.doc.pages.extract(refs));\n        return insertBytes(bytes, position, options.signal);\n      }, options);\n    },\n\n    extract: async (pages, options) => {\n      ctx.assertAllowed(DOWNLOAD, 'pageEdit.extract');\n      const refs = refsOf(pages);\n      return enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.extract(refs)), options);\n    },\n  };\n  return { api };\n}\n","import { definePlugin } from '@embedpdf/core';\n\nimport { PageEditToken } from './contract';\nimport { createPageEditController } from './controller';\n\n/**\n * Document-scoped and stateless: the engine handle's page service as page\n * edits that take refs or indexes. Turning a page relative to its own\n * rotation lives in the controller, so no app re-derives it.\n */\nexport const pageEditPlugin = () =>\n  definePlugin({\n    id: 'page-edit',\n    scope: 'document',\n    token: PageEditToken,\n    create: createPageEditController,\n  });\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -1,13 +1,11 @@
-import { n as PageEditToken, t as PageEditCapability } from "./contract-BnXi11KD.cjs";
+import { a as PagePlacement, c as PdfSize, i as PageInsertFromBytesOptions, l as PageEditToken, n as PageEditInsertResult, o as PagePlacementOptions, r as PageInsertBlankOptions, s as PdfRotation, t as PageEditCapability } from "./contract-dl4LfrRX.cjs";
 //#region src/page-edit.plugin.d.ts
 /**
- * Document-scoped, stateless: turns the engine handle's page service into a
- * PON-addressed edit capability. The relative→absolute rotation lives in the
- * capability so the four framework adapters never re-derive it, and this is the
- * home for client-side edit state (pending/optimistic/undo) when it lands —
- * adapters keep their thin hook over `PageEditToken` unchanged.
+ * Document-scoped and stateless: the engine handle's page service as page
+ * edits that take refs or indexes. Turning a page relative to its own
+ * rotation lives in the controller, so no app re-derives it.
  */
-declare const pageEditPlugin: () => import("@embedpdf/core").PluginDef<unknown, import("@embedpdf/core").Action, PageEditCapability>;
+declare const pageEditPlugin: () => import("@embedpdf/core").PluginDef<void, PageEditCapability, import("@embedpdf/core").NoSettings>;
 //#endregion
-export { type PageEditCapability, PageEditToken, pageEditPlugin };
+export { PageEditCapability, PageEditInsertResult, PageEditToken, PageInsertBlankOptions, PageInsertFromBytesOptions, PagePlacement, PagePlacementOptions, type PdfRotation, type PdfSize, pageEditPlugin };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,13 +1,11 @@
-import { n as PageEditToken, t as PageEditCapability } from "./contract-BnXi11KD.js";
+import { a as PagePlacement, c as PdfSize, i as PageInsertFromBytesOptions, l as PageEditToken, n as PageEditInsertResult, o as PagePlacementOptions, r as PageInsertBlankOptions, s as PdfRotation, t as PageEditCapability } from "./contract-dl4LfrRX.js";
 //#region src/page-edit.plugin.d.ts
 /**
- * Document-scoped, stateless: turns the engine handle's page service into a
- * PON-addressed edit capability. The relative→absolute rotation lives in the
- * capability so the four framework adapters never re-derive it, and this is the
- * home for client-side edit state (pending/optimistic/undo) when it lands —
- * adapters keep their thin hook over `PageEditToken` unchanged.
+ * Document-scoped and stateless: the engine handle's page service as page
+ * edits that take refs or indexes. Turning a page relative to its own
+ * rotation lives in the controller, so no app re-derives it.
  */
-declare const pageEditPlugin: () => import("@embedpdf/core").PluginDef<unknown, import("@embedpdf/core").Action, PageEditCapability>;
+declare const pageEditPlugin: () => import("@embedpdf/core").PluginDef<void, PageEditCapability, import("@embedpdf/core").NoSettings>;
 //#endregion
-export { type PageEditCapability, PageEditToken, pageEditPlugin };
+export { PageEditCapability, PageEditInsertResult, PageEditToken, PageInsertBlankOptions, PageInsertFromBytesOptions, PagePlacement, PagePlacementOptions, type PdfRotation, type PdfSize, pageEditPlugin };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,115 +1,185 @@
-import { t as PageEditToken } from "./contract-BsNelyd8.js";
-import { definePlugin } from "@embedpdf/core";
-//#region src/capability.ts
+import { t as PageEditToken } from "./contract-CYWYR5Pd.js";
+import { DocumentsToken, PluginError, definePlugin, toPluginError } from "@embedpdf/core";
+//#region src/controller.ts
 /**
-* Authorization for structural page edits. Maps to PDF bit 11 (ASSEMBLE =
-* insert/rotate/delete pages). The engine ALSO enforces this — every
-* page-structure verb throws `PermissionDenied` without it, identically on
-* local and cloud — so `canEdit()` is the UI mirror of a real guard, not the
-* guard itself. Typed as `DocCapability` so a typo is a compile error.
+* The page-edit controller. Stateless: it turns the engine handle's page
+* service into page edits that take refs or indexes. Turning a page relative
+* to its own rotation, and fixing a placement's page, live here once instead
+* of in every app's click handler.
+*
+* A verb refuses before anything starts (permission, pages, placement), then
+* queues its edit: edits run one at a time, in the order they were called.
 */
-const ASSEMBLE_CAPABILITY = "doc.pages.assemble";
-/**
-* Forwards structural edits to the document's engine handle, addressed by PON.
-* The handle (`ctx.doc`) and the page registry (`ctx.document()`, kept in sync
-* by the kernel's event→registry bridge) are both already on the plugin
-* context — this capability is the thin layer that turns the relative rotate
-* gesture into the engine's absolute wire.
-*/
-function createPageEditCapability(ctx) {
-	const requireDoc = () => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[page-edit] no document bound");
-		return doc;
+/** Inserting, rotating and deleting pages (PDF permission bit 4 or 11). The engine enforces it too. */
+const ASSEMBLE = "doc.pages.assemble";
+/** Copying pages out of a document is a partial download. The engine enforces it too. */
+const DOWNLOAD = "doc.download";
+/** The size of a blank page when the document has no page to match: Letter, in points. */
+const LETTER_SIZE = {
+	width: 612,
+	height: 792
+};
+function createPageEditController(ctx) {
+	const enqueue = ctx.serialQueue("edits");
+	ctx.onSettle(() => enqueue.idle());
+	/** Engine calls outside the guarded `ctx.doc` (another document, a scratch document) map their errors here. */
+	const mapErrors = async (work) => {
+		try {
+			return await work();
+		} catch (error) {
+			throw toPluginError("page-edit", error);
+		}
 	};
-	/** Current absolute rotation of a page from the registry; 0 if unknown. */
-	const rotationOf = (pon) => {
-		return (ctx.document()?.pages.find((p) => p.pageObjectNumber === pon))?.rotation ?? 0;
+	const registry = () => ctx.document()?.pages ?? [];
+	const noPages = () => new PluginError("invalid-input", "page-edit", "no pages given");
+	/**
+	* A verb's pages as refs, checked when it is called: an index names the
+	* page at that position now, which is the page the user clicked.
+	*/
+	const refsOf = (pages) => {
+		if (pages.length === 0) throw noPages();
+		return pages.map((page) => ctx.pageOf(page).ref);
 	};
 	/**
-	* Resolve a placement to the engine's index wire, from the registry at
-	* call time — the PON anchors are why "add after this thumbnail" survives
-	* a concurrent reorder. Returns the anchor page too, so `addBlank` can
-	* default its size without a second lookup.
+	* A placement as the engine's position, its page fixed when the verb is
+	* called, like the verb's own pages. Default `'end'`.
 	*/
-	const resolvePlacement = (placement) => {
-		if (!placement) return {
-			destIndex: void 0,
-			anchor: void 0
-		};
-		if ("index" in placement) return {
-			destIndex: placement.index,
-			anchor: void 0
-		};
-		const pon = "after" in placement ? placement.after : placement.before;
-		const anchor = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);
-		if (!anchor) throw new Error(`[page-edit] placement page not found: ${pon}`);
-		return {
-			destIndex: "after" in placement ? anchor.index + 1 : anchor.index,
-			anchor
-		};
+	const positionOf = (placement) => {
+		if (!placement || placement === "start" || placement === "end") return placement ?? "end";
+		if ("after" in placement) return { after: ctx.pageOf(placement.after).ref };
+		return { before: ctx.pageOf(placement.before).ref };
 	};
 	/**
-	* Default blank-page size: the insertion point's predecessor (the page
-	* the new one will follow), else the first page, else — only reachable
-	* with an empty registry, which an open document never has — US Letter.
+	* Default blank-page size: the page the placement names, else the page the
+	* new ones go next to (the first or the last), else Letter.
 	*/
-	const neighbourSize = (destIndex) => {
-		const pages = ctx.document()?.pages ?? [];
-		if (pages.length === 0) return {
-			width: 612,
-			height: 792
-		};
-		if (destIndex === void 0) return pages[pages.length - 1].size;
-		return pages[Math.max(0, Math.min(destIndex - 1, pages.length - 1))].size;
+	const sizeAt = (position) => {
+		if (typeof position === "object") return ctx.pageOf("after" in position ? position.after : position.before).size;
+		const pages = registry();
+		if (pages.length === 0) return LETTER_SIZE;
+		return (position === "start" ? pages[0] : pages[pages.length - 1]).size;
 	};
-	return {
-		canEdit() {
-			return ctx.doc?.security.allows(ASSEMBLE_CAPABILITY) ?? false;
+	/** Insert a PDF's pages; resolves the new pages. */
+	const insertBytes = async (bytes, position, signal) => {
+		return { pages: (await ctx.cancellable(signal, ctx.doc.pages.insert(bytes, position))).insertedPages };
+	};
+	return { api: {
+		canEdit: () => ctx.allows(ASSEMBLE),
+		canExtract: () => ctx.allows(DOWNLOAD),
+		rotateBy: async (pages, delta, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.rotateBy");
+			const refs = refsOf(pages);
+			const signal = options?.signal;
+			await enqueue(async () => {
+				const groups = /* @__PURE__ */ new Map();
+				for (const ref of refs) {
+					const rotation = ((ctx.pageOf(ref).rotation + delta) % 360 + 360) % 360;
+					groups.set(rotation, [...groups.get(rotation) ?? [], ref]);
+				}
+				for (const [rotation, group] of groups) await ctx.cancellable(signal, ctx.doc.pages.rotate(group, rotation));
+			}, options);
+		},
+		setRotation: async (pages, rotation, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.setRotation");
+			const refs = refsOf(pages);
+			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.rotate(refs, rotation)), options);
 		},
-		rotateBy(pon, delta) {
-			const next = ((rotationOf(pon) + delta) % 360 + 360) % 360;
-			return requireDoc().pages.rotate([pon], next);
+		reorder: async (pages, placement, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.reorder");
+			const refs = refsOf(pages);
+			const position = positionOf(placement);
+			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.reorder(refs, position)), options);
 		},
-		setRotation(pons, rotation) {
-			return requireDoc().pages.rotate(pons, rotation);
+		delete: async (pages, options) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.delete");
+			const refs = refsOf(pages);
+			const deleting = new Set(refs.map((ref) => ref.objectNumber));
+			if (registry().every((page) => deleting.has(page.ref.objectNumber))) throw new PluginError("invalid-input", "page-edit", "a document keeps at least one page");
+			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.delete(refs)), options);
 		},
-		move(pons, destIndex) {
-			return requireDoc().pages.move(pons, destIndex);
+		insertBlank: async (options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertBlank");
+			const position = positionOf(options.placement);
+			return enqueue(async () => {
+				const size = options.size ?? sizeAt(position);
+				return { pages: (await ctx.cancellable(options.signal, ctx.doc.pages.insertBlank({
+					size,
+					count: options.count
+				}, position))).insertedPages };
+			}, options);
 		},
-		delete(pons) {
-			return requireDoc().pages.delete(pons);
+		insertFromBytes: async (bytes, options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertFromBytes");
+			const position = positionOf(options.placement);
+			const { pageIndexes, signal } = options;
+			if (pageIndexes?.length === 0) throw noPages();
+			return enqueue(async () => {
+				if (!pageIndexes) return insertBytes(bytes, position, signal);
+				const source = await mapErrors(() => ctx.engine.open({
+					kind: "bytes",
+					id: `page-edit-source-${Date.now().toString(36)}`,
+					bytes: new Uint8Array(bytes)
+				}, { scope: ["*"] }));
+				try {
+					const layout = await mapErrors(() => ctx.cancellable(signal, source.pages.list()));
+					const refs = pageIndexes.map((index) => {
+						const page = layout.pages[index];
+						if (!page) throw new PluginError("not-found", "page-edit", `the PDF has no page ${index}`);
+						return page.ref;
+					});
+					const subset = await mapErrors(() => ctx.cancellable(signal, source.pages.extract(refs)));
+					return await insertBytes(subset, position, signal);
+				} finally {
+					await source.close();
+				}
+			}, options);
 		},
-		addBlank(opts = {}) {
-			const doc = requireDoc();
-			const { destIndex, anchor } = resolvePlacement(opts.placement);
-			const size = opts.size ?? anchor?.size ?? neighbourSize(destIndex);
-			return doc.pages.insertBlank({
-				size,
-				count: opts.count
-			}, destIndex);
+		insertFromDocument: async (documentId, pages, options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertFromDocument");
+			if (pages.length === 0) throw noPages();
+			const other = ctx.documentHandle(documentId);
+			if (!other) throw new PluginError("not-found", "page-edit", `document '${documentId}' is not open`);
+			const otherPages = ctx.get(DocumentsToken).listPages(documentId);
+			const refs = pages.map((page) => {
+				const found = typeof page === "number" ? otherPages[page] : otherPages.find((candidate) => candidate.ref.objectNumber === page.objectNumber);
+				if (!found) throw new PluginError("not-found", "page-edit", `document '${documentId}' has no such page`);
+				return found.ref;
+			});
+			const position = positionOf(options.placement);
+			return enqueue(async () => {
+				const bytes = await mapErrors(() => ctx.cancellable(options.signal, other.pages.extract(refs)));
+				return insertBytes(bytes, position, options.signal);
+			}, options);
 		},
-		insert(bytes, opts = {}) {
-			const doc = requireDoc();
-			const { destIndex } = resolvePlacement(opts.placement);
-			return doc.pages.insert(bytes, destIndex);
+		duplicate: async (pages, options = {}) => {
+			ctx.assertAllowed(ASSEMBLE, "pageEdit.duplicate");
+			ctx.assertAllowed(DOWNLOAD, "pageEdit.duplicate");
+			const refs = refsOf(pages);
+			const position = options.placement ? positionOf(options.placement) : { after: refs[refs.length - 1] };
+			return enqueue(async () => {
+				const bytes = await ctx.cancellable(options.signal, ctx.doc.pages.extract(refs));
+				return insertBytes(bytes, position, options.signal);
+			}, options);
+		},
+		extract: async (pages, options) => {
+			ctx.assertAllowed(DOWNLOAD, "pageEdit.extract");
+			const refs = refsOf(pages);
+			return enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.extract(refs)), options);
 		}
-	};
+	} };
 }
 //#endregion
 //#region src/page-edit.plugin.ts
 /**
-* Document-scoped, stateless: turns the engine handle's page service into a
-* PON-addressed edit capability. The relative→absolute rotation lives in the
-* capability so the four framework adapters never re-derive it, and this is the
-* home for client-side edit state (pending/optimistic/undo) when it lands —
-* adapters keep their thin hook over `PageEditToken` unchanged.
+* Document-scoped and stateless: the engine handle's page service as page
+* edits that take refs or indexes. Turning a page relative to its own
+* rotation lives in the controller, so no app re-derives it.
 */
 const pageEditPlugin = () => definePlugin({
 	id: "page-edit",
 	scope: "document",
 	token: PageEditToken,
-	capability: createPageEditCapability
+	create: createPageEditController
 });
 //#endregion
 export { PageEditToken, pageEditPlugin };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/capability.ts","../src/page-edit.plugin.ts"],"sourcesContent":["import type {\n  PluginContext,\n  PageObjectNumber,\n  PageRotation,\n  DocCapability,\n  PdfSize,\n} from '@embedpdf/core';\nimport type { PageEditCapability, PagePlacement } from './types';\n\n/**\n * Authorization for structural page edits. Maps to PDF bit 11 (ASSEMBLE =\n * insert/rotate/delete pages). The engine ALSO enforces this — every\n * page-structure verb throws `PermissionDenied` without it, identically on\n * local and cloud — so `canEdit()` is the UI mirror of a real guard, not the\n * guard itself. Typed as `DocCapability` so a typo is a compile error.\n */\nconst ASSEMBLE_CAPABILITY: DocCapability = 'doc.pages.assemble';\n\n/**\n * Forwards structural edits to the document's engine handle, addressed by PON.\n * The handle (`ctx.doc`) and the page registry (`ctx.document()`, kept in sync\n * by the kernel's event→registry bridge) are both already on the plugin\n * context — this capability is the thin layer that turns the relative rotate\n * gesture into the engine's absolute wire.\n */\nexport function createPageEditCapability(ctx: PluginContext<unknown>): PageEditCapability {\n  const requireDoc = () => {\n    const doc = ctx.doc;\n    if (!doc) throw new Error('[page-edit] no document bound');\n    return doc;\n  };\n\n  /** Current absolute rotation of a page from the registry; 0 if unknown. */\n  const rotationOf = (pon: PageObjectNumber): PageRotation => {\n    const page = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);\n    return page?.rotation ?? 0;\n  };\n\n  /**\n   * Resolve a placement to the engine's index wire, from the registry at\n   * call time — the PON anchors are why \"add after this thumbnail\" survives\n   * a concurrent reorder. Returns the anchor page too, so `addBlank` can\n   * default its size without a second lookup.\n   */\n  const resolvePlacement = (placement?: PagePlacement) => {\n    if (!placement) return { destIndex: undefined, anchor: undefined };\n    if ('index' in placement) return { destIndex: placement.index, anchor: undefined };\n    const pon = 'after' in placement ? placement.after : placement.before;\n    const anchor = ctx.document()?.pages.find((p) => p.pageObjectNumber === pon);\n    if (!anchor) throw new Error(`[page-edit] placement page not found: ${pon}`);\n    return { destIndex: 'after' in placement ? anchor.index + 1 : anchor.index, anchor };\n  };\n\n  /**\n   * Default blank-page size: the insertion point's predecessor (the page\n   * the new one will follow), else the first page, else — only reachable\n   * with an empty registry, which an open document never has — US Letter.\n   */\n  const neighbourSize = (destIndex: number | undefined): PdfSize => {\n    const pages = ctx.document()?.pages ?? [];\n    if (pages.length === 0) return { width: 612, height: 792 };\n    if (destIndex === undefined) return pages[pages.length - 1].size;\n    return pages[Math.max(0, Math.min(destIndex - 1, pages.length - 1))].size;\n  };\n\n  return {\n    canEdit() {\n      // Wildcard-aware predicate (mirrors the engine's own enforcement),\n      // identical on both engines. NOT `effectiveScope.includes(...)` — that\n      // enumeration drops the `*` admin grant, so it would hide the UI on a\n      // default admin open even though the engine allows the edit.\n      return ctx.doc?.security.allows(ASSEMBLE_CAPABILITY) ?? false;\n    },\n\n    rotateBy(pon, delta) {\n      // Wrap to [0, 360) — the double-mod keeps -90 from current 0 landing on 270.\n      const next = ((((rotationOf(pon) + delta) % 360) + 360) % 360) as PageRotation;\n      return requireDoc().pages.rotate([pon], next);\n    },\n\n    setRotation(pons, rotation) {\n      return requireDoc().pages.rotate(pons, rotation);\n    },\n\n    move(pons, destIndex) {\n      return requireDoc().pages.move(pons, destIndex);\n    },\n\n    delete(pons) {\n      return requireDoc().pages.delete(pons);\n    },\n\n    addBlank(opts = {}) {\n      const doc = requireDoc();\n      const { destIndex, anchor } = resolvePlacement(opts.placement);\n      // PON placements match the anchor the user is looking at; everything\n      // else matches the neighbour the new page will follow.\n      const size = opts.size ?? anchor?.size ?? neighbourSize(destIndex);\n      return doc.pages.insertBlank({ size, count: opts.count }, destIndex);\n    },\n\n    insert(bytes, opts = {}) {\n      const doc = requireDoc();\n      const { destIndex } = resolvePlacement(opts.placement);\n      return doc.pages.insert(bytes, destIndex);\n    },\n  };\n}\n","import { definePlugin } from '@embedpdf/core';\nimport { createPageEditCapability } from './capability';\nimport { PageEditToken } from './types';\n\n/**\n * Document-scoped, stateless: turns the engine handle's page service into a\n * PON-addressed edit capability. The relative→absolute rotation lives in the\n * capability so the four framework adapters never re-derive it, and this is the\n * home for client-side edit state (pending/optimistic/undo) when it lands —\n * adapters keep their thin hook over `PageEditToken` unchanged.\n */\nexport const pageEditPlugin = () =>\n  definePlugin({\n    id: 'page-edit',\n    scope: 'document',\n    token: PageEditToken,\n    capability: createPageEditCapability,\n  });\n"],"mappings":";;;;;;;;;;AAgBA,MAAM,sBAAqC;;;;;;;;AAS3C,SAAgB,yBAAyB,KAAiD;CACxF,MAAM,mBAAmB;EACvB,MAAM,MAAM,IAAI;EAChB,IAAI,CAAC,KAAK,MAAM,IAAI,MAAM,+BAA+B;EACzD,OAAO;CACT;;CAGA,MAAM,cAAc,QAAwC;EAE1D,QADa,IAAI,SAAS,CAAC,EAAE,MAAM,MAAM,MAAM,EAAE,qBAAqB,GAAG,EAAA,EAC5D,YAAY;CAC3B;;;;;;;CAQA,MAAM,oBAAoB,cAA8B;EACtD,IAAI,CAAC,WAAW,OAAO;GAAE,WAAW,KAAA;GAAW,QAAQ,KAAA;EAAU;EACjE,IAAI,WAAW,WAAW,OAAO;GAAE,WAAW,UAAU;GAAO,QAAQ,KAAA;EAAU;EACjF,MAAM,MAAM,WAAW,YAAY,UAAU,QAAQ,UAAU;EAC/D,MAAM,SAAS,IAAI,SAAS,CAAC,EAAE,MAAM,MAAM,MAAM,EAAE,qBAAqB,GAAG;EAC3E,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,yCAAyC,KAAK;EAC3E,OAAO;GAAE,WAAW,WAAW,YAAY,OAAO,QAAQ,IAAI,OAAO;GAAO;EAAO;CACrF;;;;;;CAOA,MAAM,iBAAiB,cAA2C;EAChE,MAAM,QAAQ,IAAI,SAAS,CAAC,EAAE,SAAS,CAAC;EACxC,IAAI,MAAM,WAAW,GAAG,OAAO;GAAE,OAAO;GAAK,QAAQ;EAAI;EACzD,IAAI,cAAc,KAAA,GAAW,OAAO,MAAM,MAAM,SAAS,EAAE,CAAC;EAC5D,OAAO,MAAM,KAAK,IAAI,GAAG,KAAK,IAAI,YAAY,GAAG,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC;CACvE;CAEA,OAAO;EACL,UAAU;GAKR,OAAO,IAAI,KAAK,SAAS,OAAO,mBAAmB,KAAK;EAC1D;EAEA,SAAS,KAAK,OAAO;GAEnB,MAAM,SAAW,WAAW,GAAG,IAAI,SAAS,MAAO,OAAO;GAC1D,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,GAAG,IAAI;EAC9C;EAEA,YAAY,MAAM,UAAU;GAC1B,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,MAAM,QAAQ;EACjD;EAEA,KAAK,MAAM,WAAW;GACpB,OAAO,WAAW,CAAC,CAAC,MAAM,KAAK,MAAM,SAAS;EAChD;EAEA,OAAO,MAAM;GACX,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,IAAI;EACvC;EAEA,SAAS,OAAO,CAAC,GAAG;GAClB,MAAM,MAAM,WAAW;GACvB,MAAM,EAAE,WAAW,WAAW,iBAAiB,KAAK,SAAS;GAG7D,MAAM,OAAO,KAAK,QAAQ,QAAQ,QAAQ,cAAc,SAAS;GACjE,OAAO,IAAI,MAAM,YAAY;IAAE;IAAM,OAAO,KAAK;GAAM,GAAG,SAAS;EACrE;EAEA,OAAO,OAAO,OAAO,CAAC,GAAG;GACvB,MAAM,MAAM,WAAW;GACvB,MAAM,EAAE,cAAc,iBAAiB,KAAK,SAAS;GACrD,OAAO,IAAI,MAAM,OAAO,OAAO,SAAS;EAC1C;CACF;AACF;;;;;;;;;;AChGA,MAAa,uBACX,aAAa;CACX,IAAI;CACJ,OAAO;CACP,OAAO;CACP,YAAY;AACd,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/controller.ts","../src/page-edit.plugin.ts"],"sourcesContent":["/**\n * The page-edit controller. Stateless: it turns the engine handle's page\n * service into page edits that take refs or indexes. Turning a page relative\n * to its own rotation, and fixing a placement's page, live here once instead\n * of in every app's click handler.\n *\n * A verb refuses before anything starts (permission, pages, placement), then\n * queues its edit: edits run one at a time, in the order they were called.\n */\nimport { DocumentsToken, PluginError, toPluginError } from '@embedpdf/core';\nimport type {\n  DocCapability,\n  PageInfo,\n  PagePosition,\n  PageRef,\n  PdfRotation,\n  PdfSize,\n  PluginContext,\n} from '@embedpdf/core';\n\nimport type { PageEditCapability, PageEditInsertResult, PagePlacement } from './contract';\n\n/** Inserting, rotating and deleting pages (PDF permission bit 4 or 11). The engine enforces it too. */\nconst ASSEMBLE: DocCapability = 'doc.pages.assemble';\n/** Copying pages out of a document is a partial download. The engine enforces it too. */\nconst DOWNLOAD: DocCapability = 'doc.download';\n\n/** The size of a blank page when the document has no page to match: Letter, in points. */\nconst LETTER_SIZE: PdfSize = { width: 612, height: 792 };\n\nexport function createPageEditController(ctx: PluginContext<void>) {\n  const enqueue = ctx.serialQueue('edits');\n  // A download waits for the page edits on their way.\n  ctx.onSettle(() => enqueue.idle());\n\n  /** Engine calls outside the guarded `ctx.doc` (another document, a scratch document) map their errors here. */\n  const mapErrors = async <T>(work: () => Promise<T>): Promise<T> => {\n    try {\n      return await work();\n    } catch (error) {\n      throw toPluginError('page-edit', error);\n    }\n  };\n  const registry = (): readonly PageInfo[] => ctx.document()?.pages ?? [];\n  const noPages = () => new PluginError('invalid-input', 'page-edit', 'no pages given');\n\n  /**\n   * A verb's pages as refs, checked when it is called: an index names the\n   * page at that position now, which is the page the user clicked.\n   */\n  const refsOf = (pages: readonly (PageRef | number)[]): PageRef[] => {\n    if (pages.length === 0) throw noPages();\n    return pages.map((page) => ctx.pageOf(page).ref);\n  };\n\n  /**\n   * A placement as the engine's position, its page fixed when the verb is\n   * called, like the verb's own pages. Default `'end'`.\n   */\n  const positionOf = (placement: PagePlacement | undefined): PagePosition => {\n    if (!placement || placement === 'start' || placement === 'end') return placement ?? 'end';\n    if ('after' in placement) return { after: ctx.pageOf(placement.after).ref };\n    return { before: ctx.pageOf(placement.before).ref };\n  };\n  /**\n   * Default blank-page size: the page the placement names, else the page the\n   * new ones go next to (the first or the last), else Letter.\n   */\n  const sizeAt = (position: PagePosition): PdfSize => {\n    if (typeof position === 'object') {\n      return ctx.pageOf('after' in position ? position.after : position.before).size;\n    }\n    const pages = registry();\n    if (pages.length === 0) return LETTER_SIZE;\n    return (position === 'start' ? pages[0] : pages[pages.length - 1]).size;\n  };\n\n  /** Insert a PDF's pages; resolves the new pages. */\n  const insertBytes = async (\n    bytes: Uint8Array | ArrayBuffer,\n    position: PagePosition,\n    signal: AbortSignal | undefined,\n  ): Promise<PageEditInsertResult> => {\n    const result = await ctx.cancellable(signal, ctx.doc.pages.insert(bytes, position));\n    return { pages: result.insertedPages };\n  };\n\n  const api: PageEditCapability = {\n    canEdit: () => ctx.allows(ASSEMBLE),\n    canExtract: () => ctx.allows(DOWNLOAD),\n\n    rotateBy: async (pages, delta, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.rotateBy');\n      const refs = refsOf(pages);\n      const signal = options?.signal;\n      await enqueue(async () => {\n        // The engine sets one rotation per call, so pages are grouped by where\n        // they end up. Each page's rotation is read when the edit runs, after\n        // the edits queued before it; the double modulo keeps -90 from 0 at 270.\n        const groups = new Map<PdfRotation, PageRef[]>();\n        for (const ref of refs) {\n          const turned = (ctx.pageOf(ref).rotation + delta) % 360;\n          const rotation = ((turned + 360) % 360) as PdfRotation;\n          groups.set(rotation, [...(groups.get(rotation) ?? []), ref]);\n        }\n        for (const [rotation, group] of groups) {\n          await ctx.cancellable(signal, ctx.doc.pages.rotate(group, rotation));\n        }\n      }, options);\n    },\n\n    setRotation: async (pages, rotation, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.setRotation');\n      const refs = refsOf(pages);\n      await enqueue(\n        () => ctx.cancellable(options?.signal, ctx.doc.pages.rotate(refs, rotation)),\n        options,\n      );\n    },\n\n    reorder: async (pages, placement, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.reorder');\n      const refs = refsOf(pages);\n      const position = positionOf(placement);\n      await enqueue(\n        () => ctx.cancellable(options?.signal, ctx.doc.pages.reorder(refs, position)),\n        options,\n      );\n    },\n\n    delete: async (pages, options) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.delete');\n      const refs = refsOf(pages);\n      const deleting = new Set(refs.map((ref) => ref.objectNumber));\n      if (registry().every((page) => deleting.has(page.ref.objectNumber))) {\n        throw new PluginError('invalid-input', 'page-edit', 'a document keeps at least one page');\n      }\n      await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.delete(refs)), options);\n    },\n\n    insertBlank: async (options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.insertBlank');\n      const position = positionOf(options.placement);\n      return enqueue(async () => {\n        const size = options.size ?? sizeAt(position);\n        const result = await ctx.cancellable(\n          options.signal,\n          ctx.doc.pages.insertBlank({ size, count: options.count }, position),\n        );\n        return { pages: result.insertedPages };\n      }, options);\n    },\n\n    insertFromBytes: async (bytes, options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.insertFromBytes');\n      const position = positionOf(options.placement);\n      const { pageIndexes, signal } = options;\n      if (pageIndexes?.length === 0) throw noPages();\n      return enqueue(async () => {\n        if (!pageIndexes) return insertBytes(bytes, position, signal);\n        // Some of the pages: open the bytes beside the document, extract them, insert those.\n        const source = await mapErrors(() =>\n          ctx.engine.open(\n            {\n              kind: 'bytes',\n              id: `page-edit-source-${Date.now().toString(36)}`,\n              bytes: new Uint8Array(bytes),\n            },\n            { scope: ['*'] },\n          ),\n        );\n        try {\n          const layout = await mapErrors(() => ctx.cancellable(signal, source.pages.list()));\n          const refs = pageIndexes.map((index) => {\n            const page = layout.pages[index];\n            if (!page) {\n              throw new PluginError('not-found', 'page-edit', `the PDF has no page ${index}`);\n            }\n            return page.ref;\n          });\n          const subset = await mapErrors(() => ctx.cancellable(signal, source.pages.extract(refs)));\n          return await insertBytes(subset, position, signal);\n        } finally {\n          await source.close();\n        }\n      }, options);\n    },\n\n    insertFromDocument: async (documentId, pages, options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.insertFromDocument');\n      if (pages.length === 0) throw noPages();\n      const other = ctx.documentHandle(documentId);\n      if (!other) {\n        throw new PluginError('not-found', 'page-edit', `document '${documentId}' is not open`);\n      }\n      // The pages are the other document's, so its page list resolves them.\n      const otherPages = ctx.get(DocumentsToken).listPages(documentId);\n      const refs = pages.map((page) => {\n        const found =\n          typeof page === 'number'\n            ? otherPages[page]\n            : otherPages.find((candidate) => candidate.ref.objectNumber === page.objectNumber);\n        if (!found) {\n          throw new PluginError(\n            'not-found',\n            'page-edit',\n            `document '${documentId}' has no such page`,\n          );\n        }\n        return found.ref;\n      });\n      const position = positionOf(options.placement);\n      return enqueue(async () => {\n        // The other document's session decides whether its pages may be copied\n        // out: the engine refuses `doc.download` there with the permission named.\n        const bytes = await mapErrors(() =>\n          ctx.cancellable(options.signal, other.pages.extract(refs)),\n        );\n        return insertBytes(bytes, position, options.signal);\n      }, options);\n    },\n\n    duplicate: async (pages, options = {}) => {\n      ctx.assertAllowed(ASSEMBLE, 'pageEdit.duplicate');\n      ctx.assertAllowed(DOWNLOAD, 'pageEdit.duplicate');\n      const refs = refsOf(pages);\n      const position = options.placement\n        ? positionOf(options.placement)\n        : { after: refs[refs.length - 1]! };\n      return enqueue(async () => {\n        const bytes = await ctx.cancellable(options.signal, ctx.doc.pages.extract(refs));\n        return insertBytes(bytes, position, options.signal);\n      }, options);\n    },\n\n    extract: async (pages, options) => {\n      ctx.assertAllowed(DOWNLOAD, 'pageEdit.extract');\n      const refs = refsOf(pages);\n      return enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.extract(refs)), options);\n    },\n  };\n  return { api };\n}\n","import { definePlugin } from '@embedpdf/core';\n\nimport { PageEditToken } from './contract';\nimport { createPageEditController } from './controller';\n\n/**\n * Document-scoped and stateless: the engine handle's page service as page\n * edits that take refs or indexes. Turning a page relative to its own\n * rotation lives in the controller, so no app re-derives it.\n */\nexport const pageEditPlugin = () =>\n  definePlugin({\n    id: 'page-edit',\n    scope: 'document',\n    token: PageEditToken,\n    create: createPageEditController,\n  });\n"],"mappings":";;;;;;;;;;;;;AAuBA,MAAM,WAA0B;;AAEhC,MAAM,WAA0B;;AAGhC,MAAM,cAAuB;CAAE,OAAO;CAAK,QAAQ;AAAI;AAEvD,SAAgB,yBAAyB,KAA0B;CACjE,MAAM,UAAU,IAAI,YAAY,OAAO;CAEvC,IAAI,eAAe,QAAQ,KAAK,CAAC;;CAGjC,MAAM,YAAY,OAAU,SAAuC;EACjE,IAAI;GACF,OAAO,MAAM,KAAK;EACpB,SAAS,OAAO;GACd,MAAM,cAAc,aAAa,KAAK;EACxC;CACF;CACA,MAAM,iBAAsC,IAAI,SAAS,CAAC,EAAE,SAAS,CAAC;CACtE,MAAM,gBAAgB,IAAI,YAAY,iBAAiB,aAAa,gBAAgB;;;;;CAMpF,MAAM,UAAU,UAAoD;EAClE,IAAI,MAAM,WAAW,GAAG,MAAM,QAAQ;EACtC,OAAO,MAAM,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,CAAC,GAAG;CACjD;;;;;CAMA,MAAM,cAAc,cAAuD;EACzE,IAAI,CAAC,aAAa,cAAc,WAAW,cAAc,OAAO,OAAO,aAAa;EACpF,IAAI,WAAW,WAAW,OAAO,EAAE,OAAO,IAAI,OAAO,UAAU,KAAK,CAAC,CAAC,IAAI;EAC1E,OAAO,EAAE,QAAQ,IAAI,OAAO,UAAU,MAAM,CAAC,CAAC,IAAI;CACpD;;;;;CAKA,MAAM,UAAU,aAAoC;EAClD,IAAI,OAAO,aAAa,UACtB,OAAO,IAAI,OAAO,WAAW,WAAW,SAAS,QAAQ,SAAS,MAAM,CAAC,CAAC;EAE5E,MAAM,QAAQ,SAAS;EACvB,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,QAAQ,aAAa,UAAU,MAAM,KAAK,MAAM,MAAM,SAAS,GAAA,CAAI;CACrE;;CAGA,MAAM,cAAc,OAClB,OACA,UACA,WACkC;EAElC,OAAO,EAAE,QAAO,MADK,IAAI,YAAY,QAAQ,IAAI,IAAI,MAAM,OAAO,OAAO,QAAQ,CAAC,EAAA,CAC3D,cAAc;CACvC;CA4JA,OAAO,EAAE,KAAA;EAzJP,eAAe,IAAI,OAAO,QAAQ;EAClC,kBAAkB,IAAI,OAAO,QAAQ;EAErC,UAAU,OAAO,OAAO,OAAO,YAAY;GACzC,IAAI,cAAc,UAAU,mBAAmB;GAC/C,MAAM,OAAO,OAAO,KAAK;GACzB,MAAM,SAAS,SAAS;GACxB,MAAM,QAAQ,YAAY;IAIxB,MAAM,yBAAS,IAAI,IAA4B;IAC/C,KAAK,MAAM,OAAO,MAAM;KAEtB,MAAM,aADU,IAAI,OAAO,GAAG,CAAC,CAAC,WAAW,SAAS,MACxB,OAAO;KACnC,OAAO,IAAI,UAAU,CAAC,GAAI,OAAO,IAAI,QAAQ,KAAK,CAAC,GAAI,GAAG,CAAC;IAC7D;IACA,KAAK,MAAM,CAAC,UAAU,UAAU,QAC9B,MAAM,IAAI,YAAY,QAAQ,IAAI,IAAI,MAAM,OAAO,OAAO,QAAQ,CAAC;GAEvE,GAAG,OAAO;EACZ;EAEA,aAAa,OAAO,OAAO,UAAU,YAAY;GAC/C,IAAI,cAAc,UAAU,sBAAsB;GAClD,MAAM,OAAO,OAAO,KAAK;GACzB,MAAM,cACE,IAAI,YAAY,SAAS,QAAQ,IAAI,IAAI,MAAM,OAAO,MAAM,QAAQ,CAAC,GAC3E,OACF;EACF;EAEA,SAAS,OAAO,OAAO,WAAW,YAAY;GAC5C,IAAI,cAAc,UAAU,kBAAkB;GAC9C,MAAM,OAAO,OAAO,KAAK;GACzB,MAAM,WAAW,WAAW,SAAS;GACrC,MAAM,cACE,IAAI,YAAY,SAAS,QAAQ,IAAI,IAAI,MAAM,QAAQ,MAAM,QAAQ,CAAC,GAC5E,OACF;EACF;EAEA,QAAQ,OAAO,OAAO,YAAY;GAChC,IAAI,cAAc,UAAU,iBAAiB;GAC7C,MAAM,OAAO,OAAO,KAAK;GACzB,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC;GAC5D,IAAI,SAAS,CAAC,CAAC,OAAO,SAAS,SAAS,IAAI,KAAK,IAAI,YAAY,CAAC,GAChE,MAAM,IAAI,YAAY,iBAAiB,aAAa,oCAAoC;GAE1F,MAAM,cAAc,IAAI,YAAY,SAAS,QAAQ,IAAI,IAAI,MAAM,OAAO,IAAI,CAAC,GAAG,OAAO;EAC3F;EAEA,aAAa,OAAO,UAAU,CAAC,MAAM;GACnC,IAAI,cAAc,UAAU,sBAAsB;GAClD,MAAM,WAAW,WAAW,QAAQ,SAAS;GAC7C,OAAO,QAAQ,YAAY;IACzB,MAAM,OAAO,QAAQ,QAAQ,OAAO,QAAQ;IAK5C,OAAO,EAAE,QAAO,MAJK,IAAI,YACvB,QAAQ,QACR,IAAI,IAAI,MAAM,YAAY;KAAE;KAAM,OAAO,QAAQ;IAAM,GAAG,QAAQ,CACpE,EAAA,CACuB,cAAc;GACvC,GAAG,OAAO;EACZ;EAEA,iBAAiB,OAAO,OAAO,UAAU,CAAC,MAAM;GAC9C,IAAI,cAAc,UAAU,0BAA0B;GACtD,MAAM,WAAW,WAAW,QAAQ,SAAS;GAC7C,MAAM,EAAE,aAAa,WAAW;GAChC,IAAI,aAAa,WAAW,GAAG,MAAM,QAAQ;GAC7C,OAAO,QAAQ,YAAY;IACzB,IAAI,CAAC,aAAa,OAAO,YAAY,OAAO,UAAU,MAAM;IAE5D,MAAM,SAAS,MAAM,gBACnB,IAAI,OAAO,KACT;KACE,MAAM;KACN,IAAI,oBAAoB,KAAK,IAAI,CAAC,CAAC,SAAS,EAAE;KAC9C,OAAO,IAAI,WAAW,KAAK;IAC7B,GACA,EAAE,OAAO,CAAC,GAAG,EAAE,CACjB,CACF;IACA,IAAI;KACF,MAAM,SAAS,MAAM,gBAAgB,IAAI,YAAY,QAAQ,OAAO,MAAM,KAAK,CAAC,CAAC;KACjF,MAAM,OAAO,YAAY,KAAK,UAAU;MACtC,MAAM,OAAO,OAAO,MAAM;MAC1B,IAAI,CAAC,MACH,MAAM,IAAI,YAAY,aAAa,aAAa,uBAAuB,OAAO;MAEhF,OAAO,KAAK;KACd,CAAC;KACD,MAAM,SAAS,MAAM,gBAAgB,IAAI,YAAY,QAAQ,OAAO,MAAM,QAAQ,IAAI,CAAC,CAAC;KACxF,OAAO,MAAM,YAAY,QAAQ,UAAU,MAAM;IACnD,UAAU;KACR,MAAM,OAAO,MAAM;IACrB;GACF,GAAG,OAAO;EACZ;EAEA,oBAAoB,OAAO,YAAY,OAAO,UAAU,CAAC,MAAM;GAC7D,IAAI,cAAc,UAAU,6BAA6B;GACzD,IAAI,MAAM,WAAW,GAAG,MAAM,QAAQ;GACtC,MAAM,QAAQ,IAAI,eAAe,UAAU;GAC3C,IAAI,CAAC,OACH,MAAM,IAAI,YAAY,aAAa,aAAa,aAAa,WAAW,cAAc;GAGxF,MAAM,aAAa,IAAI,IAAI,cAAc,CAAC,CAAC,UAAU,UAAU;GAC/D,MAAM,OAAO,MAAM,KAAK,SAAS;IAC/B,MAAM,QACJ,OAAO,SAAS,WACZ,WAAW,QACX,WAAW,MAAM,cAAc,UAAU,IAAI,iBAAiB,KAAK,YAAY;IACrF,IAAI,CAAC,OACH,MAAM,IAAI,YACR,aACA,aACA,aAAa,WAAW,mBAC1B;IAEF,OAAO,MAAM;GACf,CAAC;GACD,MAAM,WAAW,WAAW,QAAQ,SAAS;GAC7C,OAAO,QAAQ,YAAY;IAGzB,MAAM,QAAQ,MAAM,gBAClB,IAAI,YAAY,QAAQ,QAAQ,MAAM,MAAM,QAAQ,IAAI,CAAC,CAC3D;IACA,OAAO,YAAY,OAAO,UAAU,QAAQ,MAAM;GACpD,GAAG,OAAO;EACZ;EAEA,WAAW,OAAO,OAAO,UAAU,CAAC,MAAM;GACxC,IAAI,cAAc,UAAU,oBAAoB;GAChD,IAAI,cAAc,UAAU,oBAAoB;GAChD,MAAM,OAAO,OAAO,KAAK;GACzB,MAAM,WAAW,QAAQ,YACrB,WAAW,QAAQ,SAAS,IAC5B,EAAE,OAAO,KAAK,KAAK,SAAS,GAAI;GACpC,OAAO,QAAQ,YAAY;IACzB,MAAM,QAAQ,MAAM,IAAI,YAAY,QAAQ,QAAQ,IAAI,IAAI,MAAM,QAAQ,IAAI,CAAC;IAC/E,OAAO,YAAY,OAAO,UAAU,QAAQ,MAAM;GACpD,GAAG,OAAO;EACZ;EAEA,SAAS,OAAO,OAAO,YAAY;GACjC,IAAI,cAAc,UAAU,kBAAkB;GAC9C,MAAM,OAAO,OAAO,KAAK;GACzB,OAAO,cAAc,IAAI,YAAY,SAAS,QAAQ,IAAI,IAAI,MAAM,QAAQ,IAAI,CAAC,GAAG,OAAO;EAC7F;CAES,EAAE;AACf;;;;;;;;ACxOA,MAAa,uBACX,aAAa;CACX,IAAI;CACJ,OAAO;CACP,OAAO;CACP,QAAQ;AACV,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@embedpdf/plugin-page-edit",
-  "version": "3.0.0-next.14",
+  "version": "3.0.0-next.15",
   "private": false,
-  "description": "Document-scoped page-edit capability: PON-addressed rotate/move/delete over the engine DocumentHandle. Owns relative→absolute rotation so framework adapters never re-derive it; the home for pending/undo/gating state.",
+  "description": "Document-scoped page-edit capability: ref-addressed rotate/move/delete/insert over the engine DocumentHandle. Owns relative→absolute rotation and placement resolution so framework adapters never re-derive them.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,7 +22,7 @@
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core": "3.0.0-next.14"
+    "@embedpdf/core": "3.0.0-next.15"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/dist/contract-BnXi11KD.d.cts

@@ -1,82 +0,0 @@
-import { AbortablePromise, PageDeleteResult, PageInsertResult, PageMoveResult, PageObjectNumber, PageRotateResult, PageRotation, PdfSize } from "@embedpdf/core";
-//#region src/types.d.ts
-/**
- * Where added pages land. The PON anchors are the thumbnail gestures ("+
- * after this page") and stay correct across a concurrent reorder between
- * click and call — a raw index does not; `index` remains for absolute
- * positions ("at the start"). Omitted → append. Resolved to the engine's
- * index wire by the capability at call time, from the registry.
- */
-type PagePlacement = {
-  after: PageObjectNumber;
-} | {
-  before: PageObjectNumber;
-} | {
-  index: number;
-};
-/**
- * Structural page edits, addressed by durable PON (never display index — an
- * index shifts the moment a sibling is moved or deleted). Mirrors the engine's
- * `DocumentPagesService` 1:1, with one addition the engine can't have: the
- * relative `rotateBy` gesture. The engine wire is always ABSOLUTE; turning a
- * "+90° on this thumbnail" click into an absolute value needs the page's
- * current rotation, so that read+arithmetic lives HERE — once — instead of
- * being re-derived in every framework adapter's click handler.
- *
- * Document-scoped: rotation is shared document metadata, so editing through the
- * sidebar lens and seeing it in the main lens is automatic (both read the same
- * registry, which the kernel keeps in sync from the engine's event stream).
- */
-interface PageEditCapability {
-  /**
-   * Whether this caller is authorized to perform structural page edits —
-   * `effectiveScope` includes `doc.pages.assemble` (PDF bit 11). UIs gate
-   * ALL their edit affordances on this, the add verbs included (rotate,
-   * move, delete, addBlank, and insert share the one capability); the
-   * engine independently enforces the same capability and throws
-   * `PermissionDenied` if a call slips through.
-   */
-  canEdit(): boolean;
-  /**
-   * Rotate a SINGLE page by a relative quarter-turn — the per-thumbnail button
-   * gesture. Reads the page's current rotation from the registry and forwards
-   * the resulting absolute rotation to the engine.
-   */
-  rotateBy(pon: PageObjectNumber, delta: 90 | -90): AbortablePromise<PageRotateResult>;
-  /**
-   * Set the ABSOLUTE rotation of one or more pages to a single shared value —
-   * the multi-select gesture. Maps 1:1 to the engine.
-   */
-  setRotation(pons: PageObjectNumber[], rotation: PageRotation): AbortablePromise<PageRotateResult>;
-  /** Reorder pages (by PON) as a contiguous block starting at `destIndex`. */
-  move(pons: PageObjectNumber[], destIndex: number): AbortablePromise<PageMoveResult>;
-  /** Delete pages by PON. The engine rejects deleting every page. */
-  delete(pons: PageObjectNumber[]): AbortablePromise<PageDeleteResult>;
-  /**
-   * Create blank pages — gate the affordance on `canEdit()`, like every
-   * other structure verb (the add verbs share the `doc.pages.assemble`
-   * capability and are mandatory on the engine contract). `size` defaults
-   * to the page the new pages sit beside — the anchor for PON placements,
-   * else the insertion point's predecessor, else the last page — so "add
-   * page" matches the document without an A4-vs-Letter guess. That default
-   * is a registry read, which is why it lives HERE and the engine wire
-   * stays explicit (the `rotateBy` law). `count` defaults to 1.
-   */
-  addBlank(opts?: {
-    size?: PdfSize;
-    count?: number;
-    placement?: PagePlacement;
-  }): AbortablePromise<PageInsertResult>;
-  /**
-   * Copy every page of a standalone PDF (`bytes`) in at the placement —
-   * the merge/import gesture. Forwards to `pages.insert`; the inserted
-   * copies get fresh PONs, returned in insertion order.
-   */
-  insert(bytes: Uint8Array | ArrayBuffer, opts?: {
-    placement?: PagePlacement;
-  }): AbortablePromise<PageInsertResult>;
-}
-declare const PageEditToken: import("@embedpdf/core").CapabilityToken<PageEditCapability>;
-//#endregion
-export { PageEditToken as n, PageEditCapability as t };
-//# sourceMappingURL=contract-BnXi11KD.d.cts.map

package/dist/contract-BnXi11KD.d.ts

@@ -1,82 +0,0 @@
-import { AbortablePromise, PageDeleteResult, PageInsertResult, PageMoveResult, PageObjectNumber, PageRotateResult, PageRotation, PdfSize } from "@embedpdf/core";
-//#region src/types.d.ts
-/**
- * Where added pages land. The PON anchors are the thumbnail gestures ("+
- * after this page") and stay correct across a concurrent reorder between
- * click and call — a raw index does not; `index` remains for absolute
- * positions ("at the start"). Omitted → append. Resolved to the engine's
- * index wire by the capability at call time, from the registry.
- */
-type PagePlacement = {
-  after: PageObjectNumber;
-} | {
-  before: PageObjectNumber;
-} | {
-  index: number;
-};
-/**
- * Structural page edits, addressed by durable PON (never display index — an
- * index shifts the moment a sibling is moved or deleted). Mirrors the engine's
- * `DocumentPagesService` 1:1, with one addition the engine can't have: the
- * relative `rotateBy` gesture. The engine wire is always ABSOLUTE; turning a
- * "+90° on this thumbnail" click into an absolute value needs the page's
- * current rotation, so that read+arithmetic lives HERE — once — instead of
- * being re-derived in every framework adapter's click handler.
- *
- * Document-scoped: rotation is shared document metadata, so editing through the
- * sidebar lens and seeing it in the main lens is automatic (both read the same
- * registry, which the kernel keeps in sync from the engine's event stream).
- */
-interface PageEditCapability {
-  /**
-   * Whether this caller is authorized to perform structural page edits —
-   * `effectiveScope` includes `doc.pages.assemble` (PDF bit 11). UIs gate
-   * ALL their edit affordances on this, the add verbs included (rotate,
-   * move, delete, addBlank, and insert share the one capability); the
-   * engine independently enforces the same capability and throws
-   * `PermissionDenied` if a call slips through.
-   */
-  canEdit(): boolean;
-  /**
-   * Rotate a SINGLE page by a relative quarter-turn — the per-thumbnail button
-   * gesture. Reads the page's current rotation from the registry and forwards
-   * the resulting absolute rotation to the engine.
-   */
-  rotateBy(pon: PageObjectNumber, delta: 90 | -90): AbortablePromise<PageRotateResult>;
-  /**
-   * Set the ABSOLUTE rotation of one or more pages to a single shared value —
-   * the multi-select gesture. Maps 1:1 to the engine.
-   */
-  setRotation(pons: PageObjectNumber[], rotation: PageRotation): AbortablePromise<PageRotateResult>;
-  /** Reorder pages (by PON) as a contiguous block starting at `destIndex`. */
-  move(pons: PageObjectNumber[], destIndex: number): AbortablePromise<PageMoveResult>;
-  /** Delete pages by PON. The engine rejects deleting every page. */
-  delete(pons: PageObjectNumber[]): AbortablePromise<PageDeleteResult>;
-  /**
-   * Create blank pages — gate the affordance on `canEdit()`, like every
-   * other structure verb (the add verbs share the `doc.pages.assemble`
-   * capability and are mandatory on the engine contract). `size` defaults
-   * to the page the new pages sit beside — the anchor for PON placements,
-   * else the insertion point's predecessor, else the last page — so "add
-   * page" matches the document without an A4-vs-Letter guess. That default
-   * is a registry read, which is why it lives HERE and the engine wire
-   * stays explicit (the `rotateBy` law). `count` defaults to 1.
-   */
-  addBlank(opts?: {
-    size?: PdfSize;
-    count?: number;
-    placement?: PagePlacement;
-  }): AbortablePromise<PageInsertResult>;
-  /**
-   * Copy every page of a standalone PDF (`bytes`) in at the placement —
-   * the merge/import gesture. Forwards to `pages.insert`; the inserted
-   * copies get fresh PONs, returned in insertion order.
-   */
-  insert(bytes: Uint8Array | ArrayBuffer, opts?: {
-    placement?: PagePlacement;
-  }): AbortablePromise<PageInsertResult>;
-}
-declare const PageEditToken: import("@embedpdf/core").CapabilityToken<PageEditCapability>;
-//#endregion
-export { PageEditToken as n, PageEditCapability as t };
-//# sourceMappingURL=contract-BnXi11KD.d.ts.map

package/dist/contract-BsNelyd8.js

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

package/dist/contract-BsNelyd8.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"contract-BsNelyd8.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import {\n  createCapabilityToken,\n  type AbortablePromise,\n  type PageObjectNumber,\n  type PageRotation,\n  type PageRotateResult,\n  type PageMoveResult,\n  type PageDeleteResult,\n  type PageInsertResult,\n  type PdfSize,\n} from '@embedpdf/core';\n\n/**\n * Where added pages land. The PON anchors are the thumbnail gestures (\"+\n * after this page\") and stay correct across a concurrent reorder between\n * click and call — a raw index does not; `index` remains for absolute\n * positions (\"at the start\"). Omitted → append. Resolved to the engine's\n * index wire by the capability at call time, from the registry.\n */\nexport type PagePlacement =\n  | { after: PageObjectNumber }\n  | { before: PageObjectNumber }\n  | { index: number };\n\n/**\n * Structural page edits, addressed by durable PON (never display index — an\n * index shifts the moment a sibling is moved or deleted). Mirrors the engine's\n * `DocumentPagesService` 1:1, with one addition the engine can't have: the\n * relative `rotateBy` gesture. The engine wire is always ABSOLUTE; turning a\n * \"+90° on this thumbnail\" click into an absolute value needs the page's\n * current rotation, so that read+arithmetic lives HERE — once — instead of\n * being re-derived in every framework adapter's click handler.\n *\n * Document-scoped: rotation is shared document metadata, so editing through the\n * sidebar lens and seeing it in the main lens is automatic (both read the same\n * registry, which the kernel keeps in sync from the engine's event stream).\n */\nexport interface PageEditCapability {\n  /**\n   * Whether this caller is authorized to perform structural page edits —\n   * `effectiveScope` includes `doc.pages.assemble` (PDF bit 11). UIs gate\n   * ALL their edit affordances on this, the add verbs included (rotate,\n   * move, delete, addBlank, and insert share the one capability); the\n   * engine independently enforces the same capability and throws\n   * `PermissionDenied` if a call slips through.\n   */\n  canEdit(): boolean;\n\n  /**\n   * Rotate a SINGLE page by a relative quarter-turn — the per-thumbnail button\n   * gesture. Reads the page's current rotation from the registry and forwards\n   * the resulting absolute rotation to the engine.\n   */\n  rotateBy(pon: PageObjectNumber, delta: 90 | -90): AbortablePromise<PageRotateResult>;\n\n  /**\n   * Set the ABSOLUTE rotation of one or more pages to a single shared value —\n   * the multi-select gesture. Maps 1:1 to the engine.\n   */\n  setRotation(pons: PageObjectNumber[], rotation: PageRotation): AbortablePromise<PageRotateResult>;\n\n  /** Reorder pages (by PON) as a contiguous block starting at `destIndex`. */\n  move(pons: PageObjectNumber[], destIndex: number): AbortablePromise<PageMoveResult>;\n\n  /** Delete pages by PON. The engine rejects deleting every page. */\n  delete(pons: PageObjectNumber[]): AbortablePromise<PageDeleteResult>;\n\n  /**\n   * Create blank pages — gate the affordance on `canEdit()`, like every\n   * other structure verb (the add verbs share the `doc.pages.assemble`\n   * capability and are mandatory on the engine contract). `size` defaults\n   * to the page the new pages sit beside — the anchor for PON placements,\n   * else the insertion point's predecessor, else the last page — so \"add\n   * page\" matches the document without an A4-vs-Letter guess. That default\n   * is a registry read, which is why it lives HERE and the engine wire\n   * stays explicit (the `rotateBy` law). `count` defaults to 1.\n   */\n  addBlank(opts?: {\n    size?: PdfSize;\n    count?: number;\n    placement?: PagePlacement;\n  }): AbortablePromise<PageInsertResult>;\n\n  /**\n   * Copy every page of a standalone PDF (`bytes`) in at the placement —\n   * the merge/import gesture. Forwards to `pages.insert`; the inserted\n   * copies get fresh PONs, returned in insertion order.\n   */\n  insert(\n    bytes: Uint8Array | ArrayBuffer,\n    opts?: { placement?: PagePlacement },\n  ): AbortablePromise<PageInsertResult>;\n}\n\nexport const PageEditToken = createCapabilityToken<PageEditCapability>('page-edit');\n"],"mappings":";;AA8FA,MAAa,gBAAgB,sBAA0C,WAAW"}

package/dist/contract-UeGRCn-t.cjs

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

package/dist/contract-UeGRCn-t.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"contract-UeGRCn-t.cjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["import {\n  createCapabilityToken,\n  type AbortablePromise,\n  type PageObjectNumber,\n  type PageRotation,\n  type PageRotateResult,\n  type PageMoveResult,\n  type PageDeleteResult,\n  type PageInsertResult,\n  type PdfSize,\n} from '@embedpdf/core';\n\n/**\n * Where added pages land. The PON anchors are the thumbnail gestures (\"+\n * after this page\") and stay correct across a concurrent reorder between\n * click and call — a raw index does not; `index` remains for absolute\n * positions (\"at the start\"). Omitted → append. Resolved to the engine's\n * index wire by the capability at call time, from the registry.\n */\nexport type PagePlacement =\n  | { after: PageObjectNumber }\n  | { before: PageObjectNumber }\n  | { index: number };\n\n/**\n * Structural page edits, addressed by durable PON (never display index — an\n * index shifts the moment a sibling is moved or deleted). Mirrors the engine's\n * `DocumentPagesService` 1:1, with one addition the engine can't have: the\n * relative `rotateBy` gesture. The engine wire is always ABSOLUTE; turning a\n * \"+90° on this thumbnail\" click into an absolute value needs the page's\n * current rotation, so that read+arithmetic lives HERE — once — instead of\n * being re-derived in every framework adapter's click handler.\n *\n * Document-scoped: rotation is shared document metadata, so editing through the\n * sidebar lens and seeing it in the main lens is automatic (both read the same\n * registry, which the kernel keeps in sync from the engine's event stream).\n */\nexport interface PageEditCapability {\n  /**\n   * Whether this caller is authorized to perform structural page edits —\n   * `effectiveScope` includes `doc.pages.assemble` (PDF bit 11). UIs gate\n   * ALL their edit affordances on this, the add verbs included (rotate,\n   * move, delete, addBlank, and insert share the one capability); the\n   * engine independently enforces the same capability and throws\n   * `PermissionDenied` if a call slips through.\n   */\n  canEdit(): boolean;\n\n  /**\n   * Rotate a SINGLE page by a relative quarter-turn — the per-thumbnail button\n   * gesture. Reads the page's current rotation from the registry and forwards\n   * the resulting absolute rotation to the engine.\n   */\n  rotateBy(pon: PageObjectNumber, delta: 90 | -90): AbortablePromise<PageRotateResult>;\n\n  /**\n   * Set the ABSOLUTE rotation of one or more pages to a single shared value —\n   * the multi-select gesture. Maps 1:1 to the engine.\n   */\n  setRotation(pons: PageObjectNumber[], rotation: PageRotation): AbortablePromise<PageRotateResult>;\n\n  /** Reorder pages (by PON) as a contiguous block starting at `destIndex`. */\n  move(pons: PageObjectNumber[], destIndex: number): AbortablePromise<PageMoveResult>;\n\n  /** Delete pages by PON. The engine rejects deleting every page. */\n  delete(pons: PageObjectNumber[]): AbortablePromise<PageDeleteResult>;\n\n  /**\n   * Create blank pages — gate the affordance on `canEdit()`, like every\n   * other structure verb (the add verbs share the `doc.pages.assemble`\n   * capability and are mandatory on the engine contract). `size` defaults\n   * to the page the new pages sit beside — the anchor for PON placements,\n   * else the insertion point's predecessor, else the last page — so \"add\n   * page\" matches the document without an A4-vs-Letter guess. That default\n   * is a registry read, which is why it lives HERE and the engine wire\n   * stays explicit (the `rotateBy` law). `count` defaults to 1.\n   */\n  addBlank(opts?: {\n    size?: PdfSize;\n    count?: number;\n    placement?: PagePlacement;\n  }): AbortablePromise<PageInsertResult>;\n\n  /**\n   * Copy every page of a standalone PDF (`bytes`) in at the placement —\n   * the merge/import gesture. Forwards to `pages.insert`; the inserted\n   * copies get fresh PONs, returned in insertion order.\n   */\n  insert(\n    bytes: Uint8Array | ArrayBuffer,\n    opts?: { placement?: PagePlacement },\n  ): AbortablePromise<PageInsertResult>;\n}\n\nexport const PageEditToken = createCapabilityToken<PageEditCapability>('page-edit');\n"],"mappings":";AA8FA,MAAa,iBAAA,2BAAA,CAAA,CAAA,sBAAA,CAA0D,WAAW"}