@embedpdf/react 3.0.0-next.4 → 3.0.0-next.6

package/dist/page-view.js

@@ -1,6 +1,8 @@
 import { DocumentScope, PageProvider, makePageContext, useActiveDocumentId, useKernel } from "./runtime.js";
+import { ProjectorProvider } from "./anchored.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useMemo, useRef } from "react";
+import { observeClientGeometry } from "@embedpdf/web";
 import { NO_FRAME, pageTransform } from "@embedpdf/core-geometry";
 //#region src/page-view.tsx
 /** A single page surface with NO Stage — same layers + rotation + chrome frame,
@@ -42,6 +44,21 @@ function PageView({ page, documentId, width = 240, pageFrame = NO_FRAME, childre
 		pageFrame,
 		transform
 	]);
+	const projector = useMemo(() => ({
+		space: "client",
+		toScreen: (p, rect) => p === ctx.pon && ref.current ? ctx.toClientRect(rect) : null,
+		toScreenPoint: (p, at) => p === ctx.pon && ref.current ? ctx.toClientPoint(at) : null,
+		viewEnv: (p) => p === ctx.pon ? {
+			scale: ctx.transform.viewScale,
+			rotation: ctx.transform.rotation,
+			zoom: ctx.transform.zoom
+		} : null
+	}), [ctx]);
+	const projectorBinding = useMemo(() => ({
+		projector,
+		revision: ctx,
+		subscribe: observeClientGeometry
+	}), [projector, ctx]);
 	if (!docId || !meta || !base) return null;
 	const t = transform;
 	const outerW = t.viewWidth + pageFrame.left + pageFrame.right;
@@ -50,41 +67,44 @@ function PageView({ page, documentId, width = 240, pageFrame = NO_FRAME, childre
 	const contentTop = pageFrame.top + (t.viewHeight - t.contentHeight) / 2;
 	return /* @__PURE__ */ jsx(DocumentScope, {
 		id: docId,
-		children: /* @__PURE__ */ jsx("div", {
-			style: {
-				position: "relative",
-				width: outerW,
-				height: outerH,
-				...style
-			},
-			children: /* @__PURE__ */ jsxs(PageProvider, {
-				value: ctx,
-				children: [
-					/* @__PURE__ */ jsx("div", { style: {
-						position: "absolute",
-						left: pageFrame.left,
-						top: pageFrame.top,
-						width: t.viewWidth,
-						height: t.viewHeight,
-						boxShadow: "0 6px 18px rgba(0,0,0,.18)"
-					} }),
-					/* @__PURE__ */ jsx("div", {
-						ref,
-						style: {
+		children: /* @__PURE__ */ jsx(ProjectorProvider, {
+			value: projectorBinding,
+			children: /* @__PURE__ */ jsx("div", {
+				style: {
+					position: "relative",
+					width: outerW,
+					height: outerH,
+					...style
+				},
+				children: /* @__PURE__ */ jsxs(PageProvider, {
+					value: ctx,
+					children: [
+						/* @__PURE__ */ jsx("div", { style: {
 							position: "absolute",
-							left: contentLeft,
-							top: contentTop,
-							width: t.contentWidth,
-							height: t.contentHeight,
-							background: "#fff",
-							transform: rotation ? `rotate(${rotation}deg)` : void 0,
-							userSelect: "none",
-							WebkitUserSelect: "none"
-						},
-						children
-					}),
-					pageChrome
-				]
+							left: pageFrame.left,
+							top: pageFrame.top,
+							width: t.viewWidth,
+							height: t.viewHeight,
+							boxShadow: "0 6px 18px rgba(0,0,0,.18)"
+						} }),
+						/* @__PURE__ */ jsx("div", {
+							ref,
+							style: {
+								position: "absolute",
+								left: contentLeft,
+								top: contentTop,
+								width: t.contentWidth,
+								height: t.contentHeight,
+								background: "#fff",
+								transform: rotation ? `rotate(${rotation}deg)` : void 0,
+								userSelect: "none",
+								WebkitUserSelect: "none"
+							},
+							children
+						}),
+						pageChrome
+					]
+				})
 			})
 		})
 	});

package/dist/page-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"page-view.js","names":[],"sources":["../src/page-view.tsx"],"sourcesContent":["/**\n * <PageView> — a single page surface with NO Stage.\n *\n * Same layers + rotation + chrome frame as a `<Stage>` page, but no\n * camera/scroll/zoom and, crucially, NO dependency on `@embedpdf/plugin-stage`.\n * It builds its own `PageTransform` from a target content width and shares the\n * exact `PageContext` seam, so every layer (RenderLayer, AnnotationLayer,\n * PageAnnotationMenu, …) works here identically.\n */\nimport * as React from 'react';\nimport { useMemo, useRef } from 'react';\nimport { NO_FRAME, pageTransform, type PageFrame } from '@embedpdf/core-geometry';\nimport {\n  DocumentScope,\n  makePageContext,\n  PageProvider,\n  useActiveDocumentId,\n  useKernel,\n} from './runtime';\n\nexport interface PageViewProps {\n  page: number;\n  /** Which document to show. Defaults to the active document. */\n  documentId?: string;\n  /** Target width for the page CONTENT; the display box is the rotated footprint. */\n  width?: number;\n  /** Reserved chrome bands around the page (screen px) — same model as `<Stage>`. */\n  pageFrame?: PageFrame;\n  /** Page-space content (rotates with the page). */\n  children: React.ReactNode;\n  /** Box-space chrome (label, border, …) — never rotated. Mirrors `<Stage pageChrome>`. */\n  pageChrome?: React.ReactNode;\n  style?: React.CSSProperties;\n}\n\n/** A single page surface with NO Stage — same layers + rotation + chrome frame,\n *  no camera/scroll/zoom. */\nexport function PageView({\n  page,\n  documentId,\n  width = 240,\n  pageFrame = NO_FRAME,\n  children,\n  pageChrome,\n  style,\n}: PageViewProps) {\n  const kernel = useKernel();\n  const active = useActiveDocumentId();\n  const ref = useRef<HTMLDivElement>(null);\n  const docId = documentId ?? active;\n  const meta = docId ? kernel.getState().core.documents[docId] : undefined;\n  const base = meta?.pages[page];\n  const pon = base?.pageObjectNumber ?? page + 1;\n  const rotation = base?.rotation ?? 0;\n  const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;\n  // Standalone (no Stage/camera): build the page's transform from the target\n  // content `width` directly. `scale` is view px per point = width / pageWidthPts.\n  const transform = useMemo(\n    () =>\n      pageTransform({\n        pageSize: base\n          ? { width: base.size.width, height: base.size.height }\n          : { width: 1, height: 1 },\n        rotation,\n        scale: base ? width / base.size.width : 1,\n        // Physical 100% on the web: 1pt = 96/72 CSS px, times the page's\n        // /UserUnit — so `transform.zoom` is meaningful even without a Stage\n        // (a thumbnail-sized PageView reads as zoomed out, as it should).\n        baseScale: (96 / 72) * (base?.userUnit ?? 1),\n        dpr,\n      }),\n    [base?.size.width, base?.size.height, base?.userUnit, rotation, width, dpr],\n  );\n  const ctx = useMemo(\n    () =>\n      makePageContext(docId ?? '', pon, page, pageFrame, transform, () =>\n        ref.current!.getBoundingClientRect(),\n      ),\n    [docId, pon, page, pageFrame, transform],\n  );\n  if (!docId || !meta || !base) return null;\n  const t = transform;\n  const outerW = t.viewWidth + pageFrame.left + pageFrame.right;\n  const outerH = t.viewHeight + pageFrame.top + pageFrame.bottom;\n  const contentLeft = pageFrame.left + (t.viewWidth - t.contentWidth) / 2;\n  const contentTop = pageFrame.top + (t.viewHeight - t.contentHeight) / 2;\n  return (\n    <DocumentScope id={docId}>\n      <div style={{ position: 'relative', width: outerW, height: outerH, ...style }}>\n        <PageProvider value={ctx}>\n          {/* drop shadow ONLY — transparent, axis-aligned, can't leak behind the bitmap */}\n          <div\n            style={{\n              position: 'absolute',\n              left: pageFrame.left,\n              top: pageFrame.top,\n              width: t.viewWidth,\n              height: t.viewHeight,\n              boxShadow: '0 6px 18px rgba(0,0,0,.18)',\n            }}\n          />\n          {/* white backing + content as ONE box; rotation 0 carries no transform */}\n          <div\n            ref={ref}\n            style={{\n              position: 'absolute',\n              left: contentLeft,\n              top: contentTop,\n              width: t.contentWidth,\n              height: t.contentHeight,\n              background: '#fff',\n              transform: rotation ? `rotate(${rotation}deg)` : undefined,\n              userSelect: 'none',\n              WebkitUserSelect: 'none',\n            }}\n          >\n            {children}\n          </div>\n          {pageChrome}\n        </PageProvider>\n      </div>\n    </DocumentScope>\n  );\n}\n"],"mappings":";;;;;;;AAqCA,SAAgB,SAAS,EACvB,MACA,YACA,QAAQ,KACR,YAAY,UACZ,UACA,YACA,SACgB;CAChB,MAAM,SAAS,UAAU;CACzB,MAAM,SAAS,oBAAoB;CACnC,MAAM,MAAM,OAAuB,IAAI;CACvC,MAAM,QAAQ,cAAc;CAC5B,MAAM,OAAO,QAAQ,OAAO,SAAS,CAAC,CAAC,KAAK,UAAU,SAAS,KAAA;CAC/D,MAAM,OAAO,MAAM,MAAM;CACzB,MAAM,MAAM,MAAM,oBAAoB,OAAO;CAC7C,MAAM,WAAW,MAAM,YAAY;CACnC,MAAM,MAAM,OAAO,WAAW,cAAc,OAAO,oBAAoB,IAAI;CAG3E,MAAM,YAAY,cAEd,cAAc;EACZ,UAAU,OACN;GAAE,OAAO,KAAK,KAAK;GAAO,QAAQ,KAAK,KAAK;EAAO,IACnD;GAAE,OAAO;GAAG,QAAQ;EAAE;EAC1B;EACA,OAAO,OAAO,QAAQ,KAAK,KAAK,QAAQ;EAIxC,WAAY,KAAK,MAAO,MAAM,YAAY;EAC1C;CACF,CAAC,GACH;EAAC,MAAM,KAAK;EAAO,MAAM,KAAK;EAAQ,MAAM;EAAU;EAAU;EAAO;CAAG,CAC5E;CACA,MAAM,MAAM,cAER,gBAAgB,SAAS,IAAI,KAAK,MAAM,WAAW,iBACjD,IAAI,QAAS,sBAAsB,CACrC,GACF;EAAC;EAAO;EAAK;EAAM;EAAW;CAAS,CACzC;CACA,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,OAAO;CACrC,MAAM,IAAI;CACV,MAAM,SAAS,EAAE,YAAY,UAAU,OAAO,UAAU;CACxD,MAAM,SAAS,EAAE,aAAa,UAAU,MAAM,UAAU;CACxD,MAAM,cAAc,UAAU,QAAQ,EAAE,YAAY,EAAE,gBAAgB;CACtE,MAAM,aAAa,UAAU,OAAO,EAAE,aAAa,EAAE,iBAAiB;CACtE,OACE,oBAAC,eAAD;EAAe,IAAI;EACjB,UAAA,oBAAC,OAAD;GAAK,OAAO;IAAE,UAAU;IAAY,OAAO;IAAQ,QAAQ;IAAQ,GAAG;GAAM;GAC1E,UAAA,qBAAC,cAAD;IAAc,OAAO;IAArB,UAAA;KAEE,oBAAC,OAAD,EACE,OAAO;MACL,UAAU;MACV,MAAM,UAAU;MAChB,KAAK,UAAU;MACf,OAAO,EAAE;MACT,QAAQ,EAAE;MACV,WAAW;KACb,EACD,CAAA;KAED,oBAAC,OAAD;MACO;MACL,OAAO;OACL,UAAU;OACV,MAAM;OACN,KAAK;OACL,OAAO,EAAE;OACT,QAAQ,EAAE;OACV,YAAY;OACZ,WAAW,WAAW,UAAU,SAAS,QAAQ,KAAA;OACjD,YAAY;OACZ,kBAAkB;MACpB;MAEC;KACE,CAAA;KACJ;IACW;;EACX,CAAA;CACQ,CAAA;AAEnB"}
+{"version":3,"file":"page-view.js","names":[],"sources":["../src/page-view.tsx"],"sourcesContent":["/**\n * <PageView> — a single page surface with NO Stage.\n *\n * Same layers + rotation + chrome frame as a `<Stage>` page, but no\n * camera/scroll/zoom and, crucially, NO dependency on `@embedpdf/plugin-stage`.\n * It builds its own `PageTransform` from a target content width and shares the\n * exact `PageContext` seam, so every layer (RenderLayer, AnnotationLayer, …)\n * works here identically — and it provides the measured `ViewProjector`, so\n * anchored UI (`<AnnotationMenu>`, `<SelectionMenu>`) works here too, portalled\n * and clipping-immune.\n */\nimport * as React from 'react';\nimport { useMemo, useRef } from 'react';\nimport { NO_FRAME, pageTransform, type PageFrame } from '@embedpdf/core-geometry';\nimport { observeClientGeometry } from '@embedpdf/web';\nimport { ProjectorProvider, type ProjectorBinding, type ViewProjector } from './anchored';\nimport {\n  DocumentScope,\n  makePageContext,\n  PageProvider,\n  useActiveDocumentId,\n  useKernel,\n} from './runtime';\n\nexport interface PageViewProps {\n  page: number;\n  /** Which document to show. Defaults to the active document. */\n  documentId?: string;\n  /** Target width for the page CONTENT; the display box is the rotated footprint. */\n  width?: number;\n  /** Reserved chrome bands around the page (screen px) — same model as `<Stage>`. */\n  pageFrame?: PageFrame;\n  /** Page-space content (rotates with the page). */\n  children: React.ReactNode;\n  /** Box-space chrome (label, border, …) — never rotated. Mirrors `<Stage pageChrome>`. */\n  pageChrome?: React.ReactNode;\n  style?: React.CSSProperties;\n}\n\n/** A single page surface with NO Stage — same layers + rotation + chrome frame,\n *  no camera/scroll/zoom. */\nexport function PageView({\n  page,\n  documentId,\n  width = 240,\n  pageFrame = NO_FRAME,\n  children,\n  pageChrome,\n  style,\n}: PageViewProps) {\n  const kernel = useKernel();\n  const active = useActiveDocumentId();\n  const ref = useRef<HTMLDivElement>(null);\n  const docId = documentId ?? active;\n  const meta = docId ? kernel.getState().core.documents[docId] : undefined;\n  const base = meta?.pages[page];\n  const pon = base?.pageObjectNumber ?? page + 1;\n  const rotation = base?.rotation ?? 0;\n  const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;\n  // Standalone (no Stage/camera): build the page's transform from the target\n  // content `width` directly. `scale` is view px per point = width / pageWidthPts.\n  const transform = useMemo(\n    () =>\n      pageTransform({\n        pageSize: base\n          ? { width: base.size.width, height: base.size.height }\n          : { width: 1, height: 1 },\n        rotation,\n        scale: base ? width / base.size.width : 1,\n        // Physical 100% on the web: 1pt = 96/72 CSS px, times the page's\n        // /UserUnit — so `transform.zoom` is meaningful even without a Stage\n        // (a thumbnail-sized PageView reads as zoomed out, as it should).\n        baseScale: (96 / 72) * (base?.userUnit ?? 1),\n        dpr,\n      }),\n    [base?.size.width, base?.size.height, base?.userUnit, rotation, width, dpr],\n  );\n  const ctx = useMemo(\n    () =>\n      makePageContext(docId ?? '', pon, page, pageFrame, transform, () =>\n        ref.current!.getBoundingClientRect(),\n      ),\n    [docId, pon, page, pageFrame, transform],\n  );\n  // The PageView's ViewProjector: no camera, so anchored UI positions by\n  // MEASURING the DOM (client space → portal + position:fixed, immune to\n  // ancestor overflow clipping). `toScreen` answers null until the page\n  // element has committed — <Anchored> forces one post-commit pass to pick\n  // it up. The binding's revision covers state-driven changes (a new\n  // transform/page); `observeClientGeometry` covers the genuinely\n  // browser-driven ones (document scroll, window resize) that no state\n  // change announces.\n  const projector = useMemo<ViewProjector>(\n    () => ({\n      space: 'client',\n      toScreen: (p, rect) => (p === ctx.pon && ref.current ? ctx.toClientRect(rect) : null),\n      toScreenPoint: (p, at) => (p === ctx.pon && ref.current ? ctx.toClientPoint(at) : null),\n      viewEnv: (p) =>\n        p === ctx.pon\n          ? {\n              scale: ctx.transform.viewScale,\n              rotation: ctx.transform.rotation,\n              zoom: ctx.transform.zoom,\n            }\n          : null,\n    }),\n    [ctx],\n  );\n  const projectorBinding = useMemo<ProjectorBinding>(\n    () => ({ projector, revision: ctx, subscribe: observeClientGeometry }),\n    [projector, ctx],\n  );\n  if (!docId || !meta || !base) return null;\n  const t = transform;\n  const outerW = t.viewWidth + pageFrame.left + pageFrame.right;\n  const outerH = t.viewHeight + pageFrame.top + pageFrame.bottom;\n  const contentLeft = pageFrame.left + (t.viewWidth - t.contentWidth) / 2;\n  const contentTop = pageFrame.top + (t.viewHeight - t.contentHeight) / 2;\n  return (\n    <DocumentScope id={docId}>\n      <ProjectorProvider value={projectorBinding}>\n      <div style={{ position: 'relative', width: outerW, height: outerH, ...style }}>\n        <PageProvider value={ctx}>\n          {/* drop shadow ONLY — transparent, axis-aligned, can't leak behind the bitmap */}\n          <div\n            style={{\n              position: 'absolute',\n              left: pageFrame.left,\n              top: pageFrame.top,\n              width: t.viewWidth,\n              height: t.viewHeight,\n              boxShadow: '0 6px 18px rgba(0,0,0,.18)',\n            }}\n          />\n          {/* white backing + content as ONE box; rotation 0 carries no transform */}\n          <div\n            ref={ref}\n            style={{\n              position: 'absolute',\n              left: contentLeft,\n              top: contentTop,\n              width: t.contentWidth,\n              height: t.contentHeight,\n              background: '#fff',\n              transform: rotation ? `rotate(${rotation}deg)` : undefined,\n              userSelect: 'none',\n              WebkitUserSelect: 'none',\n            }}\n          >\n            {children}\n          </div>\n          {pageChrome}\n        </PageProvider>\n      </div>\n      </ProjectorProvider>\n    </DocumentScope>\n  );\n}\n"],"mappings":";;;;;;;;;AAyCA,SAAgB,SAAS,EACvB,MACA,YACA,QAAQ,KACR,YAAY,UACZ,UACA,YACA,SACgB;CAChB,MAAM,SAAS,UAAU;CACzB,MAAM,SAAS,oBAAoB;CACnC,MAAM,MAAM,OAAuB,IAAI;CACvC,MAAM,QAAQ,cAAc;CAC5B,MAAM,OAAO,QAAQ,OAAO,SAAS,CAAC,CAAC,KAAK,UAAU,SAAS,KAAA;CAC/D,MAAM,OAAO,MAAM,MAAM;CACzB,MAAM,MAAM,MAAM,oBAAoB,OAAO;CAC7C,MAAM,WAAW,MAAM,YAAY;CACnC,MAAM,MAAM,OAAO,WAAW,cAAc,OAAO,oBAAoB,IAAI;CAG3E,MAAM,YAAY,cAEd,cAAc;EACZ,UAAU,OACN;GAAE,OAAO,KAAK,KAAK;GAAO,QAAQ,KAAK,KAAK;EAAO,IACnD;GAAE,OAAO;GAAG,QAAQ;EAAE;EAC1B;EACA,OAAO,OAAO,QAAQ,KAAK,KAAK,QAAQ;EAIxC,WAAY,KAAK,MAAO,MAAM,YAAY;EAC1C;CACF,CAAC,GACH;EAAC,MAAM,KAAK;EAAO,MAAM,KAAK;EAAQ,MAAM;EAAU;EAAU;EAAO;CAAG,CAC5E;CACA,MAAM,MAAM,cAER,gBAAgB,SAAS,IAAI,KAAK,MAAM,WAAW,iBACjD,IAAI,QAAS,sBAAsB,CACrC,GACF;EAAC;EAAO;EAAK;EAAM;EAAW;CAAS,CACzC;CASA,MAAM,YAAY,eACT;EACL,OAAO;EACP,WAAW,GAAG,SAAU,MAAM,IAAI,OAAO,IAAI,UAAU,IAAI,aAAa,IAAI,IAAI;EAChF,gBAAgB,GAAG,OAAQ,MAAM,IAAI,OAAO,IAAI,UAAU,IAAI,cAAc,EAAE,IAAI;EAClF,UAAU,MACR,MAAM,IAAI,MACN;GACE,OAAO,IAAI,UAAU;GACrB,UAAU,IAAI,UAAU;GACxB,MAAM,IAAI,UAAU;EACtB,IACA;CACR,IACA,CAAC,GAAG,CACN;CACA,MAAM,mBAAmB,eAChB;EAAE;EAAW,UAAU;EAAK,WAAW;CAAsB,IACpE,CAAC,WAAW,GAAG,CACjB;CACA,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,OAAO;CACrC,MAAM,IAAI;CACV,MAAM,SAAS,EAAE,YAAY,UAAU,OAAO,UAAU;CACxD,MAAM,SAAS,EAAE,aAAa,UAAU,MAAM,UAAU;CACxD,MAAM,cAAc,UAAU,QAAQ,EAAE,YAAY,EAAE,gBAAgB;CACtE,MAAM,aAAa,UAAU,OAAO,EAAE,aAAa,EAAE,iBAAiB;CACtE,OACE,oBAAC,eAAD;EAAe,IAAI;EACjB,UAAA,oBAAC,mBAAD;GAAmB,OAAO;GAC1B,UAAA,oBAAC,OAAD;IAAK,OAAO;KAAE,UAAU;KAAY,OAAO;KAAQ,QAAQ;KAAQ,GAAG;IAAM;IAC1E,UAAA,qBAAC,cAAD;KAAc,OAAO;KAArB,UAAA;MAEE,oBAAC,OAAD,EACE,OAAO;OACL,UAAU;OACV,MAAM,UAAU;OAChB,KAAK,UAAU;OACf,OAAO,EAAE;OACT,QAAQ,EAAE;OACV,WAAW;MACb,EACD,CAAA;MAED,oBAAC,OAAD;OACO;OACL,OAAO;QACL,UAAU;QACV,MAAM;QACN,KAAK;QACL,OAAO,EAAE;QACT,QAAQ,EAAE;QACV,YAAY;QACZ,WAAW,WAAW,UAAU,SAAS,QAAQ,KAAA;QACjD,YAAY;QACZ,kBAAkB;OACpB;OAEC;MACE,CAAA;MACJ;KACW;;GACX,CAAA;EACc,CAAA;CACN,CAAA;AAEnB"}

package/dist/render.cjs

@@ -4,11 +4,14 @@ const require_runtime = require("./runtime.cjs");
 let react_jsx_runtime = require("react/jsx-runtime");
 let react = require("react");
 react = require_rolldown_runtime.__toESM(react, 1);
+let _embedpdf_web = require("@embedpdf/web");
 let _embedpdf_plugin_render = require("@embedpdf/plugin-render");
 //#region src/render.tsx
-function RenderLayer({ annotations = true } = {}) {
+let warnedTileSize = false;
+function RenderLayer({ annotations = true, tiles = true } = {}) {
 	const page = require_runtime.usePage();
 	const render = require_runtime.useCapability(_embedpdf_plugin_render.RenderToken);
+	const settings = render.paintSettings();
 	const ref = (0, react.useRef)(null);
 	const sourceKey = require_runtime.useSelector(_embedpdf_plugin_render.RenderToken, (c) => c.renderSourceKey(page.pon, {
 		scale: page.transform.renderScale,
@@ -41,7 +44,7 @@ function RenderLayer({ annotations = true } = {}) {
 		page.pon,
 		sourceKey
 	]);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
 		ref,
 		alt: "",
 		draggable: false,
@@ -52,19 +55,26 @@ function RenderLayer({ annotations = true } = {}) {
 			height: "100%",
 			pointerEvents: "none"
 		}
-	});
+	}), tiles && settings.tiles ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TilePlane, {
+		annotations,
+		fadeMs: settings.fadeMs
+	}) : null] });
 }
 /**
-* TileLayer — the sharp plane above the base rung.
+* The sharp plane above the base — the plugin's retention-safe paint plan
+* as keyed <img>s. Each tile reports painted after its first presentation
+* opportunity (and its inverse on unmount), so retained coarser generations
+* release only when their replacement is truly compositable.
 *
-* Mounting it is the per-lens OPT-IN; whether it spends anything is demand
-* arithmetic (a thumbnail rail's demand never engages). The paint list is the
-* plugin's retention-safe plan: keyed <img>s inside ONE container that carries
-* the page scale as a single transform (one rounding context — no tile seams),
-* with `onLoad` reporting the decode boundary back so retained coarser
-* generations release only when their replacement is truly on screen.
+* Tiles are placed in VIEW (CSS px) space directly — never in page points
+* under a scaled container. Blink quantizes layout lengths to 1/64 CSS px
+* BEFORE transforms apply, so a pt-space rect under a ×25 zoom transform
+* turns that harmless 1/64 into ±0.4px+ of per-tile misplacement — visible
+* seams and per-zoom-step letter shifts that grow with depth. In view
+* space the same quantization is a fixed ~1/64 CSS px at every zoom.
+* (v2 placed tiles in screen px for exactly this reason.)
 */
-function TileLayer({ annotations = true } = {}) {
+function TilePlane({ annotations, fadeMs }) {
 	const page = require_runtime.usePage();
 	const render = require_runtime.useCapability(_embedpdf_plugin_render.RenderToken);
 	const demand = page.getViewDemand?.() ?? { desiredDeviceWidth: page.transform.deviceWidth };
@@ -72,64 +82,70 @@ function TileLayer({ annotations = true } = {}) {
 	(0, react.useEffect)(() => () => render.releaseTiles(page.pon), [render, page.pon]);
 	if (plan.paint.length === 0) return null;
 	const t = page.transform;
-	const scale = t.viewScale;
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+	const s = t.viewScale;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		style: {
 			position: "absolute",
 			left: 0,
 			top: 0,
-			width: t.contentWidth / scale,
-			height: t.contentHeight / scale,
-			transform: `scale(${scale})`,
-			transformOrigin: "0 0",
-			pointerEvents: "none"
+			width: t.contentWidth,
+			height: t.contentHeight,
+			pointerEvents: "none",
+			isolation: "isolate"
 		},
-		children: plan.paint.map((source) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TileImg, {
+		children: [fadeMs > 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: `@keyframes epdf-tile-in { from { opacity: 0 } to { opacity: 1 } }` }) : null, plan.paint.map((source) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TileImg, {
 			source,
-			onPainted: () => render.tilePainted(page.pon, source.key)
-		}, source.key))
+			view: {
+				x: source.rect.x * s,
+				y: source.rect.y * s,
+				width: source.rect.width * s,
+				height: source.rect.height * s
+			},
+			fadeMs,
+			onPainted: () => render.tilePainted(page.pon, source.key),
+			onUnpainted: () => render.tileUnpainted(page.pon, source.key)
+		}, source.key))]
 	});
 }
-/** One tile: object-URL lifecycle + the painted (decode-boundary) report. */
-function TileImg({ source, onPainted }) {
+/** One tile: geometry plus the shared browser image binding. The binding
+*  hides the incomplete image, reports painted after its first presentation
+*  opportunity, and inverts that report when the element leaves the DOM. */
+function TileImg({ source, view, fadeMs, onPainted, onUnpainted }) {
 	const ref = (0, react.useRef)(null);
-	(0, react.useEffect)(() => {
-		const controller = new AbortController();
-		let revoke;
-		(async () => {
-			try {
-				const obj = await source.handle.objectUrl(controller.signal);
-				if (controller.signal.aborted) {
-					obj.revoke();
-					return;
-				}
-				revoke = obj.revoke;
-				if (ref.current) ref.current.src = obj.url;
-			} catch {}
-		})();
-		return () => {
-			controller.abort();
-			revoke?.();
-		};
+	(0, react.useLayoutEffect)(() => {
+		if (!ref.current) return;
+		return (0, _embedpdf_web.bindPaintedImage)(ref.current, source.handle, {
+			onPainted,
+			onUnpainted
+		});
 	}, [source.handle]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
 		ref,
 		alt: "",
 		draggable: false,
-		onLoad: onPainted,
+		onLoad: (e) => {
+			const w = e.currentTarget.naturalWidth;
+			if (w > 0 && !warnedTileSize) {
+				const expected = Math.round(source.rect.width * source.scale);
+				if (Math.abs(w - expected) > 1) {
+					warnedTileSize = true;
+					console.warn(`[render] tile bitmap ${w}px wide does not match its rect (expected ~${expected}px) — stale raster identity? key=${source.key}`);
+				}
+			}
+		},
 		style: {
 			position: "absolute",
-			left: source.rect.x,
-			top: source.rect.y,
-			width: source.rect.width,
-			height: source.rect.height,
-			zIndex: source.z
+			left: view.x,
+			top: view.y,
+			width: view.width,
+			height: view.height,
+			zIndex: source.z,
+			...fadeMs > 0 ? { animation: `epdf-tile-in ${fadeMs}ms ease-out` } : null
 		}
 	});
 }
 //#endregion
 exports.RenderLayer = RenderLayer;
-exports.TileLayer = TileLayer;
 Object.keys(_embedpdf_plugin_render).forEach(function(k) {
 	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/dist/render.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"render.cjs","names":["usePage","useCapability","RenderToken","useSelector"],"sources":["../src/render.tsx"],"sourcesContent":["/**\n * RenderLayer + TileLayer — the React views of @embedpdf/plugin-render.\n *\n * RenderLayer paints the BASE rung to an <img> from the engine's ENCODED\n * image() (identical for local & cloud). TileLayer paints the tile paint-plan\n * ABOVE it when the deployment lattice caps the base below the demand — mount\n * it per lens (the main stage yes, a thumbnail rail no); where the demand is\n * small it engages nothing. Both are dumb painters: every decision (policy\n * conformance, want sets, retention, release) is plugin-render's.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-render';\nimport * as React from 'react';\nimport { useEffect, useRef } from 'react';\nimport { RenderToken } from '@embedpdf/plugin-render';\nimport type { PageViewDemand, TilePaintSource } from '@embedpdf/plugin-render';\nimport { useCapability, usePage, useSelector } from './runtime';\n\nexport interface RenderLayerProps {\n  /**\n   * Bake annotations into the page bitmap (default true). Pass false when an\n   * <AnnotationLayer> owns annotation rendering, so they aren't drawn twice.\n   */\n  annotations?: boolean;\n}\n\nexport function RenderLayer({ annotations = true }: RenderLayerProps = {}) {\n  const page = usePage();\n  const render = useCapability(RenderToken);\n  const ref = useRef<HTMLImageElement>(null);\n  // ONE dependency: the raster's canonical identity — conformed viewport +\n  // annotations flag + epoch. Inside a lattice\n  // rung, zoom changes don't move it: no refetch, no DOM churn — the stage's\n  // CSS transform does the scaling. It changes exactly at rung crossings and\n  // on CONFIRMED mutations (epoch bumps at commit, never mid-gesture). Under\n  // `continuous` it embeds the exact scale — v2 behavior byte-for-byte. The\n  // policy behind it is a document fact the kernel materialized before\n  // publish, so the key is always computable.\n  const sourceKey = useSelector(RenderToken, (c) =>\n    c.renderSourceKey(page.pon, {\n      scale: page.transform.renderScale,\n      includeAnnotations: annotations,\n    }),\n  );\n  useEffect(() => {\n    const controller = new AbortController();\n    let revoke: (() => void) | undefined;\n    (async () => {\n      try {\n        // The capability conforms this to the policy (lattice → ladder width,\n        // continuous → this exact scale) and collapses same-key asks in its\n        // raster store. A stale-closure scale is harmless by construction:\n        // any scale in this rung produces this key's canonical request.\n        const image = await render.renderPage(page.pon, {\n          scale: page.transform.renderScale,\n          includeAnnotations: annotations,\n          signal: controller.signal,\n        });\n        const obj = await image.objectUrl(controller.signal);\n        if (controller.signal.aborted) {\n          obj.revoke();\n          return;\n        }\n        revoke = obj.revoke;\n        if (ref.current) ref.current.src = obj.url;\n      } catch {\n        /* aborted (camera moved / unmounted) or render failed */\n      }\n    })();\n    return () => {\n      controller.abort();\n      revoke?.();\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- sourceKey IS the\n    // render identity; scale/annotations/epoch are folded into it upstream.\n  }, [render, page.pon, sourceKey]);\n  return (\n    <img\n      ref={ref}\n      alt=\"\"\n      draggable={false}\n      style={{\n        position: 'absolute',\n        inset: 0,\n        width: '100%',\n        height: '100%',\n        pointerEvents: 'none',\n      }}\n    />\n  );\n}\n\nexport interface TileLayerProps {\n  /**\n   * Bake annotations into tile bitmaps (default true). Pass false when an\n   * <AnnotationLayer> owns annotation rendering — the composition that keeps\n   * tile artifacts annotation-version-free (CDN-stable across edits).\n   */\n  annotations?: boolean;\n}\n\n/**\n * TileLayer — the sharp plane above the base rung.\n *\n * Mounting it is the per-lens OPT-IN; whether it spends anything is demand\n * arithmetic (a thumbnail rail's demand never engages). The paint list is the\n * plugin's retention-safe plan: keyed <img>s inside ONE container that carries\n * the page scale as a single transform (one rounding context — no tile seams),\n * with `onLoad` reporting the decode boundary back so retained coarser\n * generations release only when their replacement is truly on screen.\n */\nexport function TileLayer({ annotations = true }: TileLayerProps = {}) {\n  const page = usePage();\n  const render = useCapability(RenderToken);\n  // Demand: the host's live camera view (Stage) or whole-page (PageView).\n  const demand: PageViewDemand = page.getViewDemand?.() ?? {\n    desiredDeviceWidth: page.transform.deviceWidth,\n  };\n  const plan = useSelector(RenderToken, (c) =>\n    c.tilePlan(page.pon, demand, { includeAnnotations: annotations }),\n  );\n  // Lens unmounted: stop in-flight tile fetches; resolved bytes stay cached.\n  useEffect(() => () => render.releaseTiles(page.pon), [render, page.pon]);\n  if (plan.paint.length === 0) return null;\n  const t = page.transform;\n  const scale = t.viewScale;\n  return (\n    <div\n      style={{\n        position: 'absolute',\n        left: 0,\n        top: 0,\n        width: t.contentWidth / scale,\n        height: t.contentHeight / scale,\n        transform: `scale(${scale})`,\n        transformOrigin: '0 0',\n        pointerEvents: 'none',\n      }}\n    >\n      {plan.paint.map((source) => (\n        <TileImg\n          key={source.key}\n          source={source}\n          onPainted={() => render.tilePainted(page.pon, source.key)}\n        />\n      ))}\n    </div>\n  );\n}\n\n/** One tile: object-URL lifecycle + the painted (decode-boundary) report. */\nfunction TileImg({ source, onPainted }: { source: TilePaintSource; onPainted: () => void }) {\n  const ref = useRef<HTMLImageElement>(null);\n  useEffect(() => {\n    const controller = new AbortController();\n    let revoke: (() => void) | undefined;\n    (async () => {\n      try {\n        const obj = await source.handle.objectUrl(controller.signal);\n        if (controller.signal.aborted) {\n          obj.revoke();\n          return;\n        }\n        revoke = obj.revoke;\n        if (ref.current) ref.current.src = obj.url;\n      } catch {\n        /* aborted (plan moved on) */\n      }\n    })();\n    return () => {\n      controller.abort();\n      revoke?.();\n    };\n  }, [source.handle]);\n  return (\n    <img\n      ref={ref}\n      alt=\"\"\n      draggable={false}\n      onLoad={onPainted}\n      style={{\n        position: 'absolute',\n        left: source.rect.x,\n        top: source.rect.y,\n        width: source.rect.width,\n        height: source.rect.height,\n        zIndex: source.z,\n      }}\n    />\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"render.cjs","names":["usePage","useCapability","RenderToken","useSelector"],"sources":["../src/render.tsx"],"sourcesContent":["/**\n * RenderLayer — the React view of @embedpdf/plugin-render. The page raster\n * is ONE concern with two planes:\n *\n *   - the BASE plane: a whole-page <img> at the plugin's resolved render\n *     points — the exact settled demand capped at the pixel budget on a\n *     continuous (local) engine, the advertised ladder on a lattice (cloud)\n *     deployment. Always present; the instant backdrop.\n *   - the TILE plane: the plugin's retention-safe paint plan above it,\n *     engaging by demand arithmetic when the view wants more pixels than\n *     the base may spend. A thumbnail-sized demand engages nothing — the\n *     arithmetic is the configuration.\n *\n * The layer is a DUMB painter, deliberately thin: plain <img>s bound through\n * the shared browser adapter, with painted/unpainted reports around their\n * visible lifetime. Every decision — strategy ∧ policy conformance, want\n * sets, level settling, retention, release — is plugin-render's; anything\n * mid-gesture simply CSS-scales until the plugin hands down new pixels.\n */\n\n// One-line-per-feature: registration travels with the UI.\nexport * from '@embedpdf/plugin-render';\nimport * as React from 'react';\nimport { useEffect, useLayoutEffect, useRef } from 'react';\nimport { RenderToken } from '@embedpdf/plugin-render';\nimport type { PageViewDemand, TilePaintSource } from '@embedpdf/plugin-render';\nimport { bindPaintedImage } from '@embedpdf/web';\nimport { useCapability, usePage, useSelector } from './runtime';\n\nexport interface RenderLayerProps {\n  /**\n   * Bake annotations into the page bitmap (default true). Pass false when an\n   * <AnnotationLayer> owns annotation rendering, so they aren't drawn twice.\n   */\n  annotations?: boolean;\n  /**\n   * Mount the tile plane (default true). Whether it SPENDS anything is\n   * demand arithmetic — leave it on; pass false only for a lens that must\n   * never tile even under deep zoom.\n   */\n  tiles?: boolean;\n}\n\nlet warnedTileSize = false;\n\nexport function RenderLayer({ annotations = true, tiles = true }: RenderLayerProps = {}) {\n  const page = usePage();\n  const render = useCapability(RenderToken);\n  const settings = render.paintSettings();\n  const ref = useRef<HTMLImageElement>(null);\n\n  // ONE dependency: the raster's canonical identity — conformed width +\n  // annotations flag + epoch. Under a lattice it moves only at rung\n  // crossings; under exact mode it tracks the demand and is CONSTANT above\n  // the budget — so the deep-zoom backdrop never refetches, and the sub-\n  // budget range refetches per settled demand exactly like v2 did.\n  const sourceKey = useSelector(RenderToken, (c) =>\n    c.renderSourceKey(page.pon, {\n      scale: page.transform.renderScale,\n      includeAnnotations: annotations,\n    }),\n  );\n\n  useEffect(() => {\n    const controller = new AbortController();\n    let revoke: (() => void) | undefined;\n    (async () => {\n      try {\n        // The capability conforms this to the resolved render points and\n        // collapses same-key asks in its raster store. A stale-closure scale\n        // is harmless by construction: any scale mapping to this key\n        // produces this key's canonical request.\n        const image = await render.renderPage(page.pon, {\n          scale: page.transform.renderScale,\n          includeAnnotations: annotations,\n          signal: controller.signal,\n        });\n        const obj = await image.objectUrl(controller.signal);\n        if (controller.signal.aborted) {\n          obj.revoke();\n          return;\n        }\n        revoke = obj.revoke;\n        // Imperative src on a STABLE element: the browser keeps the old\n        // bitmap until the new one decodes, and nothing ever re-requests the\n        // old URL — so revoke-on-cleanup is safe here by construction.\n        if (ref.current) ref.current.src = obj.url;\n      } catch {\n        /* aborted (camera moved / unmounted) or render failed */\n      }\n    })();\n    return () => {\n      controller.abort();\n      revoke?.();\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- sourceKey IS the\n    // render identity; scale/annotations/epoch are folded into it upstream.\n  }, [render, page.pon, sourceKey]);\n\n  return (\n    <>\n      <img\n        ref={ref}\n        alt=\"\"\n        draggable={false}\n        style={{\n          position: 'absolute',\n          inset: 0,\n          width: '100%',\n          height: '100%',\n          pointerEvents: 'none',\n        }}\n      />\n      {tiles && settings.tiles ? (\n        <TilePlane annotations={annotations} fadeMs={settings.fadeMs} />\n      ) : null}\n    </>\n  );\n}\n\n/**\n * The sharp plane above the base — the plugin's retention-safe paint plan\n * as keyed <img>s. Each tile reports painted after its first presentation\n * opportunity (and its inverse on unmount), so retained coarser generations\n * release only when their replacement is truly compositable.\n *\n * Tiles are placed in VIEW (CSS px) space directly — never in page points\n * under a scaled container. Blink quantizes layout lengths to 1/64 CSS px\n * BEFORE transforms apply, so a pt-space rect under a ×25 zoom transform\n * turns that harmless 1/64 into ±0.4px+ of per-tile misplacement — visible\n * seams and per-zoom-step letter shifts that grow with depth. In view\n * space the same quantization is a fixed ~1/64 CSS px at every zoom.\n * (v2 placed tiles in screen px for exactly this reason.)\n */\nfunction TilePlane({ annotations, fadeMs }: { annotations: boolean; fadeMs: number }) {\n  const page = usePage();\n  const render = useCapability(RenderToken);\n  // Demand: the host's live camera view (Stage) or whole-page (PageView).\n  // Level settling lives in the plugin (its settle gate), pan stays live.\n  const demand: PageViewDemand = page.getViewDemand?.() ?? {\n    desiredDeviceWidth: page.transform.deviceWidth,\n  };\n  const plan = useSelector(RenderToken, (c) =>\n    c.tilePlan(page.pon, demand, { includeAnnotations: annotations }),\n  );\n  // Lens unmounted: stop in-flight tile fetches; resolved bytes stay cached.\n  useEffect(() => () => render.releaseTiles(page.pon), [render, page.pon]);\n  if (plan.paint.length === 0) return null;\n  const t = page.transform;\n  const s = t.viewScale;\n  return (\n    <div\n      style={{\n        position: 'absolute',\n        left: 0,\n        top: 0,\n        width: t.contentWidth,\n        height: t.contentHeight,\n        pointerEvents: 'none',\n        // STACKING CONTRACT: tile <img>s carry zIndex ranks (coarse under\n        // fine) that exist only while generations are mixed — mid-zoom. This\n        // container MUST be a stacking context so those ranks stay internal;\n        // without it they join the Stage's context and paint above every\n        // z-auto sibling (annotations, page chrome, menus) exactly while\n        // zooming. The old scaled container created one implicitly via its\n        // transform; `isolation` is the explicit, no-side-effect way.\n        isolation: 'isolate',\n      }}\n    >\n      {fadeMs > 0 ? (\n        <style>{`@keyframes epdf-tile-in { from { opacity: 0 } to { opacity: 1 } }`}</style>\n      ) : null}\n      {plan.paint.map((source) => (\n        <TileImg\n          key={source.key}\n          source={source}\n          view={{\n            x: source.rect.x * s,\n            y: source.rect.y * s,\n            width: source.rect.width * s,\n            height: source.rect.height * s,\n          }}\n          fadeMs={fadeMs}\n          onPainted={() => render.tilePainted(page.pon, source.key)}\n          onUnpainted={() => render.tileUnpainted(page.pon, source.key)}\n        />\n      ))}\n    </div>\n  );\n}\n\n/** One tile: geometry plus the shared browser image binding. The binding\n *  hides the incomplete image, reports painted after its first presentation\n *  opportunity, and inverts that report when the element leaves the DOM. */\nfunction TileImg({\n  source,\n  view,\n  fadeMs,\n  onPainted,\n  onUnpainted,\n}: {\n  source: TilePaintSource;\n  /** Placement rect in VIEW (CSS px) space. */\n  view: { x: number; y: number; width: number; height: number };\n  fadeMs: number;\n  onPainted: () => void;\n  onUnpainted: () => void;\n}) {\n  const ref = useRef<HTMLImageElement>(null);\n  useLayoutEffect(() => {\n    if (!ref.current) return;\n    return bindPaintedImage(ref.current, source.handle, { onPainted, onUnpainted });\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- the handle is\n    // the bitmap's identity; the report callbacks carry stable values.\n  }, [source.handle]);\n  return (\n    <img\n      ref={ref}\n      alt=\"\"\n      draggable={false}\n      onLoad={(e) => {\n        // A raster whose intrinsic size disagrees with its rect would be\n        // silently stretched into place — the stale-handle bug class.\n        const w = e.currentTarget.naturalWidth;\n        if (w > 0 && !warnedTileSize) {\n          const expected = Math.round(source.rect.width * source.scale);\n          if (Math.abs(w - expected) > 1) {\n            warnedTileSize = true;\n            console.warn(\n              `[render] tile bitmap ${w}px wide does not match its rect ` +\n                `(expected ~${expected}px) — stale raster identity? key=${source.key}`,\n            );\n          }\n        }\n      }}\n      style={{\n        position: 'absolute',\n        left: view.x,\n        top: view.y,\n        width: view.width,\n        height: view.height,\n        zIndex: source.z,\n        ...(fadeMs > 0 ? { animation: `epdf-tile-in ${fadeMs}ms ease-out` } : null),\n      }}\n    />\n  );\n}\n"],"mappings":"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"}

package/dist/render.d.cts

@@ -6,27 +6,14 @@ interface RenderLayerProps {
    * <AnnotationLayer> owns annotation rendering, so they aren't drawn twice.
    */
   annotations?: boolean;
-}
-declare function RenderLayer({ annotations }?: RenderLayerProps): import("react/jsx-runtime").JSX.Element;
-interface TileLayerProps {
   /**
-   * Bake annotations into tile bitmaps (default true). Pass false when an
-   * <AnnotationLayer> owns annotation rendering — the composition that keeps
-   * tile artifacts annotation-version-free (CDN-stable across edits).
+   * Mount the tile plane (default true). Whether it SPENDS anything is
+   * demand arithmetic — leave it on; pass false only for a lens that must
+   * never tile even under deep zoom.
    */
-  annotations?: boolean;
+  tiles?: boolean;
 }
-/**
- * TileLayer — the sharp plane above the base rung.
- *
- * Mounting it is the per-lens OPT-IN; whether it spends anything is demand
- * arithmetic (a thumbnail rail's demand never engages). The paint list is the
- * plugin's retention-safe plan: keyed <img>s inside ONE container that carries
- * the page scale as a single transform (one rounding context — no tile seams),
- * with `onLoad` reporting the decode boundary back so retained coarser
- * generations release only when their replacement is truly on screen.
- */
-declare function TileLayer({ annotations }?: TileLayerProps): import("react/jsx-runtime").JSX.Element | null;
+declare function RenderLayer({ annotations, tiles }?: RenderLayerProps): import("react/jsx-runtime").JSX.Element;
 //#endregion
-export { RenderLayer, RenderLayerProps, TileLayer, TileLayerProps };
+export { RenderLayer, RenderLayerProps };
 //# sourceMappingURL=render.d.cts.map

package/dist/render.d.ts

@@ -6,27 +6,14 @@ interface RenderLayerProps {
    * <AnnotationLayer> owns annotation rendering, so they aren't drawn twice.
    */
   annotations?: boolean;
-}
-declare function RenderLayer({ annotations }?: RenderLayerProps): import("react/jsx-runtime").JSX.Element;
-interface TileLayerProps {
   /**
-   * Bake annotations into tile bitmaps (default true). Pass false when an
-   * <AnnotationLayer> owns annotation rendering — the composition that keeps
-   * tile artifacts annotation-version-free (CDN-stable across edits).
+   * Mount the tile plane (default true). Whether it SPENDS anything is
+   * demand arithmetic — leave it on; pass false only for a lens that must
+   * never tile even under deep zoom.
    */
-  annotations?: boolean;
+  tiles?: boolean;
 }
-/**
- * TileLayer — the sharp plane above the base rung.
- *
- * Mounting it is the per-lens OPT-IN; whether it spends anything is demand
- * arithmetic (a thumbnail rail's demand never engages). The paint list is the
- * plugin's retention-safe plan: keyed <img>s inside ONE container that carries
- * the page scale as a single transform (one rounding context — no tile seams),
- * with `onLoad` reporting the decode boundary back so retained coarser
- * generations release only when their replacement is truly on screen.
- */
-declare function TileLayer({ annotations }?: TileLayerProps): import("react/jsx-runtime").JSX.Element | null;
+declare function RenderLayer({ annotations, tiles }?: RenderLayerProps): import("react/jsx-runtime").JSX.Element;
 //#endregion
-export { RenderLayer, RenderLayerProps, TileLayer, TileLayerProps };
+export { RenderLayer, RenderLayerProps };
 //# sourceMappingURL=render.d.ts.map

package/dist/render.js

@@ -1,12 +1,15 @@
 import { useCapability, usePage, useSelector } from "./runtime.js";
-import { jsx } from "react/jsx-runtime";
-import { useEffect, useRef } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { bindPaintedImage } from "@embedpdf/web";
 import { RenderToken } from "@embedpdf/plugin-render";
 export * from "@embedpdf/plugin-render";
 //#region src/render.tsx
-function RenderLayer({ annotations = true } = {}) {
+let warnedTileSize = false;
+function RenderLayer({ annotations = true, tiles = true } = {}) {
 	const page = usePage();
 	const render = useCapability(RenderToken);
+	const settings = render.paintSettings();
 	const ref = useRef(null);
 	const sourceKey = useSelector(RenderToken, (c) => c.renderSourceKey(page.pon, {
 		scale: page.transform.renderScale,
@@ -39,7 +42,7 @@ function RenderLayer({ annotations = true } = {}) {
 		page.pon,
 		sourceKey
 	]);
-	return /* @__PURE__ */ jsx("img", {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("img", {
 		ref,
 		alt: "",
 		draggable: false,
@@ -50,19 +53,26 @@ function RenderLayer({ annotations = true } = {}) {
 			height: "100%",
 			pointerEvents: "none"
 		}
-	});
+	}), tiles && settings.tiles ? /* @__PURE__ */ jsx(TilePlane, {
+		annotations,
+		fadeMs: settings.fadeMs
+	}) : null] });
 }
 /**
-* TileLayer — the sharp plane above the base rung.
+* The sharp plane above the base — the plugin's retention-safe paint plan
+* as keyed <img>s. Each tile reports painted after its first presentation
+* opportunity (and its inverse on unmount), so retained coarser generations
+* release only when their replacement is truly compositable.
 *
-* Mounting it is the per-lens OPT-IN; whether it spends anything is demand
-* arithmetic (a thumbnail rail's demand never engages). The paint list is the
-* plugin's retention-safe plan: keyed <img>s inside ONE container that carries
-* the page scale as a single transform (one rounding context — no tile seams),
-* with `onLoad` reporting the decode boundary back so retained coarser
-* generations release only when their replacement is truly on screen.
+* Tiles are placed in VIEW (CSS px) space directly — never in page points
+* under a scaled container. Blink quantizes layout lengths to 1/64 CSS px
+* BEFORE transforms apply, so a pt-space rect under a ×25 zoom transform
+* turns that harmless 1/64 into ±0.4px+ of per-tile misplacement — visible
+* seams and per-zoom-step letter shifts that grow with depth. In view
+* space the same quantization is a fixed ~1/64 CSS px at every zoom.
+* (v2 placed tiles in screen px for exactly this reason.)
 */
-function TileLayer({ annotations = true } = {}) {
+function TilePlane({ annotations, fadeMs }) {
 	const page = usePage();
 	const render = useCapability(RenderToken);
 	const demand = page.getViewDemand?.() ?? { desiredDeviceWidth: page.transform.deviceWidth };
@@ -70,62 +80,69 @@ function TileLayer({ annotations = true } = {}) {
 	useEffect(() => () => render.releaseTiles(page.pon), [render, page.pon]);
 	if (plan.paint.length === 0) return null;
 	const t = page.transform;
-	const scale = t.viewScale;
-	return /* @__PURE__ */ jsx("div", {
+	const s = t.viewScale;
+	return /* @__PURE__ */ jsxs("div", {
 		style: {
 			position: "absolute",
 			left: 0,
 			top: 0,
-			width: t.contentWidth / scale,
-			height: t.contentHeight / scale,
-			transform: `scale(${scale})`,
-			transformOrigin: "0 0",
-			pointerEvents: "none"
+			width: t.contentWidth,
+			height: t.contentHeight,
+			pointerEvents: "none",
+			isolation: "isolate"
 		},
-		children: plan.paint.map((source) => /* @__PURE__ */ jsx(TileImg, {
+		children: [fadeMs > 0 ? /* @__PURE__ */ jsx("style", { children: `@keyframes epdf-tile-in { from { opacity: 0 } to { opacity: 1 } }` }) : null, plan.paint.map((source) => /* @__PURE__ */ jsx(TileImg, {
 			source,
-			onPainted: () => render.tilePainted(page.pon, source.key)
-		}, source.key))
+			view: {
+				x: source.rect.x * s,
+				y: source.rect.y * s,
+				width: source.rect.width * s,
+				height: source.rect.height * s
+			},
+			fadeMs,
+			onPainted: () => render.tilePainted(page.pon, source.key),
+			onUnpainted: () => render.tileUnpainted(page.pon, source.key)
+		}, source.key))]
 	});
 }
-/** One tile: object-URL lifecycle + the painted (decode-boundary) report. */
-function TileImg({ source, onPainted }) {
+/** One tile: geometry plus the shared browser image binding. The binding
+*  hides the incomplete image, reports painted after its first presentation
+*  opportunity, and inverts that report when the element leaves the DOM. */
+function TileImg({ source, view, fadeMs, onPainted, onUnpainted }) {
 	const ref = useRef(null);
-	useEffect(() => {
-		const controller = new AbortController();
-		let revoke;
-		(async () => {
-			try {
-				const obj = await source.handle.objectUrl(controller.signal);
-				if (controller.signal.aborted) {
-					obj.revoke();
-					return;
-				}
-				revoke = obj.revoke;
-				if (ref.current) ref.current.src = obj.url;
-			} catch {}
-		})();
-		return () => {
-			controller.abort();
-			revoke?.();
-		};
+	useLayoutEffect(() => {
+		if (!ref.current) return;
+		return bindPaintedImage(ref.current, source.handle, {
+			onPainted,
+			onUnpainted
+		});
 	}, [source.handle]);
 	return /* @__PURE__ */ jsx("img", {
 		ref,
 		alt: "",
 		draggable: false,
-		onLoad: onPainted,
+		onLoad: (e) => {
+			const w = e.currentTarget.naturalWidth;
+			if (w > 0 && !warnedTileSize) {
+				const expected = Math.round(source.rect.width * source.scale);
+				if (Math.abs(w - expected) > 1) {
+					warnedTileSize = true;
+					console.warn(`[render] tile bitmap ${w}px wide does not match its rect (expected ~${expected}px) — stale raster identity? key=${source.key}`);
+				}
+			}
+		},
 		style: {
 			position: "absolute",
-			left: source.rect.x,
-			top: source.rect.y,
-			width: source.rect.width,
-			height: source.rect.height,
-			zIndex: source.z
+			left: view.x,
+			top: view.y,
+			width: view.width,
+			height: view.height,
+			zIndex: source.z,
+			...fadeMs > 0 ? { animation: `epdf-tile-in ${fadeMs}ms ease-out` } : null
 		}
 	});
 }
 //#endregion
-export { RenderLayer, TileLayer };
+export { RenderLayer };
 
 //# sourceMappingURL=render.js.map