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

package/dist/index.d.cts

@@ -209,6 +209,45 @@ type RenderAction = {
   type: 'PAINT_ADVANCED';
   pon: PageObjectNumber;
 };
+/**
+ * One view's scoped tile surface (see {@link RenderCapability.tilesFor}).
+ * Identity (the view) is bound at creation; every call addresses that view's
+ * own state for the given page.
+ */
+interface ViewTiles {
+  /**
+   * The tile paint plan for a page under this view's demand. Tiling is a
+   * STRATEGY inside this plugin, not a sibling.
+   * Memoized: the same object returns until the demand, an epoch, or a
+   * tile resolution actually changes it, so layers can subscribe with
+   * plain `Object.is`. Calling it schedules the want-set fetches (visible
+   * first, center-out, prefetch ring after) — idempotent, store-deduped.
+   * Engagement is pure arithmetic against what the base will ACTUALLY
+   * supply (the same `baseAsk` the base layer sizes with): tiles fire when
+   * demand exceeds the budget/ladder cap × engageAt — on every engine.
+   * A thumbnail-sized demand never engages.
+   */
+  plan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
+    includeAnnotations?: boolean;
+  }): TilePaintPlan;
+  /**
+   * The painter's report: the image for this plan key had a presentation
+   * opportunity. Retained coarser generations covered by painted want-set
+   * tiles release on this signal — never on fetch completion or image load,
+   * which could drop the backdrop before replacement pixels are presented.
+   */
+  painted(pon: PageObjectNumber, key: string): void;
+  /**
+   * The inverse report: this plan key's <img> left the DOM, so its pixels
+   * are no longer compositable. Painted is a statement about the SCREEN and
+   * must follow the DOM — a remounting tile re-decodes, and until it
+   * reports painted again, retention may not count it as coverage.
+   */
+  unpainted(pon: PageObjectNumber, key: string): void;
+  /** This view unmounted its tile plane for the page: abort in-flight tile
+   *  fetches, drop ITS bookkeeping (resolved bytes stay cached). */
+  release(pon: PageObjectNumber): void;
+}
 interface RenderCapability {
   /**
    * Render a page (by its durable pon) to an ENCODED image. Abortable. Encoded
@@ -247,37 +286,16 @@ interface RenderCapability {
   /** The document's advertised policy (sugar over `DocumentMeta.renderPolicy`). */
   renderPolicy(): EngineRenderPolicy;
   /**
-   * The tile paint plan for a page under a host-supplied demand. Tiling is a
-   * STRATEGY inside this plugin, not a sibling.
-   * Memoized: the same object returns until the demand, an epoch, or a
-   * tile resolution actually changes it, so layers can subscribe with
-   * plain `Object.is`. Calling it schedules the want-set fetches (visible
-   * first, center-out, prefetch ring after) — idempotent, store-deduped.
-   * Engagement is pure arithmetic against what the base will ACTUALLY
-   * supply (the same `baseAsk` the base layer sizes with): tiles fire when
-   * demand exceeds the budget/ladder cap × engageAt — on every engine.
-   * A thumbnail-sized demand never engages.
-   */
-  tilePlan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
-    includeAnnotations?: boolean;
-  }): TilePaintPlan;
-  /**
-   * The painter's report: the image for this plan key had a presentation
-   * opportunity. Retained coarser generations covered by painted want-set
-   * tiles release on this signal — never on fetch completion or image load,
-   * which could drop the backdrop before replacement pixels are presented.
-   */
-  tilePainted(pon: PageObjectNumber, key: string): void;
-  /**
-   * The inverse report: this plan key's <img> left the DOM, so its pixels
-   * are no longer compositable. Painted is a statement about the SCREEN and
-   * must follow the DOM — a remounting tile re-decodes, and until it
-   * reports painted again, retention may not count it as coverage.
+   * This view's tile surface — the ONE tile entry point. `view` is the
+   * consuming view's identity (`PageContextValue.view`: a stage lens id, or
+   * a PageView instance id). Tile state is kept PER VIEW × PAGE, so two
+   * views showing the same page plan independently — a thumbnail rail's
+   * never-engaging demand cannot disturb the main view's tiles. Binding the
+   * identity ONCE makes it unforgettable and unmixable: the handle's four
+   * calls can never disagree about whose state they address. Stable per
+   * view — safe as a hook/effect dependency.
    */
-  tileUnpainted(pon: PageObjectNumber, key: string): void;
-  /** A lens unmounted its tile plane: abort in-flight tile fetches and drop
-   *  the page's tile bookkeeping (resolved bytes stay cached). */
-  releaseTiles(pon: PageObjectNumber): void;
+  tilesFor(view: string): ViewTiles;
   /**
    * Version of the raster the given options would produce. Key a long-lived
    * render on it: when it bumps, refetch. Base renders version on content

package/dist/index.d.ts

@@ -209,6 +209,45 @@ type RenderAction = {
   type: 'PAINT_ADVANCED';
   pon: PageObjectNumber;
 };
+/**
+ * One view's scoped tile surface (see {@link RenderCapability.tilesFor}).
+ * Identity (the view) is bound at creation; every call addresses that view's
+ * own state for the given page.
+ */
+interface ViewTiles {
+  /**
+   * The tile paint plan for a page under this view's demand. Tiling is a
+   * STRATEGY inside this plugin, not a sibling.
+   * Memoized: the same object returns until the demand, an epoch, or a
+   * tile resolution actually changes it, so layers can subscribe with
+   * plain `Object.is`. Calling it schedules the want-set fetches (visible
+   * first, center-out, prefetch ring after) — idempotent, store-deduped.
+   * Engagement is pure arithmetic against what the base will ACTUALLY
+   * supply (the same `baseAsk` the base layer sizes with): tiles fire when
+   * demand exceeds the budget/ladder cap × engageAt — on every engine.
+   * A thumbnail-sized demand never engages.
+   */
+  plan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
+    includeAnnotations?: boolean;
+  }): TilePaintPlan;
+  /**
+   * The painter's report: the image for this plan key had a presentation
+   * opportunity. Retained coarser generations covered by painted want-set
+   * tiles release on this signal — never on fetch completion or image load,
+   * which could drop the backdrop before replacement pixels are presented.
+   */
+  painted(pon: PageObjectNumber, key: string): void;
+  /**
+   * The inverse report: this plan key's <img> left the DOM, so its pixels
+   * are no longer compositable. Painted is a statement about the SCREEN and
+   * must follow the DOM — a remounting tile re-decodes, and until it
+   * reports painted again, retention may not count it as coverage.
+   */
+  unpainted(pon: PageObjectNumber, key: string): void;
+  /** This view unmounted its tile plane for the page: abort in-flight tile
+   *  fetches, drop ITS bookkeeping (resolved bytes stay cached). */
+  release(pon: PageObjectNumber): void;
+}
 interface RenderCapability {
   /**
    * Render a page (by its durable pon) to an ENCODED image. Abortable. Encoded
@@ -247,37 +286,16 @@ interface RenderCapability {
   /** The document's advertised policy (sugar over `DocumentMeta.renderPolicy`). */
   renderPolicy(): EngineRenderPolicy;
   /**
-   * The tile paint plan for a page under a host-supplied demand. Tiling is a
-   * STRATEGY inside this plugin, not a sibling.
-   * Memoized: the same object returns until the demand, an epoch, or a
-   * tile resolution actually changes it, so layers can subscribe with
-   * plain `Object.is`. Calling it schedules the want-set fetches (visible
-   * first, center-out, prefetch ring after) — idempotent, store-deduped.
-   * Engagement is pure arithmetic against what the base will ACTUALLY
-   * supply (the same `baseAsk` the base layer sizes with): tiles fire when
-   * demand exceeds the budget/ladder cap × engageAt — on every engine.
-   * A thumbnail-sized demand never engages.
-   */
-  tilePlan(pon: PageObjectNumber, demand: PageViewDemand, opts?: {
-    includeAnnotations?: boolean;
-  }): TilePaintPlan;
-  /**
-   * The painter's report: the image for this plan key had a presentation
-   * opportunity. Retained coarser generations covered by painted want-set
-   * tiles release on this signal — never on fetch completion or image load,
-   * which could drop the backdrop before replacement pixels are presented.
-   */
-  tilePainted(pon: PageObjectNumber, key: string): void;
-  /**
-   * The inverse report: this plan key's <img> left the DOM, so its pixels
-   * are no longer compositable. Painted is a statement about the SCREEN and
-   * must follow the DOM — a remounting tile re-decodes, and until it
-   * reports painted again, retention may not count it as coverage.
+   * This view's tile surface — the ONE tile entry point. `view` is the
+   * consuming view's identity (`PageContextValue.view`: a stage lens id, or
+   * a PageView instance id). Tile state is kept PER VIEW × PAGE, so two
+   * views showing the same page plan independently — a thumbnail rail's
+   * never-engaging demand cannot disturb the main view's tiles. Binding the
+   * identity ONCE makes it unforgettable and unmixable: the handle's four
+   * calls can never disagree about whose state they address. Stable per
+   * view — safe as a hook/effect dependency.
    */
-  tileUnpainted(pon: PageObjectNumber, key: string): void;
-  /** A lens unmounted its tile plane: abort in-flight tile fetches and drop
-   *  the page's tile bookkeeping (resolved bytes stay cached). */
-  releaseTiles(pon: PageObjectNumber): void;
+  tilesFor(view: string): ViewTiles;
   /**
    * Version of the raster the given options would produce. Key a long-lived
    * render on it: when it bumps, refetch. Base renders version on content

package/dist/index.js

@@ -373,6 +373,8 @@ function snapToPyramid(scales, needed) {
 * 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. */
@@ -393,14 +395,14 @@ var TileManager = class {
 		};
 		return this.strategyMemo.strategy;
 	}
-	plan(pon, demand, includeAnnotations) {
+	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();
@@ -511,8 +513,8 @@ var TileManager = class {
 		return plan;
 	}
 	/** The layer's painted report: this key's pixels had a presentation opportunity. */
-	sourcePainted(pon, key) {
-		const state = this.pages.get(pon);
+	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;
@@ -530,20 +532,20 @@ var TileManager = class {
 	* 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(pon, key) {
-		const entry = this.pages.get(pon)?.entries.get(key);
+	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,
@@ -557,7 +559,7 @@ var TileManager = class {
 				pendingLevel: null,
 				lastVisible: null
 			};
-			this.pages.set(pon, state);
+			this.pages.set(stateKey(view, pon), state);
 		}
 		return state;
 	}
@@ -702,9 +704,9 @@ var TileManager = class {
 		return released;
 	}
 	/** Test/diagnostic introspection: bookkeeping size for one page. */
-	stats(pon) {
+	stats(view, pon) {
 		return {
-			entries: this.pages.get(pon)?.entries.size ?? 0,
+			entries: this.pages.get(stateKey(view, pon))?.entries.size ?? 0,
 			inFlight: this.inFlight
 		};
 	}
@@ -823,6 +825,7 @@ function createRenderCapability(ctx, options = {}) {
 			});
 		});
 	};
+	const viewTiles = /* @__PURE__ */ new Map();
 	const tiles = new TileManager({
 		store,
 		options: resolved,
@@ -885,17 +888,18 @@ function createRenderCapability(ctx, options = {}) {
 			};
 		},
 		renderPolicy: policy,
-		tilePlan(pon, demand, opts) {
-			return tiles.plan(pon, demand, opts?.includeAnnotations ?? true);
-		},
-		tilePainted(pon, key) {
-			tiles.sourcePainted(pon, key);
-		},
-		tileUnpainted(pon, key) {
-			tiles.sourceUnpainted(pon, key);
-		},
-		releaseTiles(pon) {
-			tiles.releasePage(pon);
+		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);