@embedpdf/plugin-render 3.0.0-next.5 → 3.0.0-next.7

package/dist/index.js

@@ -1,4 +1,4 @@
-import { CONTINUOUS_RENDER_POLICY, createCapabilityToken, definePlugin, snapFullPageViewport } from "@embedpdf/core";
+import { CONTINUOUS_RENDER_POLICY, createCapabilityToken, definePlugin } from "@embedpdf/core";
 import { intersectRects } from "@embedpdf/core-geometry";
 //#region src/paint-plan.ts
 const EMPTY_TILE_PLAN = {
@@ -7,36 +7,61 @@ const EMPTY_TILE_PLAN = {
 	fetching: [],
 	stamp: "empty"
 };
-function resolveTiling(config) {
+/** 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 {
-		tileSize: config?.tileSize ?? 512,
-		scales: config?.scales ?? [
-			1,
-			2,
-			4,
-			8,
-			16,
-			32
-		],
-		engageAt: config?.engageAt ?? 1.25,
-		prefetchMargin: config?.prefetch?.margin ?? .5,
-		velocityBias: config?.prefetch?.velocityBias ?? true,
-		settleMs: config?.settleMs ?? 150
+		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
 	};
 }
 //#endregion
 //#region src/raster-store.ts
 /**
 * Client-side mirror of the server's one-door read-through: per-key
-* SINGLEFLIGHT + LRU over encoded page images.
+* 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 lattice does the
-* caching work: every ask inside one rung is the same key, and rung
+* annotations flag + epoch — see `renderSourceKey`), 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
+* 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,
 * layer unmounted) detaches without killing it for other consumers; the
 * underlying engine call aborts only when the LAST in-flight consumer leaves.
@@ -44,10 +69,11 @@ function resolveTiling(config) {
 * is a no-op by design.
 */
 var RasterStore = class {
-	constructor(maxEntries = 48) {
-		this.maxEntries = maxEntries;
+	constructor(maxCost = 128 * 1024 * 1024) {
+		this.maxCost = maxCost;
 		this.entries = /* @__PURE__ */ new Map();
 		this.tick = 0;
+		this.total = 0;
 	}
 	acquire(key, fetch, signal) {
 		const existing = this.entries.get(key);
@@ -64,9 +90,12 @@ var RasterStore = class {
 		};
 		entry.promise = fetch(abort.signal).then((handle) => {
 			entry.handle = handle;
+			entry.cost = costOf(handle);
+			this.total += entry.cost;
+			this.evict();
 			return handle;
 		}, (err) => {
-			if (this.entries.get(key) === entry) this.entries.delete(key);
+			this.drop(key, entry);
 			throw err;
 		});
 		entry.promise.catch(() => {});
@@ -83,6 +112,10 @@ var RasterStore = class {
 	get size() {
 		return this.entries.size;
 	}
+	/** Total cost (~bytes) of resolved entries — the budgeted quantity. */
+	get costUsed() {
+		return this.total;
+	}
 	attach(key, entry, signal) {
 		if (signal?.aborted) return Promise.reject(abortReason(signal));
 		entry.refs += 1;
@@ -101,7 +134,7 @@ var RasterStore = class {
 				entry.refs -= 1;
 				if (entry.refs <= 0 && entry.handle === void 0) {
 					entry.abort.abort(abortReason(signal));
-					if (this.entries.get(key) === entry) this.entries.delete(key);
+					this.drop(key, entry);
 				}
 				reject(abortReason(signal));
 			};
@@ -121,19 +154,72 @@ var RasterStore = class {
 			});
 		});
 	}
+	/** Remove an entry, keeping the cost ledger honest. */
+	drop(key, entry) {
+		if (this.entries.get(key) !== entry) return;
+		this.entries.delete(key);
+		if (entry.cost !== void 0) this.total -= entry.cost;
+	}
 	evict() {
-		if (this.entries.size <= this.maxEntries) return;
+		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);
-		for (const [key] of candidates) {
-			if (this.entries.size <= this.maxEntries) return;
-			this.entries.delete(key);
+		for (const [key, entry] of candidates) {
+			if (this.total <= this.maxCost) return;
+			this.drop(key, entry);
 		}
 	}
 };
+/** Approximate memory cost: encoded bytes when known, pixel count as a
+*  decoded-order estimate for URL handles, 1 when nothing is known. */
+function costOf(handle) {
+	if (handle.source?.kind === "bytes") return handle.source.bytes.byteLength;
+	if (handle.width !== void 0 && handle.height !== void 0) return handle.width * handle.height;
+	return 1;
+}
 function abortReason(signal) {
 	return signal.reason ?? new DOMException("aborted", "AbortError");
 }
 //#endregion
+//#region src/strategy.ts
+const ascending = (values) => [...values].sort((a, b) => a - b);
+/** 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);
+	return kept.length ? kept : sorted.slice(0, 1);
+};
+function resolveStrategy(policy, options) {
+	const lattice = policy.kind === "lattice";
+	const widths = lattice ? options.fullPage.maxWidthExplicit ? capWidths(policy.fullPage.widths, options.fullPage.maxWidth) : ascending(policy.fullPage.widths) : options.fullPage.quantize === "exact" ? null : capWidths(options.fullPage.quantize, options.fullPage.maxWidth);
+	const clientPyramid = options.tiles.quantize === "exact" ? null : ascending(options.tiles.quantize);
+	const pyramid = lattice ? policy.tiles?.scales ? ascending(policy.tiles.scales) : clientPyramid ?? options.tiles.fallbackPyramid : clientPyramid;
+	const tileSize = lattice && policy.tiles?.tileSizes.length ? policy.tiles.tileSizes.includes(options.tiles.size) ? options.tiles.size : policy.tiles.tileSizes[0] : options.tiles.size;
+	const engageAt = options.tiles.engageAt ?? (widths === null ? 1 : 1.25);
+	const requested = options.format;
+	const format = requested === void 0 ? void 0 : !lattice || policy.formats.includes(requested) ? requested : policy.formats[0];
+	return {
+		widths,
+		maxWidth: options.fullPage.maxWidth,
+		pyramid,
+		tileSize,
+		engageAt,
+		tileMaxScale: options.tiles.maxScale,
+		format,
+		quality: options.quality
+	};
+}
+/**
+* The ONE base-sizing function — four callers: `renderPage`,
+* `renderSourceKey`, `conformViewport`, and tile engagement. Exact mode
+* returns the (settled) demand itself up to the budget; ladder mode snaps
+* 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];
+}
+//#endregion
 //#region src/tiles.ts
 function tileGrid(page, scale, tileSize) {
 	return {
@@ -174,14 +260,32 @@ function tilePaintRect(grid, page, c) {
 		height: Math.min(span, page.height - y)
 	};
 }
-/** Engine target rect: y-UP PDF user space (top > bottom). */
-function tileEngineRect(grid, page, c) {
-	const paint = tilePaintRect(grid, page, c);
+/** 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
+* 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);
 	return {
-		left: paint.x,
-		right: paint.x + paint.width,
-		top: page.height - paint.y,
-		bottom: page.height - (paint.y + paint.height)
+		x,
+		y,
+		width: Math.min(page.width, rect.x + rect.width + pt) - x,
+		height: Math.min(page.height, rect.y + rect.height + pt) - y
 	};
 }
 /**
@@ -247,56 +351,108 @@ function snapToPyramid(scales, needed) {
 * 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, 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 (the
-*     layer's img onload — the decode boundary), 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 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
+*     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.
 *   - epoch exception: an invalidation bump means retained pixels are
 *     WRONG — 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
+* 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.
 */
+/** 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.inFlight = 0;
+		this.warnedStageless = false;
 	}
-	plan(pon, demand, includeAnnotations) {
-		const { config } = this.deps;
+	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;
+		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);
+		const state = this.pageState(pon, view);
 		if (state.epoch !== epoch) {
 			this.abortAll(state);
 			state.entries.clear();
+			state.failedKeys.clear();
 			state.epoch = epoch;
 			state.wantScale = null;
+			state.wantWidth = null;
 			state.planCache = null;
 		}
-		const baseSupplied = policy.kind === "lattice" ? widthOf(snapFullPageViewport(policy, {
-			kind: "width",
-			width: demand.desiredDeviceWidth
-		})) : demand.desiredDeviceWidth;
-		if (demand.desiredDeviceWidth / baseSupplied <= config.engageAt) {
+		const supplied = baseAskWidth(strategy, demand.desiredDeviceWidth);
+		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.abortAll(state);
 				state.entries.clear();
+				state.failedKeys.clear();
 				state.wantScale = null;
+				state.wantWidth = null;
 				state.planCache = null;
 			}
 			return EMPTY_TILE_PLAN;
 		}
-		const pyramid = policy.kind === "lattice" && policy.tiles ? policy.tiles.scales : config.scales;
-		const wantScale = snapToPyramid(pyramid, demand.desiredDeviceWidth / page.width);
-		const grid = tileGrid(page, wantScale, config.tileSize);
+		let wantWidth;
+		let wantScale;
+		if (strategy.pyramid) {
+			wantScale = snapToPyramid(strategy.pyramid, demand.desiredDeviceWidth / page.width);
+			wantWidth = Math.round(wantScale * page.width);
+		} else {
+			wantWidth = Math.min(Math.max(1, Math.round(demand.desiredDeviceWidth)), Math.round(strategy.tileMaxScale * page.width));
+			wantScale = wantWidth / page.width;
+		}
+		if (!demand.visibleRect) {
+			const maxStagelessWidth = Math.max(strategy.tileSize, Math.floor(strategy.tileSize * Math.sqrt(STAGELESS_TILE_CAP * page.width / page.height)));
+			if (wantWidth > maxStagelessWidth) {
+				if (!this.warnedStageless) {
+					this.warnedStageless = true;
+					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);
+					wantScale = fitting.length ? fitting[fitting.length - 1] : strategy.pyramid[0];
+					wantWidth = Math.round(wantScale * page.width);
+				} else {
+					wantWidth = maxStagelessWidth;
+					wantScale = wantWidth / page.width;
+				}
+			}
+		}
+		const grid = tileGrid(page, wantScale, strategy.tileSize);
 		const visible = demand.visibleRect ?? {
 			x: 0,
 			y: 0,
@@ -305,26 +461,43 @@ var TileManager = class {
 		};
 		state.lastVisible = visible;
 		const p0 = tilesInRect(grid, page, visible);
-		const ring = inflateRect(visible, config.prefetchMargin, config.velocityBias ? demand.velocity : void 0);
+		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, includeAnnotations, epoch, p0, p1);
-		const demandKey = `${wantScale}|${rectKey(visible)}|e${epoch}`;
+		this.schedule(pon, state, page, grid, wantScale, wantWidth, includeAnnotations, epoch, p0, p1, visible);
+		if (this.releaseCovered(pon, state, page, includeAnnotations)) {
+			state.version += 1;
+			state.planCache = null;
+		}
+		const demandKey = `w${wantWidth}|${rectKey(visible)}|e${epoch}`;
 		if (state.planCache && state.planCache.demandKey === demandKey && state.planCache.version === state.version) return state.planCache.plan;
 		const paint = [];
 		const fetching = [];
+		const stale = [];
+		const bleedPx = this.deps.options.tiles.bleedPx;
 		for (const entry of state.entries.values()) {
 			const visIntersect = intersectRects(entry.rect, visible);
-			if (entry.handle) {
-				if (visIntersect.width > 0 && visIntersect.height > 0) paint.push({
-					key: entry.key,
-					scale: entry.scale,
-					rect: entry.rect,
-					z: zOf(pyramid, entry.scale),
-					handle: entry.handle
-				});
+			if (entry.resolved) {
+				if (visIntersect.width > 0 && visIntersect.height > 0) {
+					const handle = this.deps.store.peek(entry.key);
+					if (!handle) {
+						stale.push(entry.key);
+						continue;
+					}
+					paint.push({
+						key: entry.key,
+						scale: entry.scale,
+						rect: bleedPx > 0 ? bleedRect(entry.rect, bleedPx / entry.scale, page) : entry.rect,
+						z: 0,
+						handle
+					});
+				}
 			} else if (entry.scale === wantScale) fetching.push(entry.key);
 		}
+		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 plan = {
 			engaged: true,
@@ -339,62 +512,95 @@ var TileManager = class {
 		};
 		return plan;
 	}
-	/** The layer's decode-boundary report: this key's <img> actually painted. */
-	sourcePainted(pon, key) {
-		const state = this.pages.get(pon);
+	/** 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));
 		const entry = state?.entries.get(key);
 		if (!state || !entry || entry.painted) return;
 		entry.painted = true;
-		this.releaseOccluded(state, entry);
+		const page = this.deps.getPageSize(pon);
+		if (page) this.releaseCovered(pon, state, page, annotationsOf(key));
 		state.version += 1;
 		state.planCache = null;
 		this.deps.onAdvance(pon);
 	}
-	/** A lens unmounted its TileLayer: stop fetching, drop bookkeeping.
+	/**
+	* 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
+	* 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.
+	*/
+	sourceUnpainted(view, pon, key) {
+		const entry = this.pages.get(stateKey(view, pon))?.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(pon) {
-		const state = this.pages.get(pon);
+	releasePage(view, pon) {
+		const state = this.pages.get(stateKey(view, pon));
 		if (!state) return;
 		this.abortAll(state);
-		this.pages.delete(pon);
+		this.pages.delete(stateKey(view, pon));
 	}
-	pageState(pon) {
-		let state = this.pages.get(pon);
+	pageState(pon, view) {
+		let state = this.pages.get(stateKey(view, pon));
 		if (!state) {
 			state = {
 				epoch: -1,
 				wantScale: null,
+				wantWidth: null,
 				entries: /* @__PURE__ */ new Map(),
+				failedKeys: /* @__PURE__ */ new Set(),
 				version: 0,
 				planCache: null,
 				settleTimer: null,
 				pendingLevel: null,
 				lastVisible: null
 			};
-			this.pages.set(pon, state);
+			this.pages.set(stateKey(view, pon), state);
 		}
 		return state;
 	}
-	schedule(pon, state, page, grid, wantScale, includeAnnotations, epoch, p0, p1) {
-		const { config } = this.deps;
-		const firstEngage = state.wantScale === null;
-		const levelChanged = state.wantScale !== null && state.wantScale !== wantScale;
+	schedule(pon, state, page, grid, wantScale, wantWidth, includeAnnotations, epoch, p0, p1, visible) {
+		const { options } = this.deps;
+		const firstEngage = state.wantWidth === null;
+		const levelChanged = state.wantWidth !== null && state.wantWidth !== wantWidth;
+		if (levelChanged) state.failedKeys.clear();
 		state.wantScale = wantScale;
-		const wanted = new Set([...p0, ...p1].map((c) => this.tileKey(pon, wantScale, c, includeAnnotations, epoch)));
-		for (const [key, entry] of state.entries) if (entry.handle === void 0 && !wanted.has(key)) {
-			entry.abort?.abort();
-			state.entries.delete(key);
+		state.wantWidth = wantWidth;
+		const wanted = new Set([...p0, ...p1].map((c) => this.tileKey(pon, wantWidth, c, includeAnnotations, epoch)));
+		for (const [key, entry] of state.entries) {
+			if (wanted.has(key)) continue;
+			if (!entry.resolved) {
+				entry.abort?.abort();
+				this.releaseSlot(entry);
+				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 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 kickoff = () => {
-			if (this.ensureFetches(pon, state, page, grid, includeAnnotations, epoch, p0)) this.ensureFetches(pon, state, page, grid, includeAnnotations, epoch, p1);
+			if (this.ensureFetches(pon, state, page, grid, wantWidth, includeAnnotations, epoch, orderedP0)) this.ensureFetches(pon, state, page, grid, wantWidth, includeAnnotations, epoch, p1);
 		};
-		if (levelChanged && config.settleMs > 0) {
-			state.pendingLevel = wantScale;
+		if (levelChanged && options.tiles.settleMs > 0) {
+			this.deps.debug?.(`arm settle pon=${pon} level=${wantWidth}`);
+			state.pendingLevel = wantWidth;
 			if (state.settleTimer !== null) clearTimeout(state.settleTimer);
 			state.settleTimer = setTimeout(() => {
 				state.settleTimer = null;
-				if (state.pendingLevel === wantScale) kickoff();
-			}, config.settleMs);
+				this.deps.debug?.(`settle fired pon=${pon} level=${wantWidth} current=${state.pendingLevel === wantWidth}`);
+				if (state.pendingLevel === wantWidth) kickoff();
+			}, options.tiles.settleMs);
 			return;
 		}
 		if (state.settleTimer !== null && !levelChanged && !firstEngage) {
@@ -405,95 +611,177 @@ var TileManager = class {
 		kickoff();
 	}
 	/** Start missing fetches; true when every coord is already resolved. */
-	ensureFetches(pon, state, page, grid, includeAnnotations, epoch, coords) {
+	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, grid.scale, coord, includeAnnotations, epoch);
+			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.handle === void 0) allReady = false;
+				if (!existing.resolved) allReady = false;
 				continue;
 			}
 			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,
 				coord,
-				rect: tilePaintRect(grid, page, coord),
+				rect: logical,
+				resolved: false,
 				painted: false,
+				charged: true,
 				abort
 			};
 			state.entries.set(key, entry);
-			this.deps.store.acquire(key, (signal) => this.deps.fetchTile(pon, tileEngineRect(grid, page, coord), grid.scale, includeAnnotations, signal), abort.signal).then((handle) => {
+			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;
-				entry.handle = handle;
+				entry.resolved = true;
 				state.version += 1;
 				state.planCache = null;
 				this.deps.onAdvance(pon);
-			}, () => {
-				if (state.entries.get(key) === entry) state.entries.delete(key);
+			}, (err) => {
+				this.releaseSlot(entry);
+				if (state.entries.get(key) !== entry) return;
+				state.entries.delete(key);
+				if (!abort.signal.aborted) {
+					state.failedKeys.add(key);
+					this.deps.debug?.(`tile failed ${key}: ${String(err)}`);
+					state.version += 1;
+					state.planCache = null;
+					this.deps.onAdvance(pon);
+				}
 			});
 		}
+		if (started > 0) this.deps.debug?.(`fetch pon=${pon} level=${wantWidth} +${started} tiles`);
 		return allReady;
 	}
 	/**
-	* The release rule: after `painted` lands on a want-level tile, retained
-	* sources (any other level) whose footprint ∩ painted-tile region is
-	* covered by PAINTED want-level tiles leave the paint list. Index
-	* arithmetic via the aligned grid — no rectangle geometry.
+	* 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
+	* 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
+	* mix of retained scales exists (exact levels included).
 	*/
-	releaseOccluded(state, painted) {
-		const wantScale = state.wantScale;
-		if (wantScale === null || painted.scale !== wantScale) return;
-		const page = this.deps.getPageSize(pagePonOf(painted.key));
-		if (!page) return;
-		const grid = tileGrid(page, wantScale, this.deps.config.tileSize);
+	releaseCovered(pon, state, page, includeAnnotations) {
+		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(pagePonOf(painted.key), wantScale, c, annotationsOf(painted.key), state.epoch);
+			const key = this.tileKey(pon, wantWidth, c, includeAnnotations, state.epoch);
 			return state.entries.get(key)?.painted === true;
 		};
+		let released = false;
 		for (const [key, entry] of state.entries) {
-			if (entry.scale === wantScale || entry.handle === void 0) continue;
-			const overlap = intersectRects(entry.rect, painted.rect);
-			if (overlap.width <= 0 || overlap.height <= 0) continue;
-			if (regionCovered(grid, page, state.lastVisible ? intersectRects(entry.rect, state.lastVisible) : entry.rect, paintedAt)) state.entries.delete(key);
+			if (entry.scale === wantScale || !entry.resolved) continue;
+			const region = state.lastVisible ? intersectRects(entry.rect, state.lastVisible) : entry.rect;
+			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}`;
+				});
+				this.deps.debug(`retained ${key} blocked by: ${detail.join(" ")} (${missing.length} missing)`);
+			}
 		}
+		return released;
+	}
+	/** Test/diagnostic introspection: bookkeeping size for one page. */
+	stats(view, pon) {
+		return {
+			entries: this.pages.get(stateKey(view, pon))?.entries.size ?? 0,
+			inFlight: this.inFlight
+		};
+	}
+	/** 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;
 		}
-		for (const entry of state.entries.values()) if (entry.handle === void 0) entry.abort?.abort();
+		for (const entry of state.entries.values()) if (!entry.resolved) {
+			entry.abort?.abort();
+			this.releaseSlot(entry);
+		}
 	}
-	tileKey(pon, scale, c, includeAnnotations, epoch) {
-		return `t:${pon}|s${scale}|${c.ix},${c.iy}|a${includeAnnotations ? 1 : 0}|e${epoch}`;
+	/** 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
+	*  (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;
+		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}`;
 	}
 };
-const widthOf = (v) => v.kind === "width" && v.width !== void 0 ? v.width : Number.POSITIVE_INFINITY;
 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)}`;
-/** Stacking: position in the ascending pyramid (coarse under fine). */
-const zOf = (pyramid, scale) => {
-	const sorted = [...pyramid].sort((a, b) => a - b);
-	const idx = sorted.indexOf(scale);
-	return idx === -1 ? sorted.findIndex((s) => s > scale) : idx;
-};
-const pagePonOf = (key) => Number(key.slice(2, key.indexOf("|")));
 const annotationsOf = (key) => key.includes("|a1|");
 //#endregion
 //#region src/capability.ts
 /**
-* The render capability: the ONE policy consumer in the client stack
-* (the three-layer rule). The engine never snaps; framework
-* layers never see the policy; everything between — conforming a desired
-* scale to the deployment lattice, collapsing same-rung asks in the raster
-* store, exposing stable source keys — happens here.
+* 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.
 */
 function createRenderCapability(ctx, options = {}) {
+	const resolved = resolveRenderOptions(options);
 	const store = new RasterStore();
 	const policy = () => ctx.document()?.renderPolicy ?? 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;
+	};
+	let warnedFormat = false;
+	const warnDroppedFormat = (s) => {
+		if (warnedFormat || resolved.format === void 0 || s.format === resolved.format) return;
+		warnedFormat = true;
+		console.warn(`[render] format '${resolved.format}' is not in the deployment's formats — using '${s.format}'.`);
+	};
+	let warnedBudget = false;
+	const warnPastBudgetNoTiles = (demandWidth, supplied) => {
+		if (warnedBudget || resolved.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);
@@ -501,32 +789,53 @@ function createRenderCapability(ctx, options = {}) {
 		return page.size.width;
 	};
 	const conformViewport = (pon, scale) => {
-		const p = policy();
-		if (p.kind !== "lattice") return {
-			kind: "scale",
-			scale
+		const s = strategy();
+		const demandWidth = scale * pageWidthOf(pon);
+		const width = baseAskWidth(s, demandWidth);
+		warnPastBudgetNoTiles(demandWidth, width);
+		return {
+			kind: "width",
+			width
 		};
-		return snapFullPageViewport(p, {
-			kind: "scale",
-			scale
-		}, { pageWidth: pageWidthOf(pon) });
 	};
-	const viewportKey = (viewport) => viewport.kind === "width" ? `w${viewport.width}` : `s${viewport.scale ?? 1}`;
 	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 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);
+		if (advanceScheduled) return;
+		advanceScheduled = true;
+		raf(() => {
+			advanceScheduled = false;
+			const pons = [...pendingAdvance];
+			pendingAdvance.clear();
+			for (const p of pons) ctx.dispatch({
+				type: "PAINT_ADVANCED",
+				pon: p
+			});
+		});
+	};
+	const viewTiles = /* @__PURE__ */ new Map();
 	const tiles = new TileManager({
 		store,
-		config: resolveTiling(options.tiling),
+		options: resolved,
 		getPolicy: policy,
 		getPageSize: (pon) => pageOf(pon)?.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"));
+			const s = strategy();
 			const task = doc.page(pon).render.image({
 				target: {
 					kind: "rect",
@@ -536,16 +845,16 @@ function createRenderCapability(ctx, options = {}) {
 					kind: "scale",
 					scale
 				},
-				includeAnnotations
+				includeAnnotations,
+				...s.format !== void 0 ? { format: s.format } : {},
+				...s.quality !== void 0 ? { quality: s.quality } : {}
 			});
 			if (signal.aborted) task.abort(signal.reason);
 			else signal.addEventListener("abort", () => task.abort(signal.reason), { once: true });
 			return task;
 		},
-		onAdvance: (pon) => ctx.dispatch({
-			type: "PAINT_ADVANCED",
-			pon
-		})
+		onAdvance: wake,
+		...resolved.debug ? { debug: (msg) => console.debug(`[render] ${msg}`) } : {}
 	});
 	return {
 		renderPage(pon, { scale, includeAnnotations, signal }) {
@@ -553,11 +862,14 @@ function createRenderCapability(ctx, options = {}) {
 			if (!doc) return Promise.reject(/* @__PURE__ */ new Error("render: no document bound"));
 			const annotations = includeAnnotations ?? true;
 			const viewport = conformViewport(pon, scale);
-			const key = `${pon}|${viewportKey(viewport)}|a${annotations ? 1 : 0}|e${epochOf(pon, annotations)}`;
+			const key = baseKey(pon, viewport, annotations);
 			return store.acquire(key, (storeSignal) => {
+				const s = strategy();
 				const task = doc.page(pon).render.image({
 					viewport,
-					includeAnnotations: annotations
+					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 });
@@ -566,19 +878,28 @@ function createRenderCapability(ctx, options = {}) {
 		},
 		renderSourceKey(pon, { scale, includeAnnotations }) {
 			const annotations = includeAnnotations ?? true;
-			const viewport = conformViewport(pon, scale);
-			return `${pon}|${viewportKey(viewport)}|a${annotations ? 1 : 0}|e${epochOf(pon, annotations)}`;
+			return baseKey(pon, conformViewport(pon, scale), annotations);
 		},
 		conformViewport,
-		renderPolicy: policy,
-		tilePlan(pon, demand, opts) {
-			return tiles.plan(pon, demand, opts?.includeAnnotations ?? true);
-		},
-		tilePainted(pon, key) {
-			tiles.sourcePainted(pon, key);
+		paintSettings() {
+			return {
+				fadeMs: resolved.tiles.fadeMs,
+				tiles: resolved.tiles.enabled
+			};
 		},
-		releaseTiles(pon) {
-			tiles.releasePage(pon);
+		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);
+			}
+			return handle;
 		},
 		renderEpoch(pon, includeAnnotations = true) {
 			return epochOf(pon, includeAnnotations);