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

package/dist/{contract-dl4LfrRX.d.ts → contract-IN8rk5LG.d.cts}

@@ -1,19 +1,8 @@
-import { OperationOptions, PageRef, PdfRotation, PdfRotation as PdfRotation$1, PdfSize, PdfSize as PdfSize$1 } from "@embedpdf/core";
+import { OperationOptions, PagePosition, PagePosition as PagePosition$1, 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[];
@@ -21,8 +10,8 @@ interface PageEditInsertResult {
 /** 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 position?: PagePosition;
+  /** The page size, in points. Default: the size of the page the new pages go next to. */
   readonly size?: PdfSize;
   /** How many blank pages. Default 1. */
   readonly count?: number;
@@ -32,18 +21,26 @@ 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;
+  readonly position?: PagePosition;
 }
 /** Options of the verbs that copy pages in: `insertFromDocument()` and `duplicate()`. */
-interface PagePlacementOptions extends OperationOptions {
-  readonly placement?: PagePlacement;
+interface PagePositionOptions extends OperationOptions {
+  readonly position?: PagePosition;
 }
 /**
- * Every edit runs in the order it was called, after the edits before it.
+ * Every edit is one change: one step of the history, so undo brings the
+ * pages back as they were, a deleted page with its annotations under its old
+ * ref. It shows once the engine answers. Edits apply in the order they were
+ * called, except that the verbs that copy pages first (`duplicate()`,
+ * `insertFromDocument()`, `insertFromBytes()` with `pageIndexes`) take their
+ * place once the copy is made.
+ *
  * 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.
+ * session may not do it, `not-found` for a page the document doesn't have and
+ * `invalid-input` for no pages; a refusal changes nothing. An edit the engine
+ * refuses rejects with the engine's reason. When the `signal` fires the verb
+ * rejects `operation-cancelled`: before its change is made nothing changes,
+ * after it the change still applies.
  */
 interface PageEditCapability {
   /** Whether rotating, reordering, deleting and inserting pages is allowed (`doc.pages.assemble`). */
@@ -53,12 +50,20 @@ interface PageEditCapability {
    * `duplicate()` and `insertFromDocument()` need it.
    */
   canExtract(): boolean;
-  /** Turn each page by a quarter or half turn from its own rotation. */
+  /** The selected pages, in the order they were selected; pages the document no longer has drop out. */
+  getSelected(): readonly PageRef[];
+  /** Make these pages the selection; `[]` clears it. Pages the document doesn't have are left out. */
+  select(pages: readonly (PageRef | number)[]): void;
+  /**
+   * Turn each page by a quarter or half turn from its rotation, the one it
+   * has once the edits on their way apply: two quick quarter turns are a
+   * half turn.
+   */
   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>;
+  /** Move pages to `position`; several pages keep their order and land together. */
+  reorder(pages: readonly (PageRef | number)[], position: PagePosition, 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. */
@@ -69,12 +74,18 @@ interface PageEditCapability {
    * 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. */
+  insertFromDocument(documentId: string, pages: readonly (PageRef | number)[], options?: PagePositionOptions): Promise<PageEditInsertResult>;
+  /**
+   * Copy pages as they show, with the edits on their way, right after the
+   * last of them unless `position` says otherwise.
+   */
+  duplicate(pages: readonly (PageRef | number)[], options?: PagePositionOptions): Promise<PageEditInsertResult>;
+  /**
+   * Copy pages into a new PDF, as they show with the edits on their way, 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
+export { PagePosition$1 as a, PdfSize$1 as c, PageInsertFromBytesOptions as i, PageEditToken as l, PageEditInsertResult as n, PagePositionOptions as o, PageInsertBlankOptions as r, PdfRotation$1 as s, PageEditCapability as t };
+//# sourceMappingURL=contract-IN8rk5LG.d.cts.map

package/dist/{contract-dl4LfrRX.d.cts → contract-IN8rk5LG.d.ts}

@@ -1,19 +1,8 @@
-import { OperationOptions, PageRef, PdfRotation, PdfRotation as PdfRotation$1, PdfSize, PdfSize as PdfSize$1 } from "@embedpdf/core";
+import { OperationOptions, PagePosition, PagePosition as PagePosition$1, 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[];
@@ -21,8 +10,8 @@ interface PageEditInsertResult {
 /** 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 position?: PagePosition;
+  /** The page size, in points. Default: the size of the page the new pages go next to. */
   readonly size?: PdfSize;
   /** How many blank pages. Default 1. */
   readonly count?: number;
@@ -32,18 +21,26 @@ 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;
+  readonly position?: PagePosition;
 }
 /** Options of the verbs that copy pages in: `insertFromDocument()` and `duplicate()`. */
-interface PagePlacementOptions extends OperationOptions {
-  readonly placement?: PagePlacement;
+interface PagePositionOptions extends OperationOptions {
+  readonly position?: PagePosition;
 }
 /**
- * Every edit runs in the order it was called, after the edits before it.
+ * Every edit is one change: one step of the history, so undo brings the
+ * pages back as they were, a deleted page with its annotations under its old
+ * ref. It shows once the engine answers. Edits apply in the order they were
+ * called, except that the verbs that copy pages first (`duplicate()`,
+ * `insertFromDocument()`, `insertFromBytes()` with `pageIndexes`) take their
+ * place once the copy is made.
+ *
  * 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.
+ * session may not do it, `not-found` for a page the document doesn't have and
+ * `invalid-input` for no pages; a refusal changes nothing. An edit the engine
+ * refuses rejects with the engine's reason. When the `signal` fires the verb
+ * rejects `operation-cancelled`: before its change is made nothing changes,
+ * after it the change still applies.
  */
 interface PageEditCapability {
   /** Whether rotating, reordering, deleting and inserting pages is allowed (`doc.pages.assemble`). */
@@ -53,12 +50,20 @@ interface PageEditCapability {
    * `duplicate()` and `insertFromDocument()` need it.
    */
   canExtract(): boolean;
-  /** Turn each page by a quarter or half turn from its own rotation. */
+  /** The selected pages, in the order they were selected; pages the document no longer has drop out. */
+  getSelected(): readonly PageRef[];
+  /** Make these pages the selection; `[]` clears it. Pages the document doesn't have are left out. */
+  select(pages: readonly (PageRef | number)[]): void;
+  /**
+   * Turn each page by a quarter or half turn from its rotation, the one it
+   * has once the edits on their way apply: two quick quarter turns are a
+   * half turn.
+   */
   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>;
+  /** Move pages to `position`; several pages keep their order and land together. */
+  reorder(pages: readonly (PageRef | number)[], position: PagePosition, 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. */
@@ -69,12 +74,18 @@ interface PageEditCapability {
    * 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. */
+  insertFromDocument(documentId: string, pages: readonly (PageRef | number)[], options?: PagePositionOptions): Promise<PageEditInsertResult>;
+  /**
+   * Copy pages as they show, with the edits on their way, right after the
+   * last of them unless `position` says otherwise.
+   */
+  duplicate(pages: readonly (PageRef | number)[], options?: PagePositionOptions): Promise<PageEditInsertResult>;
+  /**
+   * Copy pages into a new PDF, as they show with the edits on their way, 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
+export { PagePosition$1 as a, PdfSize$1 as c, PageInsertFromBytesOptions as i, PageEditToken as l, PageEditInsertResult as n, PagePositionOptions as o, PageInsertBlankOptions as r, PdfRotation$1 as s, PageEditCapability as t };
+//# sourceMappingURL=contract-IN8rk5LG.d.ts.map

package/dist/contract.d.cts

@@ -1,2 +1,2 @@
-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 };
+import { a as PagePosition, c as PdfSize, i as PageInsertFromBytesOptions, l as PageEditToken, n as PageEditInsertResult, o as PagePositionOptions, r as PageInsertBlankOptions, s as PdfRotation, t as PageEditCapability } from "./contract-IN8rk5LG.cjs";
+export { PageEditCapability, PageEditInsertResult, PageEditToken, PageInsertBlankOptions, PageInsertFromBytesOptions, type PagePosition, PagePositionOptions, type PdfRotation, type PdfSize };

package/dist/contract.d.ts

@@ -1,2 +1,2 @@
-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 };
+import { a as PagePosition, c as PdfSize, i as PageInsertFromBytesOptions, l as PageEditToken, n as PageEditInsertResult, o as PagePositionOptions, r as PageInsertBlankOptions, s as PdfRotation, t as PageEditCapability } from "./contract-IN8rk5LG.js";
+export { PageEditCapability, PageEditInsertResult, PageEditToken, PageInsertBlankOptions, PageInsertFromBytesOptions, type PagePosition, PagePositionOptions, type PdfRotation, type PdfSize };

package/dist/index.cjs

@@ -1,15 +1,28 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_contract = require("./contract-B4DeVaKv.cjs");
 let _embedpdf_core = require("@embedpdf/core");
+//#region src/model.ts
+const initialPageEditState = () => ({ selected: [] });
+/** The selection becomes `refs`, each page once. */
+function selected(state, refs) {
+	const numbers = refs.map((ref) => ref.objectNumber);
+	const unique = refs.filter((_ref, i) => numbers.indexOf(numbers[i]) === i);
+	return unique.length === state.selected.length && unique.every((ref, i) => ref.objectNumber === state.selected[i].objectNumber) ? state : {
+		...state,
+		selected: unique
+	};
+}
+//#endregion
 //#region src/controller.ts
 /**
-* 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.
+* The page-edit controller: page edits that take refs or indexes, and the
+* page selection. Turning a page relative to its own rotation, and fixing a
+* position'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.
+* A verb refuses before anything starts (permission, pages, position), then
+* stages its edit as one change on the document's queue (`ctx.changes`): one
+* step of the history, sent after everything staged before it. The page list
+* shows it once the engine answers; nothing predicts pages yet.
 */
 /** Inserting, rotating and deleting pages (PDF permission bit 4 or 11). The engine enforces it too. */
 const ASSEMBLE = "doc.pages.assemble";
@@ -20,9 +33,9 @@ const LETTER_SIZE = {
 	width: 612,
 	height: 792
 };
+const NO_PAGES = Object.freeze([]);
+const NO_LAYOUTS = Object.freeze([]);
 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 {
@@ -31,7 +44,7 @@ function createPageEditController(ctx) {
 			throw (0, _embedpdf_core.toPluginError)("page-edit", error);
 		}
 	};
-	const registry = () => ctx.document()?.pages ?? [];
+	const registry = () => ctx.document()?.pages ?? NO_LAYOUTS;
 	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
@@ -41,17 +54,14 @@ function createPageEditController(ctx) {
 		if (pages.length === 0) throw noPages();
 		return pages.map((page) => ctx.pageOf(page).ref);
 	};
-	/**
-	* A placement as the engine's position, its page fixed when the verb is
-	* called, like the verb's own pages. Default `'end'`.
-	*/
-	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 };
+	/** A position, its page checked when the verb is called, like the verb's own pages. Default `'end'`. */
+	const positionOf = (position) => {
+		if (!position || position === "start" || position === "end") return position ?? "end";
+		if ("after" in position) return { after: ctx.pageOf(position.after).ref };
+		return { before: ctx.pageOf(position.before).ref };
 	};
 	/**
-	* Default blank-page size: the page the placement names, else the page the
+	* Default blank-page size: the page the position names, else the page the
 	* new ones go next to (the first or the last), else Letter.
 	*/
 	const sizeAt = (position) => {
@@ -60,83 +70,188 @@ function createPageEditController(ctx) {
 		if (pages.length === 0) return LETTER_SIZE;
 		return (position === "start" ? pages[0] : pages[pages.length - 1]).size;
 	};
-	/** 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 };
+	const getSelected = (0, _embedpdf_core.memo)(() => [registry(), ctx.state.get().selected], (pages, refs) => {
+		if (refs.length === 0) return NO_PAGES;
+		const present = new Set(pages.map((page) => page.ref.objectNumber));
+		return refs.filter((ref) => present.has(ref.objectNumber));
+	});
+	const select = (pages) => {
+		const refs = pages.flatMap((page) => {
+			const found = ctx.getPage(page);
+			return found ? [found.ref] : [];
+		});
+		ctx.state.update(selected, refs);
+	};
+	/** Refuse before anything starts: without the right, or once the caller cancelled. */
+	const refuse = (permission, operation, options) => {
+		ctx.assertAllowed(permission, operation);
+		if (options?.signal?.aborted) throw new _embedpdf_core.PluginError("operation-cancelled", "page-edit", `${operation} was cancelled`);
+	};
+	/**
+	* Stage one user action: one change, one step of the history. Its label
+	* counts the pages it acts on, when the verb knows how many.
+	*/
+	const stageChange = (verb, count, ops, undo) => {
+		const label = count === null ? { key: `pages.${verb}` } : {
+			key: `pages.${verb}`,
+			count
+		};
+		return ctx.changes.stage({
+			label,
+			ops,
+			...undo ? { undo } : {}
+		});
+	};
+	/** The engine's answer to a staged change: its first item. */
+	const answer = async (change, options) => {
+		try {
+			return (await ctx.cancellable(options?.signal, change.result)).items[0];
+		} catch (error) {
+			throw (0, _embedpdf_core.toPluginError)("page-edit", error);
+		}
+	};
+	/** What an insert's answer names: the new pages. */
+	const inserted = async (change, options) => {
+		const item = await answer(change, options);
+		return { pages: "insertedPages" in item ? item.insertedPages : NO_PAGES };
+	};
+	/**
+	* A page's rotation once this session's changes on their way apply: the
+	* last rotation one of them gives it, else the page's own. What a turn
+	* starts from, so two quick quarter turns are a half turn.
+	*/
+	const rotationOf = (ref) => {
+		let rotation = ctx.pageOf(ref).rotation;
+		for (const change of ctx.changes.pending()) for (const op of change.shows) {
+			if (op.type !== "pages.rotate") continue;
+			if (op.pages.some((page) => page.objectNumber === ref.objectNumber)) rotation = op.rotation;
+		}
+		return rotation;
+	};
+	/**
+	* Rotate pages as one change: one op per rotation they end up with. What
+	* undoing it looks like is each page turned back, so a turn right after an
+	* undo starts from where the undo leaves the page.
+	*/
+	const rotate = (refs, rotationAfter) => {
+		const after = /* @__PURE__ */ new Map();
+		const before = /* @__PURE__ */ new Map();
+		for (const ref of refs) {
+			const add = (groups, rotation) => groups.set(rotation, [...groups.get(rotation) ?? [], ref]);
+			add(before, rotationOf(ref));
+			add(after, rotationAfter(ref));
+		}
+		const opsOf = (groups) => [...groups].map(([rotation, pages]) => ({
+			type: "pages.rotate",
+			pages,
+			rotation
+		}));
+		return stageChange("rotate", refs.length, opsOf(after), opsOf(before));
+	};
+	/**
+	* The pages as they show: every change on its way sent and answered first,
+	* so a copy holds the edits made before it.
+	*/
+	const settled = async (options) => {
+		ctx.changes.sendHolds();
+		await ctx.cancellable(options?.signal, ctx.changes.whenSettled());
+	};
+	/** Copy pages of this document out, as they show. */
+	const extractShown = async (refs, options) => {
+		await settled(options);
+		return ctx.cancellable(options?.signal, ctx.doc.pages.extract([...refs]));
+	};
+	/** Stage the insert of a PDF's pages; resolves the new pages. */
+	const insertBytes = (verb, count, bytes, position, options) => {
+		const source = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+		const change = stageChange(verb, count, [{
+			type: "pages.insert",
+			source,
+			position
+		}]);
+		return inserted(change, options);
+	};
+	/** Some pages of a PDF: open the bytes beside the document and extract them. */
+	const pagesOfBytes = async (bytes, pageIndexes, 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;
+			});
+			return await mapErrors(() => ctx.cancellable(signal, source.pages.extract(refs)));
+		} finally {
+			await source.close();
+		}
 	};
 	return { api: {
 		canEdit: () => ctx.allows(ASSEMBLE),
 		canExtract: () => ctx.allows(DOWNLOAD),
+		getSelected,
+		select,
 		rotateBy: async (pages, delta, options) => {
-			ctx.assertAllowed(ASSEMBLE, "pageEdit.rotateBy");
+			refuse(ASSEMBLE, "pageEdit.rotateBy", options);
 			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);
+			const change = rotate(refs, (ref) => ((rotationOf(ref) + delta) % 360 + 360) % 360);
+			await answer(change, 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);
+			refuse(ASSEMBLE, "pageEdit.setRotation", options);
+			const change = rotate(refsOf(pages), () => rotation);
+			await answer(change, options);
 		},
-		reorder: async (pages, placement, options) => {
-			ctx.assertAllowed(ASSEMBLE, "pageEdit.reorder");
+		reorder: async (pages, position, options) => {
+			refuse(ASSEMBLE, "pageEdit.reorder", options);
 			const refs = refsOf(pages);
-			const position = positionOf(placement);
-			await enqueue(() => ctx.cancellable(options?.signal, ctx.doc.pages.reorder(refs, position)), options);
+			const change = stageChange("reorder", refs.length, [{
+				type: "pages.reorder",
+				pages: refs,
+				position: positionOf(position)
+			}]);
+			await answer(change, options);
 		},
 		delete: async (pages, options) => {
-			ctx.assertAllowed(ASSEMBLE, "pageEdit.delete");
+			refuse(ASSEMBLE, "pageEdit.delete", options);
 			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);
+			const change = stageChange("delete", refs.length, [{
+				type: "pages.delete",
+				pages: refs
+			}]);
+			await answer(change, options);
 		},
 		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({
+			refuse(ASSEMBLE, "pageEdit.insertBlank", options);
+			const position = positionOf(options.position);
+			const count = options.count ?? 1;
+			const size = options.size ?? sizeAt(position);
+			const change = stageChange("insertBlank", count, [{
+				type: "pages.insertBlank",
+				spec: {
 					size,
-					count: options.count
-				}, position))).insertedPages };
-			}, options);
+					count
+				},
+				position
+			}]);
+			return inserted(change, options);
 		},
 		insertFromBytes: async (bytes, options = {}) => {
-			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertFromBytes");
-			const position = positionOf(options.placement);
+			refuse(ASSEMBLE, "pageEdit.insertFromBytes", options);
+			const position = positionOf(options.position);
 			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);
+			const source = pageIndexes ? await pagesOfBytes(bytes, pageIndexes, signal) : bytes;
+			return insertBytes("insert", pageIndexes?.length ?? null, source, position, options);
 		},
 		insertFromDocument: async (documentId, pages, options = {}) => {
-			ctx.assertAllowed(ASSEMBLE, "pageEdit.insertFromDocument");
+			refuse(ASSEMBLE, "pageEdit.insertFromDocument", options);
 			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`);
@@ -146,44 +261,59 @@ function createPageEditController(ctx) {
 				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);
+			const position = positionOf(options.position);
+			const bytes = await mapErrors(() => ctx.cancellable(options.signal, other.pages.extract(refs)));
+			return insertBytes("insert", refs.length, bytes, position, options);
 		},
 		duplicate: async (pages, options = {}) => {
-			ctx.assertAllowed(ASSEMBLE, "pageEdit.duplicate");
+			refuse(ASSEMBLE, "pageEdit.duplicate", options);
 			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);
+			const position = options.position ? positionOf(options.position) : { after: refs[refs.length - 1] };
+			const bytes = await extractShown(refs, options);
+			return insertBytes("duplicate", refs.length, bytes, position, 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);
+			refuse(DOWNLOAD, "pageEdit.extract", options);
+			return extractShown(refsOf(pages), options);
 		}
 	} };
 }
 //#endregion
 //#region src/page-edit.plugin.ts
 /**
-* 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.
+* Document-scoped: the document's page edits, each one change of its
+* history, and which of its pages are selected. 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,
+	state: initialPageEditState,
 	create: createPageEditController
 });
 //#endregion
+//#region src/state.ts
+/**
+* The pages page's State table as code: what `usePageEditState()` returns,
+* and the same fields in every other framework.
+*/
+const pageEditState = (0, _embedpdf_core.defineState)(require_contract.PageEditToken, {
+	read: (pageEdit) => ({
+		selected: pageEdit.getSelected(),
+		canEdit: pageEdit.canEdit(),
+		canExtract: pageEdit.canExtract()
+	}),
+	empty: {
+		selected: [],
+		canEdit: false,
+		canExtract: false
+	}
+});
+//#endregion
 exports.PageEditToken = require_contract.PageEditToken;
 exports.pageEditPlugin = pageEditPlugin;
+exports.pageEditState = pageEditState;
 
 //# sourceMappingURL=index.cjs.map