@embedpdf/plugin-render 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.cjs

@@ -1,72 +1,255 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-Bvlo2Ukp.cjs");
+const require_contract = require("./contract-CGcu-84H.cjs");
+const require_contract_host = require("./contract/host.cjs");
 let _embedpdf_core = require("@embedpdf/core");
 let _embedpdf_core_geometry = require("@embedpdf/core-geometry");
-//#region src/paint-plan.ts
-const EMPTY_TILE_PLAN = {
-	engaged: false,
-	paint: [],
-	fetching: [],
-	stamp: "empty"
+//#region src/appearance-store.ts
+/**
+* The engine's pictures of a page's annotations or form widgets, shared
+* between the views and plugins that draw them. One ask is one key (the
+* page, the family, the scale and the owner's items at their versions):
+* asks with the same key share one fetch.
+*
+* Consumer aborts are refcounted, as in the raster store: a view that leaves
+* detaches without stopping the fetch for the others; the fetch stops only
+* when the last one leaves before it resolved.
+*
+* Kept for undo:
+* - the last {@link SETS_KEPT} sets of each page and family: an undo that
+*   brings a page back to an earlier set asks the engine for nothing;
+* - each item's last pictures ({@link RecentPictures}), a while after it left
+*   its page: an undo that brings it back shows them at once.
+*/
+var AppearanceStore = class {
+	constructor() {
+		this.entries = /* @__PURE__ */ new Map();
+		this.kept = /* @__PURE__ */ new Map();
+	}
+	/** `group` names the page and family; `key` the whole ask. */
+	acquire(group, key, fetch, signal) {
+		const existing = this.entries.get(key);
+		if (existing) {
+			if (existing.resolved) this.keep(group, key);
+			return this.attach(key, existing, signal);
+		}
+		const entry = {
+			group,
+			promise: void 0,
+			refs: 0,
+			abort: new AbortController(),
+			resolved: false
+		};
+		entry.promise = fetch(entry.abort.signal).then((pictures) => {
+			entry.resolved = true;
+			this.keep(group, key);
+			return pictures;
+		}, (error) => {
+			this.drop(key, entry);
+			throw error;
+		});
+		entry.promise.catch(() => {});
+		this.entries.set(key, entry);
+		return this.attach(key, entry, signal);
+	}
+	/** Keep `key` as the group's newest set, letting go of the oldest beyond the few kept. */
+	keep(group, key) {
+		const kept = (this.kept.get(group) ?? []).filter((each) => each !== key);
+		kept.push(key);
+		const gone = kept.splice(0, Math.max(0, kept.length - 4));
+		this.kept.set(group, kept);
+		for (const old of gone) {
+			const entry = this.entries.get(old);
+			if (entry && entry.refs <= 0) this.entries.delete(old);
+		}
+	}
+	isKept(group, key) {
+		return this.kept.get(group)?.includes(key) ?? false;
+	}
+	attach(key, entry, signal) {
+		if (signal?.aborted) return Promise.reject(abortReason$1(signal));
+		entry.refs += 1;
+		if (!signal) {
+			const release = () => this.release(key, entry);
+			entry.promise.then(release, release);
+			return entry.promise;
+		}
+		let settled = false;
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				if (settled) return;
+				settled = true;
+				entry.refs -= 1;
+				if (entry.refs <= 0 && !entry.resolved) {
+					entry.abort.abort(abortReason$1(signal));
+					this.drop(key, entry);
+				}
+				reject(abortReason$1(signal));
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			entry.promise.then((pictures) => {
+				if (settled) return;
+				settled = true;
+				this.release(key, entry);
+				signal.removeEventListener("abort", onAbort);
+				resolve(pictures);
+			}, (error) => {
+				if (settled) return;
+				settled = true;
+				this.release(key, entry);
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			});
+		});
+	}
+	/** A consumer let go: a set no longer kept goes with the last one. */
+	release(key, entry) {
+		entry.refs -= 1;
+		if (entry.refs <= 0 && entry.resolved && !this.isKept(entry.group, key)) this.drop(key, entry);
+	}
+	drop(key, entry) {
+		if (this.entries.get(key) === entry) this.entries.delete(key);
+	}
 };
-/** The ×2 client pyramid used for lattice deployments without a tiles block. */
-const DEFAULT_TILE_PYRAMID = [
-	1,
-	2,
-	4,
-	8,
-	16,
-	32
-];
-function resolveRenderOptions(options) {
-	const tiles = options.tiles === false ? void 0 : options.tiles;
-	return {
-		fullPage: {
-			maxWidth: options.fullPage?.maxWidth ?? 640,
-			maxWidthExplicit: options.fullPage?.maxWidth !== void 0,
-			quantize: options.fullPage?.quantize ?? "exact"
-		},
-		tiles: {
-			enabled: options.tiles !== false,
-			size: tiles?.size ?? 512,
-			quantize: tiles?.quantize ?? "exact",
-			maxScale: tiles?.maxScale ?? 128,
-			bleedPx: tiles?.bleed ?? 1,
-			engageAt: tiles?.engageAt,
-			prefetchMargin: tiles?.prefetch?.margin ?? .5,
-			velocityBias: tiles?.prefetch?.velocityBias ?? true,
-			settleMs: tiles?.settleMs ?? 150,
-			fadeMs: tiles?.fadeMs ?? 0,
-			fallbackPyramid: DEFAULT_TILE_PYRAMID
-		},
-		format: options.format,
-		quality: options.quality,
-		debug: options.debug ?? false
-	};
+/**
+* The last pictures of each item (all its states), the newest {@link ITEMS_KEPT}
+* items per family, kept after the item left its page.
+*/
+var RecentPictures = class {
+	constructor() {
+		this.families = /* @__PURE__ */ new Map();
+	}
+	/** A fetch's pictures, grouped by item: each replaces what its item had. */
+	remember(family, pictures, keyOf) {
+		const items = this.families.get(family) ?? /* @__PURE__ */ new Map();
+		const byItem = /* @__PURE__ */ new Map();
+		for (const picture of pictures) {
+			const key = keyOf(picture);
+			byItem.set(key, [...byItem.get(key) ?? [], picture]);
+		}
+		for (const [key, itemPictures] of byItem) {
+			items.delete(key);
+			items.set(key, itemPictures);
+		}
+		while (items.size > 200) items.delete(items.keys().next().value);
+		this.families.set(family, items);
+	}
+	of(family, key) {
+		return this.families.get(family)?.get(key) ?? [];
+	}
+};
+function abortReason$1(signal) {
+	return signal.reason ?? new DOMException("aborted", "AbortError");
+}
+//#endregion
+//#region src/invalidation.ts
+const placedPages = (widgets) => widgets.flatMap((widget) => widget.page ? [widget.page.objectNumber] : []);
+const changeOf = (pages, scope) => pages.length ? {
+	pages: [...new Set(pages)],
+	scope
+} : null;
+/**
+* The pages a form fact repaints. Every form fact names the widgets whose
+* look changed or that went (`meta.changedWidgets`), each with its page; the
+* widget rows it carries, and a deleted widget's page, are counted too. An
+* unplaced widget (`page: null`) has no pixels to repaint.
+*/
+function formPagesOf(event) {
+	const pages = placedPages(event.meta.changedWidgets);
+	if ("widgets" in event) pages.push(...placedPages(event.widgets));
+	if ("page" in event && event.page) pages.push(event.page.objectNumber);
+	return pages;
+}
+function pixelChangeOf(event, allPageObjectNumbers) {
+	switch (event.type) {
+		case "annotations.created":
+		case "annotations.updated":
+		case "annotations.deleted":
+		case "annotations.restored":
+		case "annotations.reordered": return changeOf([event.page.objectNumber], "annotations");
+		case "forms.valueSet":
+		case "forms.created":
+		case "forms.updated":
+		case "forms.deleted":
+		case "forms.restored":
+		case "forms.widgetAdded":
+		case "forms.widgetRemoved":
+		case "forms.widgetDeleted":
+		case "forms.widgetRestored":
+		case "forms.widgetUpdated":
+		case "forms.widgetsReordered": return changeOf(formPagesOf(event), "fields");
+		case "forms.repaired": return changeOf(allPageObjectNumbers(), "fields");
+		case "signatures.completed": return changeOf(event.signature.widget ? placedPages([event.signature.widget]) : [], "fields");
+		case "redaction.applied":
+		case "pages.flattened": return changeOf(event.results.filter((result) => result.status === "applied").map((result) => result.page.objectNumber), "content");
+		case "annotations.flattened": return changeOf(event.results.some((result) => result.status === "applied") ? [event.page.objectNumber] : [], "content");
+		case "stream.desynced": return changeOf(allPageObjectNumbers(), "content");
+		default: return null;
+	}
+}
+//#endregion
+//#region src/model.ts
+const initialRenderState = () => ({
+	contentEpochs: {},
+	annotationEpochs: {},
+	fieldEpochs: {}
+});
+const bump = (epochs, pageObjectNumbers) => {
+	const next = { ...epochs };
+	for (const pageObjectNumber of pageObjectNumbers) next[pageObjectNumber] = (next[pageObjectNumber] ?? 0) + 1;
+	return next;
+};
+/**
+* Bump the pages' versions in the ledger the scope names. A content fact
+* bumps only the content ledger; every picture counts content (see
+* {@link renderEpochOf}), which is how content invalidation reaches them all.
+*/
+function invalidatePages(state, pageObjectNumbers, scope) {
+	if (pageObjectNumbers.length === 0) return state;
+	switch (scope) {
+		case "content": return {
+			...state,
+			contentEpochs: bump(state.contentEpochs, pageObjectNumbers)
+		};
+		case "annotations": return {
+			...state,
+			annotationEpochs: bump(state.annotationEpochs, pageObjectNumbers)
+		};
+		case "fields": return {
+			...state,
+			fieldEpochs: bump(state.fieldEpochs, pageObjectNumbers)
+		};
+	}
+}
+/** The version of one picture of a page: its content, plus the annotations and form fields it draws. */
+function renderEpochOf(state, pageObjectNumber, layers) {
+	return (state.contentEpochs[pageObjectNumber] ?? 0) + (layers.includeAnnotations ? state.annotationEpochs[pageObjectNumber] ?? 0 : 0) + (layers.includeFormFields ? state.fieldEpochs[pageObjectNumber] ?? 0 : 0);
 }
+/** What a picture draws, as one key part: `a1f0` draws annotations and no form fields. */
+const layersKeyOf = (layers) => `a${layers.includeAnnotations ? 1 : 0}f${layers.includeFormFields ? 1 : 0}`;
 //#endregion
 //#region src/raster-store.ts
 /**
-* Client-side mirror of the server's one-door read-through: per-key
-* SINGLEFLIGHT + cost-budgeted LRU over encoded page images.
+* The client-side counterpart of the server's read-through cache: per-key
+* singleflight + cost-budgeted LRU over encoded page images.
 *
-* The key is the raster's canonical identity (conformed viewport +
-* annotations flag + epoch — see `renderSourceKey`), so the render points do
+* The key is the raster's canonical identity (for page rasters: width,
+* annotations flag, epoch and format, built by `rasterKey` in the
+* controller; for tiles: `TileManager`'s tile key), so the render points do
 * the caching work: every ask at one point is the same key, and
 * re-crossings (zoom 1280 → 2560 → back) resolve instantly from the LRU
 * instead of re-rendering. Epoch bumps mint new keys; stale-epoch entries
 * age out through the LRU (they are never re-requested).
 *
-* The budget is COST, approximately bytes: an entry costs its encoded byte
+* The budget is cost, approximately bytes: an entry costs its encoded byte
 * length when the handle carries bytes (local), its pixel count as a
 * decoded-order estimate otherwise (URL-backed cloud handles), and 1 when
 * neither is known. Entry counts lie — a 512² webp tile and a BMP full page
 * differ by 100× — and long deep-zoom sessions cycle hundreds of tile keys,
 * so the budget is what actually bounds memory.
 *
-* Consumer aborts are REFCOUNTED: a caller abandoning a fetch (camera moved,
+* Consumer aborts are refcounted: a caller abandoning a fetch (camera moved,
 * layer unmounted) detaches without killing it for other consumers; the
-* underlying engine call aborts only when the LAST in-flight consumer leaves.
+* underlying engine call aborts only when the last in-flight consumer leaves.
 * Resolved entries are kept (evictable by LRU) — an abort after resolution
 * is a no-op by design.
 */
@@ -96,9 +279,9 @@ var RasterStore = class {
 			this.total += entry.cost;
 			this.evict();
 			return handle;
-		}, (err) => {
+		}, (error) => {
 			this.drop(key, entry);
-			throw err;
+			throw error;
 		});
 		entry.promise.catch(() => {});
 		this.entries.set(key, entry);
@@ -147,12 +330,12 @@ var RasterStore = class {
 				entry.refs -= 1;
 				signal.removeEventListener("abort", onAbort);
 				resolve(handle);
-			}, (err) => {
+			}, (error) => {
 				if (settled) return;
 				settled = true;
 				entry.refs -= 1;
 				signal.removeEventListener("abort", onAbort);
-				reject(err);
+				reject(error);
 			});
 		});
 	}
@@ -164,7 +347,7 @@ var RasterStore = class {
 	}
 	evict() {
 		if (this.total <= this.maxCost) return;
-		const candidates = [...this.entries.entries()].filter(([, e]) => e.refs <= 0 && e.handle !== void 0).sort((a, b) => a[1].used - b[1].used);
+		const candidates = [...this.entries.entries()].filter(([, entry]) => entry.refs <= 0 && entry.handle !== void 0).sort((left, right) => left[1].used - right[1].used);
 		for (const [key, entry] of candidates) {
 			if (this.total <= this.maxCost) return;
 			this.drop(key, entry);
@@ -183,11 +366,11 @@ function abortReason(signal) {
 }
 //#endregion
 //#region src/strategy.ts
-const ascending = (values) => [...values].sort((a, b) => a - b);
+const ascending = (values) => [...values].sort((left, right) => left - right);
 /** Rung list capped by the budget — always keeps at least the smallest rung. */
 const capWidths = (widths, maxWidth) => {
 	const sorted = ascending(widths);
-	const kept = sorted.filter((w) => w <= maxWidth);
+	const kept = sorted.filter((width) => width <= maxWidth);
 	return kept.length ? kept : sorted.slice(0, 1);
 };
 function resolveStrategy(policy, options) {
@@ -211,15 +394,16 @@ function resolveStrategy(policy, options) {
 	};
 }
 /**
-* The ONE base-sizing function — four callers: `renderPage`,
-* `renderSourceKey`, `conformViewport`, and tile engagement. Exact mode
+* The one base-sizing function. Its callers: the controller's
+* `conformViewport` (which `renderSource` and `getSourceKey` go through)
+* and tile engagement in the tile manager. Exact mode
 * returns the (settled) demand itself up to the budget; ladder mode snaps
-* UP and caps at the top rung.
+* up and caps at the top rung.
 */
 function baseAskWidth(strategy, demandWidth) {
 	const wanted = Math.max(1, Math.round(demandWidth));
 	if (strategy.widths === null) return Math.min(wanted, strategy.maxWidth);
-	return strategy.widths.find((w) => w >= wanted) ?? strategy.widths[strategy.widths.length - 1];
+	return strategy.widths.find((width) => width >= wanted) ?? strategy.widths[strategy.widths.length - 1];
 }
 //#endregion
 //#region src/tiles.ts
@@ -239,22 +423,22 @@ const tileSpanPt = (grid) => grid.tileSize / grid.scale;
 */
 function tilesInRect(grid, page, rect) {
 	const span = tileSpanPt(grid);
-	const x0 = Math.max(0, Math.floor(rect.x / span));
-	const y0 = Math.max(0, Math.floor(rect.y / span));
-	const x1 = Math.min(grid.cols - 1, Math.ceil((rect.x + rect.width) / span) - 1);
-	const y1 = Math.min(grid.rows - 1, Math.ceil((rect.y + rect.height) / span) - 1);
-	const out = [];
-	for (let iy = y0; iy <= y1; iy++) for (let ix = x0; ix <= x1; ix++) out.push({
+	const firstColumn = Math.max(0, Math.floor(rect.x / span));
+	const firstRow = Math.max(0, Math.floor(rect.y / span));
+	const lastColumn = Math.min(grid.cols - 1, Math.ceil((rect.x + rect.width) / span) - 1);
+	const lastRow = Math.min(grid.rows - 1, Math.ceil((rect.y + rect.height) / span) - 1);
+	const coords = [];
+	for (let iy = firstRow; iy <= lastRow; iy++) for (let ix = firstColumn; ix <= lastColumn; ix++) coords.push({
 		ix,
 		iy
 	});
-	return out;
+	return coords;
 }
 /** Paint rect: y-down page points, clamped to the page edge. */
-function tilePaintRect(grid, page, c) {
+function tilePaintRect(grid, page, coord) {
 	const span = tileSpanPt(grid);
-	const x = c.ix * span;
-	const y = c.iy * span;
+	const x = coord.ix * span;
+	const y = coord.iy * span;
 	return {
 		x,
 		y,
@@ -262,43 +446,33 @@ function tilePaintRect(grid, page, c) {
 		height: Math.min(span, page.height - y)
 	};
 }
-/** Engine target rect (y-UP PDF user space, top > bottom) for an arbitrary
-*  y-down page-point rect. */
-function toEngineRect(page, rect) {
-	return {
-		left: rect.x,
-		right: rect.x + rect.width,
-		top: page.height - rect.y,
-		bottom: page.height - (rect.y + rect.height)
-	};
-}
 /**
-* Expand a paint rect by `pt` page points per side, clamped to the page —
-* the tile BLEED. Neighboring tiles rendered with bleed overlap by twice
+* Expand a paint rect by `amountPt` page points per side, clamped to the page —
+* the tile bleed. Neighboring tiles rendered with bleed overlap by twice
 * this amount, and the overlapping strips contain identical content (same
 * page region, same scale), so every img edge composites over its
 * neighbor's duplicated pixels instead of the backdrop: no AA hairlines,
 * no bilinear edge smear, at any CSS stretch.
 */
-function bleedRect(rect, pt, page) {
-	const x = Math.max(0, rect.x - pt);
-	const y = Math.max(0, rect.y - pt);
+function bleedRect(rect, amountPt, page) {
+	const x = Math.max(0, rect.x - amountPt);
+	const y = Math.max(0, rect.y - amountPt);
 	return {
 		x,
 		y,
-		width: Math.min(page.width, rect.x + rect.width + pt) - x,
-		height: Math.min(page.height, rect.y + rect.height + pt) - y
+		width: Math.min(page.width, rect.x + rect.width + amountPt) - x,
+		height: Math.min(page.height, rect.y + rect.height + amountPt) - y
 	};
 }
 /**
-* Does a set of PAINTED want-level tiles cover `region` (y-down points)?
+* Does a set of painted want-level tiles cover `region` (y-down points)?
 * The retention release check: a retained source may leave the paint list
 * once its visible footprint answers true here. Pure index arithmetic on
 * the aligned grid — the whole reason the pyramid is aligned.
 */
 function regionCovered(grid, page, region, isPainted) {
 	if (region.width <= 0 || region.height <= 0) return true;
-	for (const c of tilesInRect(grid, page, region)) if (!isPainted(c)) return false;
+	for (const coord of tilesInRect(grid, page, region)) if (!isPainted(coord)) return false;
 	return true;
 }
 /**
@@ -308,26 +482,26 @@ function regionCovered(grid, page, region, isPainted) {
 * velocity is just data.
 */
 function inflateRect(rect, margin, velocity) {
-	const mx = rect.width * margin;
-	const my = rect.height * margin;
-	let left = mx;
-	let right = mx;
-	let up = my;
-	let down = my;
+	const marginX = rect.width * margin;
+	const marginY = rect.height * margin;
+	let left = marginX;
+	let right = marginX;
+	let up = marginY;
+	let down = marginY;
 	if (velocity) {
 		if (velocity.dx > 0) {
-			right = mx * 2;
-			left = mx / 2;
+			right = marginX * 2;
+			left = marginX / 2;
 		} else if (velocity.dx < 0) {
-			left = mx * 2;
-			right = mx / 2;
+			left = marginX * 2;
+			right = marginX / 2;
 		}
 		if (velocity.dy > 0) {
-			down = my * 2;
-			up = my / 2;
+			down = marginY * 2;
+			up = marginY / 2;
 		} else if (velocity.dy < 0) {
-			up = my * 2;
-			down = my / 2;
+			up = marginY * 2;
+			down = marginY / 2;
 		}
 	}
 	return {
@@ -337,74 +511,70 @@ function inflateRect(rect, margin, velocity) {
 		height: rect.height + up + down
 	};
 }
-/** Snap UP through a pyramid's sorted scales; cap at the top. */
+/** Snap up through a pyramid's sorted scales; cap at the top. */
 function snapToPyramid(scales, needed) {
-	const sorted = [...scales].sort((a, b) => a - b);
-	return sorted.find((s) => s >= needed) ?? sorted[sorted.length - 1];
+	const sorted = [...scales].sort((left, right) => left - right);
+	return sorted.find((scale) => scale >= needed) ?? sorted[sorted.length - 1];
 }
 //#endregion
 //#region src/tile-manager.ts
+/** One state entry per view of a page (see {@link TileManager}'s `pages`). */
+const stateKey = (view, pageObjectNumber) => `${view}\u0000${pageObjectNumber}`;
+/** Backpressure: raw rasters in flight at once (render + encode transit). */
+const MAX_IN_FLIGHT = 8;
+/** Stage-less (no visibleRect) demand is capped to this many whole-page tiles. */
+const STAGELESS_TILE_CAP = 64;
 /**
-* The tile retention state machine. One instance per
-* plugin instance (per document), all levels and pages in one place, over
-* the SAME RasterStore the base renders use.
+* The tile retention state machine. One instance per plugin instance (per
+* document), all levels and pages in one place, over the same RasterStore
+* the base renders use.
 *
-* Invariant it enforces: every screen region paints the sharpest PAINTED
+* Invariant it enforces: every screen region paints the sharpest painted
 * pixels available; quality per region only goes up until the want set
 * resolves. Mechanics:
-*   - want vs paint: `plan()` schedules fetches for the want set (P0
-*     visible first — center-out — then P1 prefetch when P0 is fully
-*     resolved) and returns a paint list drawn ONLY from resolved entries —
-*     current level AND retained older generations.
-*   - release-on-occlusion: when a want-level tile reports PAINTED (after the
+*   - want vs paint: `plan()` queues the want set (visible tiles first,
+*     center-out, then the prefetch ring once every visible tile resolved)
+*     and returns a paint list drawn only from resolved entries: the
+*     current level and retained older generations.
+*   - one line for every view and page: a transit slot goes to an on-screen
+*     tile of any page before a tile of any prefetch ring, so a ring never
+*     takes the slots an on-screen tile needs. The engine ranks the tiles it
+*     is given by where each one is on screen.
+*   - release-on-occlusion: when a want-level tile reports painted (after the
 *     layer's first presentation opportunity), retained sources whose
-*     visible footprint is
-*     covered by painted want tiles leave the paint list. Their bytes stay
-*     in the RasterStore (demotion, not eviction) — zoom-back re-promotes
-*     from cache.
+*     visible footprint is covered by painted want tiles leave the paint
+*     list. Their bytes stay in the RasterStore (demotion, not eviction), so
+*     zooming back re-promotes from cache.
 *   - epoch exception: an invalidation bump means retained pixels are
-*     WRONG — everything of the old epoch drops immediately.
+*     wrong, so everything of the old epoch drops immediately.
 *
-* Levels come from the resolved STRATEGY (policy ∧ options): a pyramid
-* under a lattice (or the opt-in client ladder), the EXACT settled scale
-* under exact mode — where the level identity is the demand's device width
+* Levels come from the resolved strategy (policy ∧ options): a pyramid
+* under a lattice (or the opt-in client ladder), the exact settled scale
+* under exact mode, where the level identity is the demand's device width
 * across the page, so keys stay integer and stable. The retention/coverage
 * math is generic over any mix of retained scales.
 *
-* `plan()` is called from selectors: it MUST NOT dispatch. Fetch kickoff
-* is idempotent (the store singleflights); resolution handlers dispatch
-* the wake-up (`onAdvance`) that makes subscribed layers recompute.
+* `plan()` never wakes readers itself: its callers do, once, when the
+* returned plan changed. Fetch kickoff is idempotent (the store
+* singleflights); resolution handlers call `onAdvance`, which re-plans the
+* page and wakes subscribed layers, and hand the freed slot on.
 */
-/** One state entry per VIEW-of-page (see the class doc). */
-const stateKey = (view, pon) => `${view}\u0000${pon}`;
-/** Backpressure: raw rasters in flight at once (render + encode transit). */
-const MAX_IN_FLIGHT = 8;
-/** Stage-less (no visibleRect) demand is capped to this many whole-page tiles. */
-const STAGELESS_TILE_CAP = 64;
 var TileManager = class {
 	constructor(deps) {
 		this.deps = deps;
 		this.pages = /* @__PURE__ */ new Map();
-		this.strategyMemo = null;
+		this.strategy = (0, _embedpdf_core.memo)(() => [this.deps.getPolicy(), this.deps.getOptions()], (policy, options) => resolveStrategy(policy, options));
 		this.inFlight = 0;
 		this.warnedStageless = false;
 	}
-	strategy() {
-		const policy = this.deps.getPolicy();
-		if (this.strategyMemo?.policy !== policy) this.strategyMemo = {
-			policy,
-			strategy: resolveStrategy(policy, this.deps.options)
-		};
-		return this.strategyMemo.strategy;
-	}
-	plan(view, pon, demand, includeAnnotations) {
-		const { options } = this.deps;
-		if (!options.tiles.enabled) return EMPTY_TILE_PLAN;
+	plan(view, pageObjectNumber, demand, layers) {
+		const options = this.deps.getOptions();
+		if (!options.tiles.enabled) return require_contract.EMPTY_TILE_PLAN;
 		const strategy = this.strategy();
-		const page = this.deps.getPageSize(pon);
-		if (!page) return EMPTY_TILE_PLAN;
-		const epoch = this.deps.getEpoch(pon, includeAnnotations);
-		const state = this.pageState(pon, view);
+		const page = this.deps.getPageSize(pageObjectNumber);
+		if (!page) return require_contract.EMPTY_TILE_PLAN;
+		const epoch = this.deps.getEpoch(pageObjectNumber, layers);
+		const state = this.pageState(pageObjectNumber, view);
 		if (state.epoch !== epoch) {
 			this.abortAll(state);
 			state.entries.clear();
@@ -418,15 +588,16 @@ var TileManager = class {
 		const deficit = demand.desiredDeviceWidth / supplied;
 		if (deficit <= strategy.engageAt) {
 			if (state.entries.size || state.wantScale !== null) {
-				this.deps.debug?.(`disengage pon=${pon} (deficit ${deficit.toFixed(2)})`);
+				this.deps.debug?.(`disengage page=${pageObjectNumber} (deficit ${deficit.toFixed(2)})`);
 				this.abortAll(state);
 				state.entries.clear();
 				state.failedKeys.clear();
 				state.wantScale = null;
 				state.wantWidth = null;
 				state.planCache = null;
+				this.pump();
 			}
-			return EMPTY_TILE_PLAN;
+			return require_contract.EMPTY_TILE_PLAN;
 		}
 		let wantWidth;
 		let wantScale;
@@ -445,7 +616,7 @@ var TileManager = class {
 					console.warn(`[render] stage-less tile demand of ${Math.round(demand.desiredDeviceWidth)} device px would tile the whole page — clamped to ${maxStagelessWidth}. Supply a visibleRect (host the page in a Stage) for sharp deep zoom.`);
 				}
 				if (strategy.pyramid) {
-					const fitting = strategy.pyramid.filter((s) => Math.round(s * page.width) <= maxStagelessWidth);
+					const fitting = strategy.pyramid.filter((scale) => Math.round(scale * page.width) <= maxStagelessWidth);
 					wantScale = fitting.length ? fitting[fitting.length - 1] : strategy.pyramid[0];
 					wantWidth = Math.round(wantScale * page.width);
 				} else {
@@ -462,12 +633,12 @@ var TileManager = class {
 			height: page.height
 		};
 		state.lastVisible = visible;
-		const p0 = tilesInRect(grid, page, visible);
+		const visibleCoords = tilesInRect(grid, page, visible);
 		const ring = inflateRect(visible, options.tiles.prefetchMargin, options.tiles.velocityBias ? demand.velocity : void 0);
-		const p0Keys = new Set(p0.map((c) => coordKey(c)));
-		const p1 = tilesInRect(grid, page, ring).filter((c) => !p0Keys.has(coordKey(c)));
-		this.schedule(pon, state, page, grid, wantScale, wantWidth, includeAnnotations, epoch, p0, p1, visible);
-		if (this.releaseCovered(pon, state, page, includeAnnotations)) {
+		const visibleKeys = new Set(visibleCoords.map((coord) => coordKey(coord)));
+		const prefetchCoords = tilesInRect(grid, page, ring).filter((coord) => !visibleKeys.has(coordKey(coord)));
+		this.schedule(pageObjectNumber, state, page, grid, wantScale, wantWidth, layers, epoch, visibleCoords, prefetchCoords, visible);
+		if (this.releaseCovered(pageObjectNumber, state, page, layers)) {
 			state.version += 1;
 			state.planCache = null;
 		}
@@ -476,11 +647,11 @@ var TileManager = class {
 		const paint = [];
 		const fetching = [];
 		const stale = [];
-		const bleedPx = this.deps.options.tiles.bleedPx;
+		const bleedPx = this.deps.getOptions().tiles.bleedPx;
 		for (const entry of state.entries.values()) {
-			const visIntersect = (0, _embedpdf_core_geometry.intersectRects)(entry.rect, visible);
+			const visiblePart = (0, _embedpdf_core_geometry.intersectRects)(entry.rect, visible);
 			if (entry.resolved) {
-				if (visIntersect.width > 0 && visIntersect.height > 0) {
+				if (visiblePart.width > 0 && visiblePart.height > 0) {
 					const handle = this.deps.store.peek(entry.key);
 					if (!handle) {
 						stale.push(entry.key);
@@ -498,9 +669,10 @@ var TileManager = class {
 		}
 		for (const key of stale) state.entries.delete(key);
 		const rank = /* @__PURE__ */ new Map();
-		for (const s of [...new Set(paint.map((p) => p.scale))].sort((a, b) => a - b)) rank.set(s, rank.size);
-		for (const p of paint) p.z = rank.get(p.scale);
-		paint.sort((a, b) => a.z - b.z || a.key.localeCompare(b.key));
+		const scales = [...new Set(paint.map((source) => source.scale))];
+		for (const scale of scales.sort((left, right) => left - right)) rank.set(scale, rank.size);
+		for (const source of paint) source.z = rank.get(source.scale);
+		paint.sort((left, right) => left.z - right.z || left.key.localeCompare(right.key));
 		const plan = {
 			engaged: true,
 			paint,
@@ -515,41 +687,46 @@ var TileManager = class {
 		return plan;
 	}
 	/** The layer's painted report: this key's pixels had a presentation opportunity. */
-	sourcePainted(view, pon, key) {
-		const state = this.pages.get(stateKey(view, pon));
+	sourcePainted(view, pageObjectNumber, key) {
+		const state = this.pages.get(stateKey(view, pageObjectNumber));
 		const entry = state?.entries.get(key);
 		if (!state || !entry || entry.painted) return;
 		entry.painted = true;
-		const page = this.deps.getPageSize(pon);
-		if (page) this.releaseCovered(pon, state, page, annotationsOf(key));
+		const page = this.deps.getPageSize(pageObjectNumber);
+		if (page) this.releaseCovered(pageObjectNumber, state, page, layersOfKey(key));
 		state.version += 1;
 		state.planCache = null;
-		this.deps.onAdvance(pon);
+		this.deps.onAdvance(pageObjectNumber);
 	}
 	/**
 	* The inverse report: this key's <img> left the DOM (pan-away, plan drop),
-	* so its pixels are NOT currently compositable. Without this, a tile that
+	* so its pixels are not currently compositable. Without this, a tile that
 	* unmounts and later remounts is still counted as painted while its new
 	* <img> re-decodes — and an adjacent fresh `sourcePainted` could release
 	* retained coarse coverage over a region that momentarily has no sharp
-	* pixels. Painted is a statement about the SCREEN, so it follows the DOM.
+	* pixels. Painted is a statement about the screen, so it follows the DOM.
 	*/
-	sourceUnpainted(view, pon, key) {
-		const entry = this.pages.get(stateKey(view, pon))?.entries.get(key);
+	sourceUnpainted(view, pageObjectNumber, key) {
+		const entry = this.pages.get(stateKey(view, pageObjectNumber))?.entries.get(key);
 		if (entry) entry.painted = false;
 	}
-	/** A lens unmounted its tile plane: stop fetching, drop bookkeeping.
-	*  Resolved bytes stay in the RasterStore for a re-mount. */
-	releasePage(view, pon) {
-		const state = this.pages.get(stateKey(view, pon));
+	/** A lens stopped painting tiles for the page (it left the view, or its
+	*  layer paints none): stop fetching, drop bookkeeping. Resolved bytes stay
+	*  in the RasterStore for a re-mount. */
+	releasePage(view, pageObjectNumber) {
+		const state = this.pages.get(stateKey(view, pageObjectNumber));
 		if (!state) return;
 		this.abortAll(state);
-		this.pages.delete(stateKey(view, pon));
+		this.pages.delete(stateKey(view, pageObjectNumber));
+		this.pump();
 	}
-	pageState(pon, view) {
-		let state = this.pages.get(stateKey(view, pon));
+	pageState(pageObjectNumber, view) {
+		let state = this.pages.get(stateKey(view, pageObjectNumber));
 		if (!state) {
 			state = {
+				view,
+				pageObjectNumber,
+				queue: null,
 				epoch: -1,
 				wantScale: null,
 				wantWidth: null,
@@ -557,22 +734,23 @@ var TileManager = class {
 				failedKeys: /* @__PURE__ */ new Set(),
 				version: 0,
 				planCache: null,
-				settleTimer: null,
+				cancelSettle: null,
 				pendingLevel: null,
 				lastVisible: null
 			};
-			this.pages.set(stateKey(view, pon), state);
+			this.pages.set(stateKey(view, pageObjectNumber), state);
 		}
 		return state;
 	}
-	schedule(pon, state, page, grid, wantScale, wantWidth, includeAnnotations, epoch, p0, p1, visible) {
-		const { options } = this.deps;
+	schedule(pageObjectNumber, state, page, grid, wantScale, wantWidth, layers, epoch, visibleCoords, prefetchCoords, visible) {
+		const options = this.deps.getOptions();
 		const firstEngage = state.wantWidth === null;
 		const levelChanged = state.wantWidth !== null && state.wantWidth !== wantWidth;
 		if (levelChanged) state.failedKeys.clear();
 		state.wantScale = wantScale;
 		state.wantWidth = wantWidth;
-		const wanted = new Set([...p0, ...p1].map((c) => this.tileKey(pon, wantWidth, c, includeAnnotations, epoch)));
+		const keyOf = (coord) => this.tileKey(pageObjectNumber, wantWidth, coord, layers, epoch);
+		const wanted = new Set([...visibleCoords, ...prefetchCoords].map(keyOf));
 		for (const [key, entry] of state.entries) {
 			if (wanted.has(key)) continue;
 			if (!entry.resolved) {
@@ -581,110 +759,154 @@ var TileManager = class {
 				state.entries.delete(key);
 			} else if (entry.scale === wantScale) state.entries.delete(key);
 		}
-		const cx = visible.x + visible.width / 2;
-		const cy = visible.y + visible.height / 2;
+		const centerX = visible.x + visible.width / 2;
+		const centerY = visible.y + visible.height / 2;
 		const span = grid.tileSize / grid.scale;
-		const orderedP0 = [...p0].sort((a, b) => {
-			const da = (a.ix + .5) * span - cx;
-			const db = (b.ix + .5) * span - cx;
-			const ea = (a.iy + .5) * span - cy;
-			const eb = (b.iy + .5) * span - cy;
-			return da * da + ea * ea - (db * db + eb * eb);
-		});
+		const distanceToCenter = (coord) => {
+			const dx = (coord.ix + .5) * span - centerX;
+			const dy = (coord.iy + .5) * span - centerY;
+			return dx * dx + dy * dy;
+		};
+		const orderedVisible = [...visibleCoords].sort((left, right) => distanceToCenter(left) - distanceToCenter(right));
 		const kickoff = () => {
-			if (this.ensureFetches(pon, state, page, grid, wantWidth, includeAnnotations, epoch, orderedP0)) this.ensureFetches(pon, state, page, grid, wantWidth, includeAnnotations, epoch, p1);
+			state.queue = {
+				coords: orderedVisible.every((coord) => {
+					const key = keyOf(coord);
+					return state.failedKeys.has(key) || state.entries.get(key)?.resolved === true;
+				}) ? [...orderedVisible, ...prefetchCoords] : orderedVisible,
+				ringFrom: orderedVisible.length,
+				next: 0,
+				page,
+				grid,
+				wantWidth,
+				layers,
+				epoch
+			};
+			this.pump();
 		};
 		if (levelChanged && options.tiles.settleMs > 0) {
-			this.deps.debug?.(`arm settle pon=${pon} level=${wantWidth}`);
+			this.deps.debug?.(`arm settle page=${pageObjectNumber} level=${wantWidth}`);
+			state.queue = null;
 			state.pendingLevel = wantWidth;
-			if (state.settleTimer !== null) clearTimeout(state.settleTimer);
-			state.settleTimer = setTimeout(() => {
-				state.settleTimer = null;
-				this.deps.debug?.(`settle fired pon=${pon} level=${wantWidth} current=${state.pendingLevel === wantWidth}`);
+			state.cancelSettle?.();
+			state.cancelSettle = this.deps.after(options.tiles.settleMs, () => {
+				state.cancelSettle = null;
+				this.deps.debug?.(`settle fired page=${pageObjectNumber} level=${wantWidth} current=${state.pendingLevel === wantWidth}`);
 				if (state.pendingLevel === wantWidth) kickoff();
-			}, options.tiles.settleMs);
+			});
 			return;
 		}
-		if (state.settleTimer !== null && !levelChanged && !firstEngage) {
-			clearTimeout(state.settleTimer);
-			state.settleTimer = null;
+		if (state.cancelSettle !== null && !levelChanged && !firstEngage) {
+			state.cancelSettle();
+			state.cancelSettle = null;
 			state.pendingLevel = null;
 		}
 		kickoff();
 	}
-	/** Start missing fetches; true when every coord is already resolved. */
-	ensureFetches(pon, state, page, grid, wantWidth, includeAnnotations, epoch, coords) {
-		let allReady = true;
-		let started = 0;
-		const bleedPt = this.deps.options.tiles.bleedPx / grid.scale;
-		for (const coord of coords) {
-			const key = this.tileKey(pon, wantWidth, coord, includeAnnotations, epoch);
-			if (state.failedKeys.has(key)) continue;
-			const existing = state.entries.get(key);
-			if (existing) {
-				if (!existing.resolved) allReady = false;
-				continue;
+	/**
+	* Starts queued tiles while transit slots are free: the first on-screen
+	* tile of any view and page, in the order their queues were set, before
+	* any tile of a prefetch ring. Within one view of a page, its queue's order
+	* holds. Backpressure bounds raw rasters in transit (render + encode); each
+	* resolution hands its slot on through here, so no other pump is needed.
+	*/
+	pump() {
+		const started = /* @__PURE__ */ new Map();
+		while (this.inFlight < MAX_IN_FLIGHT) {
+			let next = null;
+			for (const state of this.pages.values()) {
+				const queued = this.nextToStart(state);
+				if (!queued || next && queued.prefetch) continue;
+				next = {
+					state,
+					coord: queued.coord
+				};
+				if (!queued.prefetch) break;
 			}
-			allReady = false;
-			if (this.inFlight >= MAX_IN_FLIGHT) continue;
-			this.inFlight += 1;
-			started += 1;
-			const abort = new AbortController();
-			const logical = tilePaintRect(grid, page, coord);
-			const entry = {
-				key,
-				scale: grid.scale,
+			if (!next) break;
+			this.start(next.state, next.coord);
+			started.set(next.state, (started.get(next.state) ?? 0) + 1);
+		}
+		for (const [state, count] of started) this.deps.debug?.(`fetch page=${state.pageObjectNumber} level=${state.queue?.wantWidth} +${count} tiles`);
+	}
+	/** The first tile of the state's queue not started yet, nor failed at this level. */
+	nextToStart(state) {
+		const queue = state.queue;
+		if (!queue) return null;
+		for (; queue.next < queue.coords.length; queue.next += 1) {
+			const coord = queue.coords[queue.next];
+			const key = this.tileKey(state.pageObjectNumber, queue.wantWidth, coord, queue.layers, queue.epoch);
+			if (state.failedKeys.has(key) || state.entries.has(key)) continue;
+			return {
 				coord,
-				rect: logical,
-				resolved: false,
-				painted: false,
-				charged: true,
-				abort
+				prefetch: queue.next >= queue.ringFrom
 			};
-			state.entries.set(key, entry);
-			this.deps.store.acquire(key, (signal) => this.deps.fetchTile(pon, toEngineRect(page, bleedPt > 0 ? bleedRect(logical, bleedPt, page) : logical), grid.scale, includeAnnotations, signal), abort.signal).then(() => {
-				this.releaseSlot(entry);
-				if (state.entries.get(key) !== entry) return;
+		}
+		return null;
+	}
+	/** Starts one queued tile's fetch, in a transit slot. */
+	start(state, coord) {
+		const { page, grid, wantWidth, layers, epoch } = state.queue;
+		const pageObjectNumber = state.pageObjectNumber;
+		const key = this.tileKey(pageObjectNumber, wantWidth, coord, layers, epoch);
+		const bleedPt = this.deps.getOptions().tiles.bleedPx / grid.scale;
+		this.inFlight += 1;
+		const abort = new AbortController();
+		const logical = tilePaintRect(grid, page, coord);
+		const entry = {
+			key,
+			scale: grid.scale,
+			coord,
+			rect: logical,
+			resolved: false,
+			painted: false,
+			charged: true,
+			abort
+		};
+		state.entries.set(key, entry);
+		state.planCache = null;
+		this.deps.store.acquire(key, (signal) => this.deps.fetchTile(state.view, pageObjectNumber, bleedPt > 0 ? bleedRect(logical, bleedPt, page) : logical, grid.scale, layers, signal), abort.signal).then(() => {
+			this.releaseSlot(entry);
+			if (state.entries.get(key) === entry) {
 				entry.resolved = true;
 				state.version += 1;
 				state.planCache = null;
-				this.deps.onAdvance(pon);
-			}, (err) => {
-				this.releaseSlot(entry);
-				if (state.entries.get(key) !== entry) return;
+				this.deps.onAdvance(pageObjectNumber);
+			}
+			this.pump();
+		}, (error) => {
+			this.releaseSlot(entry);
+			if (state.entries.get(key) === entry) {
 				state.entries.delete(key);
 				if (!abort.signal.aborted) {
 					state.failedKeys.add(key);
-					this.deps.debug?.(`tile failed ${key}: ${String(err)}`);
+					this.deps.debug?.(`tile failed ${key}: ${String(error)}`);
 					state.version += 1;
 					state.planCache = null;
-					this.deps.onAdvance(pon);
+					this.deps.onAdvance(pageObjectNumber);
 				}
-			});
-		}
-		if (started > 0) this.deps.debug?.(`fetch pon=${pon} level=${wantWidth} +${started} tiles`);
-		return allReady;
+			}
+			this.pump();
+		});
 	}
 	/**
-	* The release rule, evaluated as a PURE FUNCTION of the current painted
-	* set: retained sources (any non-want level) whose VISIBLE footprint is
-	* covered by PAINTED want-level tiles leave the paint list. Runs on every
+	* The release rule, evaluated as a pure function of the current painted
+	* set: retained sources (any non-want level) whose visible footprint is
+	* covered by painted want-level tiles leave the paint list. Runs on every
 	* `plan()` and on every painted report — never only "against the tile
-	* that just painted": release must not depend on paint ORDER (center-out
+	* that just painted": release must not depend on paint order (center-out
 	* scheduling means the report that completes a retained tile's coverage
 	* routinely lands far away from it), and re-evaluating from current state
 	* also self-heals any painted-flag transition the reports raced past.
-	* Coverage is index arithmetic over the WANT grid — generic over whatever
+	* Coverage is index arithmetic over the want grid — generic over whatever
 	* mix of retained scales exists (exact levels included).
 	*/
-	releaseCovered(pon, state, page, includeAnnotations) {
+	releaseCovered(pageObjectNumber, state, page, layers) {
 		const { wantScale, wantWidth } = state;
 		if (wantScale === null || wantWidth === null) return false;
 		const grid = tileGrid(page, wantScale, this.strategy().tileSize);
-		const paintedAt = (c) => {
-			const key = this.tileKey(pon, wantWidth, c, includeAnnotations, state.epoch);
-			return state.entries.get(key)?.painted === true;
-		};
+		const wantKeyOf = (coord) => this.tileKey(pageObjectNumber, wantWidth, coord, layers, state.epoch);
+		const paintedAt = (coord) => state.entries.get(wantKeyOf(coord))?.painted === true;
 		let released = false;
 		for (const [key, entry] of state.entries) {
 			if (entry.scale === wantScale || !entry.resolved) continue;
@@ -692,13 +914,12 @@ var TileManager = class {
 			if (regionCovered(grid, page, region, paintedAt)) {
 				state.entries.delete(key);
 				released = true;
-			} else if (this.deps.debug) {
-				const missing = tilesInRect(grid, page, region).filter((c) => !paintedAt(c));
-				const detail = missing.slice(0, 3).map((c) => {
-					const k = this.tileKey(pon, wantWidth, c, includeAnnotations, state.epoch);
-					const e = state.entries.get(k);
-					const st = !e ? "NO-ENTRY" : !e.resolved ? "PENDING" : "RESOLVED-unpainted";
-					return `${c.ix},${c.iy}=${st}`;
+			} else if (this.deps.debug && this.deps.getOptions().debug) {
+				const missing = tilesInRect(grid, page, region).filter((coord) => !paintedAt(coord));
+				const detail = missing.slice(0, 3).map((coord) => {
+					const missingEntry = state.entries.get(wantKeyOf(coord));
+					const status = !missingEntry ? "NO-ENTRY" : !missingEntry.resolved ? "PENDING" : "RESOLVED-unpainted";
+					return `${coord.ix},${coord.iy}=${status}`;
 				});
 				this.deps.debug(`retained ${key} blocked by: ${detail.join(" ")} (${missing.length} missing)`);
 			}
@@ -706,23 +927,22 @@ var TileManager = class {
 		return released;
 	}
 	/** Test/diagnostic introspection: bookkeeping size for one page. */
-	stats(view, pon) {
+	stats(view, pageObjectNumber) {
 		return {
-			entries: this.pages.get(stateKey(view, pon))?.entries.size ?? 0,
+			entries: this.pages.get(stateKey(view, pageObjectNumber))?.entries.size ?? 0,
 			inFlight: this.inFlight
 		};
 	}
-	/** Idempotent transit-slot release — the ONE place inFlight decrements. */
+	/** Idempotent transit-slot release — the one place inFlight decrements. */
 	releaseSlot(entry) {
 		if (!entry.charged) return;
 		entry.charged = false;
 		this.inFlight -= 1;
 	}
 	abortAll(state) {
-		if (state.settleTimer !== null) {
-			clearTimeout(state.settleTimer);
-			state.settleTimer = null;
-		}
+		state.queue = null;
+		state.cancelSettle?.();
+		state.cancelSettle = null;
 		for (const entry of state.entries.values()) if (!entry.resolved) {
 			entry.abort?.abort();
 			this.releaseSlot(entry);
@@ -730,117 +950,306 @@ var TileManager = class {
 	}
 	/** Level identity is the integer device width across the page — integer
 	*  and stable for pyramid rungs and exact levels alike. The key also
-	*  carries everything that determines the fetched BITMAP for a coord
+	*  carries everything that determines the fetched bitmap for a coord
 	*  (tile size, bleed, encode format): a raster's identity must include
 	*  its geometry, or a cached handle from one configuration could be
 	*  stretched into another's rect. Format genuinely varies at runtime —
 	*  the cloud policy arrives async after open and can change the resolved
 	*  format under a live store. */
-	tileKey(pon, levelWidth, c, includeAnnotations, epoch) {
-		const { tiles } = this.deps.options;
+	tileKey(pageObjectNumber, levelWidth, coord, layers, epoch) {
+		const { tiles } = this.deps.getOptions();
 		const format = this.strategy().format;
 		const geometry = `g${tiles.size}.${tiles.bleedPx}${format ? `.${format}` : ""}`;
-		return `t:${pon}|w${levelWidth}|${c.ix},${c.iy}|a${includeAnnotations ? 1 : 0}|e${epoch}|${geometry}`;
+		return `t:${pageObjectNumber}|w${levelWidth}|${coord.ix},${coord.iy}|${layersKeyOf(layers)}|e${epoch}|${geometry}`;
 	}
 };
-const coordKey = (c) => `${c.ix},${c.iy}`;
-const rectKey = (r) => `${Math.round(r.x)},${Math.round(r.y)},${Math.round(r.width)},${Math.round(r.height)}`;
-const annotationsOf = (key) => key.includes("|a1|");
+const coordKey = (coord) => `${coord.ix},${coord.iy}`;
+const rectKey = (rect) => `${Math.round(rect.x)},${Math.round(rect.y)},${Math.round(rect.width)},${Math.round(rect.height)}`;
+/** What a tile key's picture draws, as {@link layersKeyOf} wrote it into the key. */
+const layersOfKey = (key) => {
+	const drawn = /\|a([01])f([01])\|/.exec(key);
+	return {
+		includeAnnotations: drawn?.[1] === "1",
+		includeFormFields: drawn?.[2] === "1"
+	};
+};
 //#endregion
-//#region src/capability.ts
+//#region src/controller.ts
+const RENDER_SCOPE = "doc.render";
+const FORMS_SCOPE = "doc.forms.read";
+const ANNOTATIONS_SCOPE = "doc.annotate.read";
+/** Every answer `getLayerRights()` gives, one object each, so the same rights are the same object. */
+const LAYER_RIGHTS = [false, true].map((annotations) => [false, true].map((formFields) => Object.freeze({
+	annotations,
+	formFields
+})));
+/** An abort reason the engine task accepts (signals carry `unknown`). */
+const reasonOf = (signal) => typeof signal.reason === "string" ? signal.reason : void 0;
+const DEFAULT_BATCH_CONCURRENCY = 4;
 /**
-* The render capability: the ONE place STRATEGY (plugin options — what the
-* viewer spends) composes with POLICY (the engine fact — what the deployment
-* serves). The engine never snaps; framework layers never see either;
-* everything between — conforming demand to the resolved render points,
-* collapsing same-key asks in the raster store, exposing stable source
-* keys — happens here.
+* The render controller: the one place strategy (config: what the viewer
+* spends) composes with policy (the engine fact: what the deployment
+* serves). The engine never snaps and layers never see either; everything
+* between happens here: conforming demand to the resolved render points,
+* collapsing same-key asks in the raster store, exposing stable source keys,
+* and turning a view's demand into a retention-safe tile plan.
+*
+* Two doors for rasters: `renderPage` (public, exact size) and
+* `renderSource` (host, conformed). Both share the raster store, so a
+* developer's thumbnail and the rail's base plane never render twice.
+*
+* Every render it asks for is the picture of a page itself, so it asks the
+* engine with `priority: 'high'`, naming the view it's for when it knows it:
+* the engine runs it before anything else about the same place (annotation
+* appearances, form fields, text geometry, links).
+*
+* Two doors for staleness: confirmed document events (see `connect`) and
+* the `invalidate` verb. Both go through `publishInvalidation`, the one
+* place the ledger bumps and `onInvalidated` fires.
+*
+* The tile manager and the per-view plans live outside state (they hold
+* live handles and abort controllers); a re-plan wakes readers with
+* `ctx.notify()`.
 */
-function createRenderCapability(ctx, options = {}) {
-	const resolved = resolveRenderOptions(options);
-	const canRender = () => ctx.doc?.security.allows("doc.render") ?? false;
+function createRenderController(ctx) {
+	const settings = ctx.settings();
+	const resolvedOptions = (0, _embedpdf_core.memo)(() => [settings.get()], (current) => require_contract.resolveRenderOptions(current));
 	const store = new RasterStore();
-	const policy = () => ctx.document()?.renderPolicy ?? _embedpdf_core.CONTINUOUS_RENDER_POLICY;
-	let strategyMemo = null;
-	const strategy = () => {
-		const p = policy();
-		if (strategyMemo?.policy !== p) {
-			strategyMemo = {
-				policy: p,
-				strategy: resolveStrategy(p, resolved)
-			};
-			warnDroppedFormat(strategyMemo.strategy);
-		}
-		return strategyMemo.strategy;
+	const appearances = new AppearanceStore();
+	const recentAppearances = new RecentPictures();
+	const invalidated = ctx.events.source();
+	const renderCompleted = ctx.events.source();
+	const renderFailed = ctx.events.source();
+	const canRender = () => ctx.allows(RENDER_SCOPE);
+	const rights = () => LAYER_RIGHTS[ctx.allows("doc.annotate.read") ? 1 : 0][ctx.allows("doc.forms.read") ? 1 : 0];
+	const layersOf = (options) => {
+		const may = rights();
+		return (0, _embedpdf_core.resolvePageLayers)({
+			...options.includeAnnotations !== void 0 && (may.annotations || !options.includeAnnotations) ? { includeAnnotations: options.includeAnnotations } : {},
+			...options.includeFormFields !== void 0 && (may.formFields || !options.includeFormFields) ? { includeFormFields: options.includeFormFields } : {}
+		}, may);
+	};
+	const pictureLayers = (options, operation) => {
+		if (options.includeAnnotations === true) ctx.assertAllowed("doc.annotate.read", operation);
+		if (options.includeFormFields === true) ctx.assertAllowed(FORMS_SCOPE, operation);
+		return layersOf(options);
 	};
 	let warnedFormat = false;
-	const warnDroppedFormat = (s) => {
-		if (warnedFormat || resolved.format === void 0 || s.format === resolved.format) return;
+	const warnDroppedFormat = (strategy, requested) => {
+		if (warnedFormat || requested === void 0 || strategy.format === requested) return;
 		warnedFormat = true;
-		console.warn(`[render] format '${resolved.format}' is not in the deployment's formats — using '${s.format}'.`);
+		console.warn(`[render] format '${requested}' is not in the deployment's formats — using '${strategy.format}'.`);
 	};
 	let warnedBudget = false;
 	const warnPastBudgetNoTiles = (demandWidth, supplied) => {
-		if (warnedBudget || resolved.tiles.enabled || demandWidth <= supplied * 2) return;
+		if (warnedBudget || resolvedOptions().tiles.enabled || demandWidth <= supplied * 2) return;
 		warnedBudget = true;
 		console.warn(`[render] demand is ${(demandWidth / supplied).toFixed(1)}× over the base budget and the tile plane is disabled (tiles: false) — the page rests blurry. Raise fullPage.maxWidth or re-enable tiles.`);
 	};
-	const pageOf = (pon) => (ctx.document()?.pages ?? []).find((p) => p.pageObjectNumber === pon);
-	const pageWidthOf = (pon) => {
-		const page = pageOf(pon);
-		if (!page) throw new Error(`render: unknown page object number ${pon}`);
-		return page.size.width;
+	const renderPolicy = () => ctx.document()?.renderPolicy ?? _embedpdf_core.CONTINUOUS_RENDER_POLICY;
+	const currentStrategy = (0, _embedpdf_core.memo)(() => [renderPolicy(), resolvedOptions()], (policy, options) => {
+		const strategy = resolveStrategy(policy, options);
+		warnDroppedFormat(strategy, options.format);
+		return strategy;
+	});
+	const pageWidthOf = (page) => {
+		const info = ctx.getPage(page);
+		if (!info) ctx.assertPageRef(page);
+		return info.size.width;
 	};
-	const conformViewport = (pon, scale) => {
-		const s = strategy();
-		const demandWidth = scale * pageWidthOf(pon);
-		const width = baseAskWidth(s, demandWidth);
+	const allPageObjectNumbers = () => (ctx.document()?.pages ?? []).map((info) => info.ref.objectNumber);
+	const conformViewport = (page, scale) => {
+		const demandWidth = scale * pageWidthOf(page);
+		const width = baseAskWidth(currentStrategy(), demandWidth);
 		warnPastBudgetNoTiles(demandWidth, width);
 		return {
 			kind: "width",
 			width
 		};
 	};
-	const epochOf = (pon, includeAnnotations) => {
-		const s = ctx.getState();
-		const content = s.contentEpochs[pon] ?? 0;
-		if (!includeAnnotations) return content;
-		return content + (s.annotatedEpochs[pon] ?? 0);
-	};
-	const baseKey = (pon, viewport, annotations) => {
-		const format = strategy().format;
-		return `${pon}|w${viewport.kind === "width" ? viewport.width : 0}|a${annotations ? 1 : 0}|e${epochOf(pon, annotations)}${format ? `|f${format}` : ""}`;
-	};
+	const epochOf = (pageObjectNumber, layers) => renderEpochOf(ctx.state.get(), pageObjectNumber, layers);
+	const rasterKey = (pageObjectNumber, width, layers, format, quality) => `${pageObjectNumber}|w${width}|${layersKeyOf(layers)}|e${epochOf(pageObjectNumber, layers)}${format ? `|f${format}` : ""}${quality !== void 0 ? `|q${quality}` : ""}`;
+	function acquireRaster(page, key, request, signal) {
+		return store.acquire(key, (storeSignal) => {
+			const task = ctx.doc.with({
+				priority: "high",
+				...request.view !== void 0 ? { view: request.view } : {}
+			}).page(page).render.image({
+				viewport: request.viewport,
+				...request.layers,
+				...request.format !== void 0 ? { format: request.format } : {},
+				...request.quality !== void 0 ? { quality: request.quality } : {}
+			});
+			if (storeSignal.aborted) task.abort(reasonOf(storeSignal));
+			else storeSignal.addEventListener("abort", () => task.abort(reasonOf(storeSignal)), { once: true });
+			return task;
+		}, signal).then((image) => {
+			renderCompleted.emit({
+				page,
+				key
+			});
+			return image;
+		}, (error) => {
+			const mapped = (0, _embedpdf_core.toPluginError)("render", error);
+			if (!(0, _embedpdf_core.isPluginError)(mapped, "operation-cancelled") && !(0, _embedpdf_core.isPluginError)(mapped, "instance-closed")) renderFailed.emit({
+				page,
+				key,
+				error: (0, _embedpdf_core.toPluginErrorInfo)(mapped)
+			});
+			throw mapped;
+		});
+	}
+	/** The host door: conformed to the render points. Async so refusals reject. */
+	async function renderSource(page, { scale, view, signal, ...options }) {
+		ctx.assertAllowed(RENDER_SCOPE, "render.renderSource");
+		const layers = pictureLayers(options, "render.renderSource");
+		const viewport = conformViewport(page, scale);
+		const strategy = currentStrategy();
+		return acquireRaster(page, rasterKey(page.objectNumber, viewport.kind === "width" ? viewport.width : 0, layers, strategy.format, void 0), {
+			viewport,
+			layers,
+			format: strategy.format,
+			quality: strategy.quality,
+			view
+		}, signal);
+	}
+	/** The public door: the requested size, exactly. Async so refusals reject. */
+	async function renderPage(pageArgument, options = {}) {
+		ctx.assertAllowed(RENDER_SCOPE, "render.renderPage");
+		const { ref: page, size } = ctx.pageOf(pageArgument);
+		const width = Math.max(1, Math.round(options.width ?? (options.scale ?? 1) * size.width));
+		const layers = pictureLayers(options, "render.renderPage");
+		const strategy = currentStrategy();
+		const format = options.format ?? strategy.format;
+		const quality = options.quality ?? strategy.quality;
+		const key = rasterKey(page.objectNumber, width, layers, format, options.quality);
+		return ctx.cancellable(options.signal, acquireRaster(page, key, {
+			viewport: {
+				kind: "width",
+				width
+			},
+			layers,
+			format,
+			quality,
+			view: void 0
+		}, options.signal));
+	}
+	async function renderPages(pages, options = {}) {
+		ctx.assertAllowed(RENDER_SCOPE, "render.renderPages");
+		const concurrency = Math.max(1, options.concurrency ?? DEFAULT_BATCH_CONCURRENCY);
+		const applied = [];
+		const failed = [];
+		const queue = pages.map((page, index) => ({
+			page,
+			index
+		}));
+		const worker = async () => {
+			for (let next = queue.shift(); next; next = queue.shift()) {
+				const { page, index } = next;
+				try {
+					const image = await renderPage(page, options);
+					applied.push({
+						index,
+						render: {
+							page: ctx.pageOf(page).ref,
+							image
+						}
+					});
+				} catch (error) {
+					failed.push({
+						index,
+						ref: page,
+						error: (0, _embedpdf_core.toPluginErrorInfo)((0, _embedpdf_core.toPluginError)("render", error))
+					});
+				}
+			}
+		};
+		const batch = Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, worker));
+		await ctx.cancellable(options.signal, batch);
+		const byInput = (left, right) => left.index - right.index;
+		return {
+			applied: applied.sort(byInput).map(({ render }) => render),
+			skipped: [],
+			failed: failed.sort(byInput).map(({ ref, error }) => ({
+				ref,
+				error
+			}))
+		};
+	}
+	async function renderAppearances(page, { family, scale, items, signal }) {
+		ctx.assertAllowed(family === "widgets" ? FORMS_SCOPE : ANNOTATIONS_SCOPE, "render.renderAppearances");
+		const pageObjectNumber = ctx.pageOf(page).ref.objectNumber;
+		const versions = new Map(items.map((item) => [(0, _embedpdf_core.annotationKey)(item.ref), item.version]));
+		const asked = [...versions].map(([item, version]) => `${item}@${version}`).sort();
+		const group = `${family}|${pageObjectNumber}`;
+		const pictures = appearances.acquire(group, `${group}|s${scale}|${asked.join(",")}`, async (fetchSignal) => {
+			const pageHandle = ctx.doc.page((0, _embedpdf_core.toPageRef)(pageObjectNumber));
+			const options = {
+				viewport: {
+					kind: "scale",
+					scale
+				},
+				modes: ["normal"]
+			};
+			const task = family === "widgets" ? pageHandle.forms.renderAppearances(options) : pageHandle.annotations.renderAppearances(options);
+			if (fetchSignal.aborted) task.abort(reasonOf(fetchSignal));
+			else fetchSignal.addEventListener("abort", () => task.abort(reasonOf(fetchSignal)), { once: true });
+			const drawn = (await task).appearances.flatMap((picture) => {
+				const version = versions.get((0, _embedpdf_core.annotationKey)(picture.ref));
+				return version === void 0 ? [] : [{
+					...picture,
+					version
+				}];
+			});
+			recentAppearances.remember(family, drawn, (picture) => (0, _embedpdf_core.annotationKey)(picture.ref));
+			return drawn;
+		}, signal);
+		return ctx.cancellable(signal, pictures.catch((error) => {
+			throw (0, _embedpdf_core.toPluginError)("render", error);
+		}));
+	}
+	function publishInvalidation(pageObjectNumbers, scope, origin) {
+		if (pageObjectNumbers.length === 0) return;
+		ctx.state.update(invalidatePages, pageObjectNumbers, scope);
+		for (const pageObjectNumber of pageObjectNumbers) replanPage(pageObjectNumber);
+		invalidated.emit({
+			pages: pageObjectNumbers.map((pageObjectNumber) => (0, _embedpdf_core.toPageRef)(pageObjectNumber)),
+			scope,
+			origin
+		});
+	}
+	function invalidate({ pages, scope = "content" } = {}) {
+		const named = pages?.flatMap((page) => ctx.getPage(page)?.ref.objectNumber ?? []);
+		publishInvalidation(named ?? allPageObjectNumbers(), scope, null);
+	}
 	const pendingAdvance = /* @__PURE__ */ new Set();
 	let advanceScheduled = false;
-	const raf = typeof requestAnimationFrame === "function" ? (cb) => requestAnimationFrame(() => cb()) : (cb) => void setTimeout(cb, 16);
-	const wake = (pon) => {
-		pendingAdvance.add(pon);
+	const wake = (pageObjectNumber) => {
+		pendingAdvance.add(pageObjectNumber);
 		if (advanceScheduled) return;
 		advanceScheduled = true;
-		raf(() => {
+		ctx.clock.nextFrame(() => {
 			advanceScheduled = false;
-			const pons = [...pendingAdvance];
+			const advanced = [...pendingAdvance];
 			pendingAdvance.clear();
-			for (const p of pons) ctx.dispatch({
-				type: "PAINT_ADVANCED",
-				pon: p
-			});
+			for (const advancedPage of advanced) replanPage(advancedPage);
 		});
 	};
-	const viewTiles = /* @__PURE__ */ new Map();
 	const tiles = new TileManager({
 		store,
-		options: resolved,
-		getPolicy: policy,
-		getPageSize: (pon) => pageOf(pon)?.size,
+		getOptions: resolvedOptions,
+		getPolicy: renderPolicy,
+		getPageSize: (pageObjectNumber) => ctx.getPage((0, _embedpdf_core.toPageRef)(pageObjectNumber))?.size,
 		getEpoch: epochOf,
-		fetchTile: (pon, rect, scale, includeAnnotations, signal) => {
-			const doc = ctx.doc;
-			if (!doc) return Promise.reject(/* @__PURE__ */ new Error("render: no document bound"));
-			if (!canRender()) return Promise.reject(new _embedpdf_core.PermissionDenied("doc.render", "render.tile"));
-			const s = strategy();
-			const task = doc.page(pon).render.image({
+		after: ctx.clock.after,
+		fetchTile: async (view, pageObjectNumber, rect, scale, layers, signal) => {
+			ctx.assertAllowed(RENDER_SCOPE, "render.tile");
+			const page = (0, _embedpdf_core.toPageRef)(pageObjectNumber);
+			const strategy = currentStrategy();
+			const task = ctx.doc.with({
+				priority: "high",
+				view
+			}).page(page).render.image({
 				target: {
 					kind: "rect",
 					rect
@@ -849,184 +1258,151 @@ function createRenderCapability(ctx, options = {}) {
 					kind: "scale",
 					scale
 				},
-				includeAnnotations,
-				...s.format !== void 0 ? { format: s.format } : {},
-				...s.quality !== void 0 ? { quality: s.quality } : {}
+				...layers,
+				...strategy.format !== void 0 ? { format: strategy.format } : {},
+				...strategy.quality !== void 0 ? { quality: strategy.quality } : {}
 			});
-			if (signal.aborted) task.abort(signal.reason);
-			else signal.addEventListener("abort", () => task.abort(signal.reason), { once: true });
+			if (signal.aborted) task.abort(reasonOf(signal));
+			else signal.addEventListener("abort", () => task.abort(reasonOf(signal)), { once: true });
 			return task;
 		},
 		onAdvance: wake,
-		...resolved.debug ? { debug: (msg) => console.debug(`[render] ${msg}`) } : {}
+		debug: (message) => {
+			if (resolvedOptions().debug) console.debug(`[render] ${message}`);
+		}
 	});
-	return {
-		canRender,
-		renderPage(pon, { scale, includeAnnotations, signal }) {
-			const doc = ctx.doc;
-			if (!doc) return Promise.reject(/* @__PURE__ */ new Error("render: no document bound"));
-			if (!canRender()) return Promise.reject(new _embedpdf_core.PermissionDenied("doc.render", "render.renderPage"));
-			const annotations = includeAnnotations ?? true;
-			const viewport = conformViewport(pon, scale);
-			const key = baseKey(pon, viewport, annotations);
-			return store.acquire(key, (storeSignal) => {
-				const s = strategy();
-				const task = doc.page(pon).render.image({
-					viewport,
-					includeAnnotations: annotations,
-					...s.format !== void 0 ? { format: s.format } : {},
-					...s.quality !== void 0 ? { quality: s.quality } : {}
-				});
-				if (storeSignal.aborted) task.abort(storeSignal.reason);
-				else storeSignal.addEventListener("abort", () => task.abort(storeSignal.reason), { once: true });
-				return task;
-			}, signal);
-		},
-		renderSourceKey(pon, { scale, includeAnnotations }) {
-			const annotations = includeAnnotations ?? true;
-			return baseKey(pon, conformViewport(pon, scale), annotations);
-		},
-		conformViewport,
-		paintSettings() {
-			return {
-				fadeMs: resolved.tiles.fadeMs,
-				tiles: resolved.tiles.enabled
-			};
-		},
-		renderPolicy: policy,
-		tilesFor(view) {
-			let handle = viewTiles.get(view);
-			if (!handle) {
-				handle = {
-					plan: (pon, demand, opts) => tiles.plan(view, pon, demand, opts?.includeAnnotations ?? true),
-					painted: (pon, key) => tiles.sourcePainted(view, pon, key),
-					unpainted: (pon, key) => tiles.sourceUnpainted(view, pon, key),
-					release: (pon) => tiles.releasePage(view, pon)
-				};
-				viewTiles.set(view, handle);
+	/** One handle per view id, reference-counted; demands and plans per page. */
+	const views = /* @__PURE__ */ new Map();
+	/** Re-plan a page for every view that wants it (schedules the next want
+	*  set), and wake readers once when any plan changed. */
+	function replanPage(pageObjectNumber) {
+		let changed = false;
+		for (const [viewId, view] of views) {
+			const entry = view.pages.get(pageObjectNumber);
+			if (!entry) continue;
+			const plan = tiles.plan(viewId, pageObjectNumber, entry.demand, entry.layers);
+			if (plan !== entry.plan) {
+				entry.plan = plan;
+				changed = true;
 			}
-			return handle;
-		},
-		renderEpoch(pon, includeAnnotations = true) {
-			return epochOf(pon, includeAnnotations);
-		},
-		invalidate({ pons, scope = "content" } = {}) {
-			const target = pons ?? (ctx.document()?.pages ?? []).map((p) => p.pageObjectNumber);
-			if (target.length) ctx.dispatch({
-				type: "INVALIDATE",
-				scope,
-				pons: target
-			});
 		}
-	};
-}
-//#endregion
-//#region src/effects.ts
-/**
-* Which pages' ANNOTATED raster a confirmed mutation repaints — the whole
-* event→scope map. Everything the engine emits today is appearance-scoped;
-* when it grows content-mutation events (redaction.applied, content.edited),
-* they get a case here dispatching scope 'content'. Over-invalidation is
-* acceptable (a z-order move that changes nothing repaints one thumb);
-* under-invalidation is the bug.
-*/
-function annotatedPons(event, allPons) {
-	switch (event.type) {
-		case "annotation.created":
-		case "annotation.updated":
-		case "annotation.deleted":
-		case "annotation.moved": return [event.pageObjectNumber];
-		case "form.valueChanged":
-		case "form.effectsApplied": return event.changedWidgets.map((w) => w.pageObjectNumber);
-		case "form.fieldDeleted": return event.removedWidgets.map((w) => w.pageObjectNumber);
-		case "form.fieldCreated":
-		case "form.fieldUpdated":
-		case "form.widgetAttached":
-		case "form.widgetDetached": return event.field.widgets.map((w) => w.pageObjectNumber);
-		case "form.imported":
-		case "form.repaired": return allPons();
-		default: return [];
+		if (changed) ctx.notify();
 	}
-}
-function registerRenderEffects(ctx) {
-	const doc = ctx.doc;
-	if (!doc) return;
-	const allPons = () => (ctx.document()?.pages ?? []).map((p) => p.pageObjectNumber);
-	const unsubscribe = doc.events.subscribe((event) => {
-		if (event.type === "redaction.applied") {
-			const pons = event.results.filter((r) => r.status === "applied").map((r) => r.pageObjectNumber);
-			if (pons.length) ctx.dispatch({
-				type: "INVALIDATE",
-				scope: "content",
-				pons
-			});
-			return;
+	function createViewDemand(viewId) {
+		const existing = views.get(viewId);
+		if (existing) {
+			existing.refs += 1;
+			return existing.handle;
 		}
-		const pons = annotatedPons(event, allPons);
-		if (pons.length) ctx.dispatch({
-			type: "INVALIDATE",
-			scope: "annotations",
-			pons
+		const pages = /* @__PURE__ */ new Map();
+		const handle = {
+			setDemand: (page, demand, options) => {
+				const pageObjectNumber = page.objectNumber;
+				const layers = layersOf(options ?? {});
+				const previous = pages.get(pageObjectNumber);
+				const plan = tiles.plan(viewId, pageObjectNumber, demand, layers);
+				pages.set(pageObjectNumber, {
+					demand,
+					layers,
+					plan
+				});
+				if (plan !== previous?.plan) ctx.notify();
+			},
+			getPlan: (page) => pages.get(page.objectNumber)?.plan ?? require_contract.EMPTY_TILE_PLAN,
+			markPainted: (page, key) => tiles.sourcePainted(viewId, page.objectNumber, key),
+			markUnpainted: (page, key) => tiles.sourceUnpainted(viewId, page.objectNumber, key),
+			release: (page) => {
+				pages.delete(page.objectNumber);
+				tiles.releasePage(viewId, page.objectNumber);
+			},
+			dispose: () => {
+				const view = views.get(viewId);
+				if (!view || view.refs === 0) return;
+				view.refs -= 1;
+				if (view.refs > 0) return;
+				for (const pageObjectNumber of [...view.pages.keys()]) tiles.releasePage(viewId, pageObjectNumber);
+				view.pages.clear();
+			}
+		};
+		views.set(viewId, {
+			handle,
+			refs: 1,
+			pages
 		});
+		return handle;
+	}
+	const paintSettings = (0, _embedpdf_core.memo)(() => [resolvedOptions().tiles.enabled], (enabled) => Object.freeze({ tiles: enabled }));
+	ctx.listen(settings.api.onSettingsChanged, () => {
+		const shown = /* @__PURE__ */ new Set();
+		for (const view of views.values()) for (const page of view.pages.keys()) shown.add(page);
+		for (const page of shown) replanPage(page);
 	});
-	ctx.cleanup(unsubscribe);
-}
-//#endregion
-//#region src/reducer.ts
-const initialRenderState = () => ({
-	contentEpochs: {},
-	annotatedEpochs: {},
-	paintVersions: {}
-});
-const bump = (epochs, pons) => {
-	const next = { ...epochs };
-	for (const pon of pons) next[pon] = (next[pon] ?? 0) + 1;
-	return next;
-};
-/** Pure. Two transitions: bump the touched pages' ledger for the fact's
-*  scope (one action per fact, so a batch result bumps each pon once — a
-*  'content' fact bumps ONLY the content ledger; annotated readers sum both,
-*  which is how content invalidation reaches them too), and the tile
-*  wake-up counter. The render POLICY is deliberately NOT here — it's a
-*  document fact on `DocumentMeta`, materialized by the kernel at open. */
-const renderReducer = (state, a) => {
-	if (a.type === "PAINT_ADVANCED") return {
-		...state,
-		paintVersions: bump(state.paintVersions, [a.pon])
-	};
-	if (a.type !== "INVALIDATE" || a.pons.length === 0) return state;
-	return a.scope === "content" ? {
-		...state,
-		contentEpochs: bump(state.contentEpochs, a.pons)
-	} : {
-		...state,
-		annotatedEpochs: bump(state.annotatedEpochs, a.pons)
+	return {
+		api: {
+			...settings.api,
+			canRender,
+			renderPage,
+			renderThumbnail: (page, { maxWidth, ...options }) => renderPage(page, {
+				width: maxWidth,
+				...options
+			}),
+			renderPages,
+			getRenderPolicy: renderPolicy,
+			getRenderEpoch: (page, layers = {}) => {
+				const info = ctx.getPage(page);
+				return info ? epochOf(info.ref.objectNumber, layersOf(layers)) : 0;
+			},
+			invalidate,
+			onInvalidated: invalidated.on,
+			renderSource,
+			getSourceKey: (page, { scale, view: _view, ...options }) => {
+				const viewport = conformViewport(page, scale);
+				return rasterKey(page.objectNumber, viewport.kind === "width" ? viewport.width : 0, layersOf(options), currentStrategy().format, void 0);
+			},
+			conformViewport,
+			getPaintSettings: paintSettings,
+			getLayerRights: rights,
+			createViewDemand,
+			renderAppearances,
+			keptAppearances: (family, item) => recentAppearances.of(family, (0, _embedpdf_core.annotationKey)(item)),
+			getAppearanceScale: (renderScale) => (0, _embedpdf_core.snapAppearanceScale)(renderPolicy(), renderScale),
+			onRenderCompleted: renderCompleted.on,
+			onRenderFailed: renderFailed.on
+		},
+		connect() {
+			ctx.listen(ctx.doc.events, (event) => {
+				const change = pixelChangeOf(event, allPageObjectNumbers);
+				if (!change) return;
+				publishInvalidation(change.pages, change.scope, "origin" in event ? event.origin : null);
+			});
+		}
 	};
-};
+}
 //#endregion
 //#region src/render.plugin.ts
 /**
-* Document-scoped. The ONE policy consumer in the client stack: the doc-bind
-* effect resolves the engine's advertised render
-* policy; `renderPage` conforms desired scales to it and collapses
-* same-rung asks in the raster store; the tile manager turns host-supplied
-* demand into a retention-safe paint plan over the SAME store. State is the
-* per-page ledger — raster versions (two doors: the document event stream's
-* built-in map and the `invalidate` verb), the policy latch, and the tile
-* wake-up counter. Layers key on `renderSourceKey`/`tilePlan` and refetch
-* exactly when those change.
+* Document-scoped page rasters. The only render-policy consumer in the
+* client stack: the kernel materializes the engine's advertised render
+* policy on the document, the controller conforms desired scales to it and
+* collapses same-key asks in its raster store, and the tile manager turns
+* host-supplied demand into a retention-safe paint plan over the same store.
+* State is the per-page raster-version ledger.
 */
-const renderPlugin = (options = {}) => (0, _embedpdf_core.definePlugin)({
+const renderPlugin = (config) => (0, _embedpdf_core.definePlugin)({
 	id: "render",
 	scope: "document",
-	token: require_contract.RenderToken,
-	initialState: initialRenderState,
-	reduce: renderReducer,
-	capability: (ctx) => createRenderCapability(ctx, options),
-	effects: registerRenderEffects
+	token: require_contract_host.RenderToken,
+	state: initialRenderState,
+	settings: {
+		defaults: require_contract.RENDER_DEFAULTS,
+		registered: config
+	},
+	create: createRenderController
 });
 //#endregion
+exports.RENDER_DEFAULTS = require_contract.RENDER_DEFAULTS;
 exports.RenderToken = require_contract.RenderToken;
 exports.renderPlugin = renderPlugin;
+exports.samePageViewDemand = require_contract.samePageViewDemand;
 
 //# sourceMappingURL=index.cjs.map