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

package/dist/index.cjs

@@ -60,6 +60,136 @@ function saveFile(bytes, name, mimeType) {
 	setTimeout(() => URL.revokeObjectURL(url), 1e3);
 }
 //#endregion
+//#region src/clipboard.ts
+const PREFETCH_DEBOUNCE_MS = 150;
+/**
+* Wire clipboard copy for a selection. Two delivery paths, both fed by the
+* prefetched text:
+*
+*   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page
+*     has a DOM selection or focused editable — e.g. the viewer shell's
+*     focus sink): answered SYNCHRONOUSLY from the cache;
+*   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually
+*     have none, and browsers don't dispatch `copy` then): a keydown
+*     fallback writes via the async Clipboard API inside the keystroke's
+*     user-activation window.
+*
+* Returns the unwire function. Mount once per document view (not per page).
+*/
+function wireSelectionClipboard(selection, options = {}) {
+	const target = options.target ?? document;
+	const prefetch = options.prefetch ?? true;
+	let cached = null;
+	let generation = 0;
+	let timer = null;
+	const refresh = () => {
+		cached = null;
+		if (!prefetch || !selection.hasSelection() || !selection.canCopy()) return;
+		const gen = ++generation;
+		selection.readText().then((text) => {
+			if (gen === generation) cached = text;
+		}, () => {});
+	};
+	const offCommit = selection.onCommit(() => {
+		if (timer) clearTimeout(timer);
+		timer = null;
+		refresh();
+	});
+	const offChange = selection.onChange(() => {
+		generation++;
+		cached = null;
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(refresh, PREFETCH_DEBOUNCE_MS);
+	});
+	const onCopy = (e) => {
+		if (cached == null || cached === "" || !selection.hasSelection()) return;
+		e.clipboardData?.setData("text/plain", cached);
+		e.preventDefault();
+	};
+	const onKeyDown = (e) => {
+		if (!(e.metaKey || e.ctrlKey) || e.key.toLowerCase() !== "c" || e.shiftKey || e.altKey) return;
+		if (!selection.hasSelection() || !selection.canCopy()) return;
+		const dom = target.getSelection?.();
+		if (dom && !dom.isCollapsed) return;
+		copySelection(selection);
+	};
+	target.addEventListener("copy", onCopy);
+	target.addEventListener("keydown", onKeyDown);
+	return () => {
+		offCommit();
+		offChange();
+		if (timer) clearTimeout(timer);
+		target.removeEventListener("copy", onCopy);
+		target.removeEventListener("keydown", onKeyDown);
+	};
+}
+/**
+* Toolbar/menu path: read the selected text and write it to the clipboard
+* via the async Clipboard API. Call from a user-gesture handler (browsers
+* require a secure context + user activation for clipboard writes). Resolves
+* with what was copied ('' when nothing was — nothing is written then, so an
+* empty selection never clobbers the user's clipboard).
+*/
+async function copySelection(selection) {
+	const text = await selection.readText();
+	if (text !== "") await navigator.clipboard.writeText(text);
+	return text;
+}
+//#endregion
+//#region src/anchored-position.ts
+/**
+* THE anchored projection: anchor → screen position, in one pure call —
+* projection, avoid-point transform, and the shared placement policy.
+* Frameworks recompute this inside their native reactive primitive
+* (a React render, a Vue `computed`, an Angular signal, a Svelte
+* `$derived`); nothing here schedules anything.
+*/
+function projectAnchoredTarget(projector, anchor, placement, gap) {
+	const box = projector.toScreen(anchor.pon, anchor.bounds);
+	if (!box) return null;
+	return positionAnchoredRect(box, placement, gap, anchor.avoid?.length ? projector.toScreenPoint(anchor.pon, anchor.avoid[0]) : null);
+}
+/**
+* The one genuinely BROWSER-driven invalidation: an element in normal
+* document flow moves when the document scrolls or the window resizes —
+* no state change announces it. `<PageView>`'s binding registers this;
+* the Stage never does (its camera is state, delivered through render).
+*/
+function observeClientGeometry(callback) {
+	window.addEventListener("scroll", callback, true);
+	window.addEventListener("resize", callback);
+	return () => {
+		window.removeEventListener("scroll", callback, true);
+		window.removeEventListener("resize", callback);
+	};
+}
+function positionAnchoredRect(box, placement, gap, avoid) {
+	const cx = box.x + box.width / 2;
+	const cy = box.y + box.height / 2;
+	switch (placement) {
+		case "bottom": return {
+			left: cx,
+			top: Math.max(box.y + box.height, avoid ? avoid.y : -Infinity) + gap,
+			transform: "translate(-50%, 0)"
+		};
+		case "left": return {
+			left: Math.min(box.x, avoid ? avoid.x : Infinity) - gap,
+			top: cy,
+			transform: "translate(-100%, -50%)"
+		};
+		case "right": return {
+			left: Math.max(box.x + box.width, avoid ? avoid.x : -Infinity) + gap,
+			top: cy,
+			transform: "translate(0, -50%)"
+		};
+		default: return {
+			left: cx,
+			top: Math.min(box.y, avoid ? avoid.y : Infinity) - gap,
+			transform: "translate(-50%, -100%)"
+		};
+	}
+}
+//#endregion
 //#region src/cursor.ts
 /** Build the CSS cursor value: `url("data:image/svg+xml,…") x y, fallback`. */
 function svgCursor({ svg, hotspot, fallback = "crosshair" }) {
@@ -105,10 +235,62 @@ function sanitizeExternalUri(uri, allowedSchemes = DEFAULT_ALLOWED_SCHEMES) {
 	}
 }
 //#endregion
+//#region src/painted-image.ts
+/**
+* Bind a raster source to an <img> without ever painting its incomplete-image
+* placeholder. The source becomes visible on load; retained coverage is
+* released only after the browser has had one full frame to present it.
+*
+* Call this from the framework's pre-paint mount hook and invoke the returned
+* cleanup on unmount. Keeping this DOM lifecycle here lets every framework
+* adapter remain a ref plus one bind/unbind hook.
+*/
+function bindPaintedImage(image, source, callbacks) {
+	const controller = new AbortController();
+	let revoke;
+	let frame = 0;
+	let painted = false;
+	image.style.visibility = "hidden";
+	const onLoad = () => {
+		image.style.visibility = "visible";
+		frame = requestAnimationFrame(() => {
+			frame = requestAnimationFrame(() => {
+				frame = 0;
+				painted = true;
+				callbacks.onPainted();
+			});
+		});
+	};
+	image.addEventListener("load", onLoad, { once: true });
+	source.objectUrl(controller.signal).then((objectUrl) => {
+		if (controller.signal.aborted) {
+			objectUrl.revoke();
+			return;
+		}
+		revoke = objectUrl.revoke;
+		image.src = objectUrl.url;
+	}, () => {});
+	return () => {
+		controller.abort();
+		if (frame) cancelAnimationFrame(frame);
+		image.removeEventListener("load", onLoad);
+		image.style.visibility = "hidden";
+		image.removeAttribute("src");
+		revoke?.();
+		if (painted) callbacks.onUnpainted();
+	};
+}
+//#endregion
+exports.bindPaintedImage = bindPaintedImage;
+exports.copySelection = copySelection;
+exports.observeClientGeometry = observeClientGeometry;
 exports.pickFile = pickFile;
 exports.pickImageFile = pickImageFile;
+exports.positionAnchoredRect = positionAnchoredRect;
+exports.projectAnchoredTarget = projectAnchoredTarget;
 exports.sanitizeExternalUri = sanitizeExternalUri;
 exports.saveFile = saveFile;
 exports.svgCursor = svgCursor;
+exports.wireSelectionClipboard = wireSelectionClipboard;
 
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/file-picker.ts","../src/cursor.ts","../src/external-uri.ts"],"sourcesContent":["/**\n * A one-shot file dialog. Opens a throwaway `<input type=file>`, resolves the\n * chosen `File`, or `null` when the dialog is dismissed. MUST be called\n * synchronously from a user gesture (a click) or the browser refuses to open it.\n *\n * A `File` is a `Blob`, which is a `BinarySource` everywhere in the stack, so the\n * caller can hand the result straight to the engine — this module stays a pure\n * DOM utility with no EmbedPDF types.\n */\nconst IMAGE_ACCEPT = 'image/png,image/jpeg,application/pdf';\n\nexport interface PickFileOptions {\n  /** The dialog's `accept` filter. Defaults to PNG / JPEG / PDF. */\n  accept?: string;\n  /** Allow multiple selection (returns the first file). Defaults to false. */\n  multiple?: boolean;\n}\n\n/** Open the file dialog; resolve the picked file, or null if cancelled. */\nexport function pickImageFile(options: PickFileOptions = {}): Promise<File | null> {\n  const { accept = IMAGE_ACCEPT, multiple = false } = options;\n  return new Promise((resolve) => {\n    const input = document.createElement('input');\n    input.type = 'file';\n    input.accept = accept;\n    input.multiple = multiple;\n    input.style.display = 'none';\n\n    let settled = false;\n    const finish = (value: File | null): void => {\n      if (settled) return;\n      settled = true;\n      window.removeEventListener('focus', onFocus);\n      input.remove();\n      resolve(value);\n    };\n\n    // A window refocus means the dialog closed. Give a queued `change` a tick to\n    // win, then treat a bare refocus as a cancel — the fallback for browsers that\n    // predate the `cancel` event.\n    const onFocus = (): void => {\n      setTimeout(() => finish(null), 300);\n    };\n\n    input.addEventListener('change', () => finish(input.files?.[0] ?? null), { once: true });\n    input.addEventListener('cancel', () => finish(null), { once: true });\n    window.addEventListener('focus', onFocus, { once: true });\n\n    document.body.appendChild(input);\n    input.click();\n  });\n}\n\n/** The same dialog with NO type filter — any file (attachments). */\nexport const pickFile = (options: PickFileOptions = {}): Promise<File | null> =>\n  pickImageFile({ accept: '*/*', ...options });\n\n/**\n * Hand bytes to the user as a browser download (a one-shot `<a download>`).\n * The DOM half of \"download this attachment\" — pair with the annotation\n * capability's `downloadAttachment` or the document `attachments.download`.\n */\nexport function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void {\n  const blob =\n    bytes instanceof Blob\n      ? bytes\n      : new Blob([bytes as BlobPart], { type: mimeType ?? 'application/octet-stream' });\n  const url = URL.createObjectURL(blob);\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = name;\n  a.style.display = 'none';\n  document.body.appendChild(a);\n  a.click();\n  a.remove();\n  setTimeout(() => URL.revokeObjectURL(url), 1000);\n}\n","/**\n * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the\n * only zero-latency pointer-locked pixel the web has — the OS composites it),\n * so an app hands its toolbar icon here and assigns the result via the\n * interaction hub's `setToolCursor`.\n *\n * Browser rules baked into this module:\n *   - The SVG must carry explicit `width`/`height` attributes (not just a\n *     viewBox) or Chromium/WebKit ignore it — enforced here.\n *   - The hard ceiling is 128×128 CSS px (bigger falls back to the keyword).\n *     Above 32×32, Chromium temporarily resets the cursor to default while it\n *     would overlap browser UI (anti-spoofing) — fine mid-viewport, so ~40px\n *     compositions are common; stay ≤128.\n *   - The keyword fallback covers browsers that refuse SVG cursor images.\n *\n * Pure string work with no EmbedPDF types — like the file picker, this module\n * is a plain web utility.\n */\n\nexport interface SvgCursorOptions {\n  /** Complete `<svg>` markup, colors baked in (no `currentColor` — a cursor\n   *  image has no cascade to inherit from). */\n  svg: string;\n  /** The click point inside the image, CSS px from the top-left. Default 0,0\n   *  (arrow-style: the image's corner is the tip). */\n  hotspot?: { x: number; y: number };\n  /** Keyword cursor when the image can't render. Default `'crosshair'`. */\n  fallback?: string;\n}\n\n/** Build the CSS cursor value: `url(\"data:image/svg+xml,…\") x y, fallback`. */\nexport function svgCursor({ svg, hotspot, fallback = 'crosshair' }: SvgCursorOptions): string {\n  // Scan only the opening `<svg …>` tag (bounded slice) rather than running\n  // `/<svg[^>]*\\swidth\\s*=/` over the whole string — the unbounded form is\n  // quadratic on pathological inputs (many `<svg` fragments with no `>`),\n  // while accepting exactly the same markup: `[^>]*` could never cross a\n  // `>` either.\n  const tagStart = svg.indexOf('<svg');\n  const tagEnd = tagStart >= 0 ? svg.indexOf('>', tagStart) : -1;\n  const openTag = tagEnd >= 0 ? svg.slice(tagStart, tagEnd + 1) : '';\n  if (!/\\swidth\\s*=/.test(openTag) || !/\\sheight\\s*=/.test(openTag)) {\n    throw new Error(\n      '[web] svgCursor: the <svg> needs explicit width/height attributes — ' +\n        'browsers ignore cursor images without an intrinsic size',\n    );\n  }\n  const uri = `data:image/svg+xml,${encodeURIComponent(svg)}`;\n  const spot = hotspot ? ` ${Math.round(hotspot.x)} ${Math.round(hotspot.y)}` : '';\n  return `url(\"${uri}\")${spot}, ${fallback}`;\n}\n","/**\n * External-URI hygiene for PDF link annotations — written ONCE here so every\n * framework adapter (react, vue, svelte, angular) shares the same policy.\n *\n * PDFs are untrusted input: a link's `/URI` can carry anything, including\n * `javascript:` payloads. The default allowlist covers what a document link\n * legitimately opens; everything else (javascript:, file:, data:, vbscript:,\n * custom app schemes) resolves to `null` and the adapters render the link\n * WITHOUT an href — activation still reports through the plugin, so an\n * embedder that needs a custom scheme can handle it in `onActivate`.\n */\nconst DEFAULT_ALLOWED_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * Validate a link URI for opening in the browser. Returns the URI when its\n * scheme is allowed (scheme-relative and bare URIs resolve as https), else\n * `null`. Never throws — a malformed URI is just an unopenable one.\n */\nexport function sanitizeExternalUri(\n  uri: string,\n  allowedSchemes: Iterable<string> = DEFAULT_ALLOWED_SCHEMES,\n): string | null {\n  const trimmed = uri.trim();\n  if (!trimmed) return null;\n  const allowed = new Set(\n    [...allowedSchemes].map((s) => (s.endsWith(':') ? s.toLowerCase() : `${s.toLowerCase()}:`)),\n  );\n  try {\n    // Base resolves scheme-relative (\"//host\") and bare (\"example.com/x\" is a\n    // relative path → https) forms; an absolute scheme wins over the base.\n    const url = new URL(trimmed, 'https://invalid.example/');\n    return allowed.has(url.protocol) ? trimmed : null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;;AASA,MAAM,eAAe;;AAUrB,SAAgB,cAAc,UAA2B,CAAC,GAAyB;CACjF,MAAM,EAAE,SAAS,cAAc,WAAW,UAAU;CACpD,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,QAAQ,SAAS,cAAc,OAAO;EAC5C,MAAM,OAAO;EACb,MAAM,SAAS;EACf,MAAM,WAAW;EACjB,MAAM,MAAM,UAAU;EAEtB,IAAI,UAAU;EACd,MAAM,UAAU,UAA6B;GAC3C,IAAI,SAAS;GACb,UAAU;GACV,OAAO,oBAAoB,SAAS,OAAO;GAC3C,MAAM,OAAO;GACb,QAAQ,KAAK;EACf;EAKA,MAAM,gBAAsB;GAC1B,iBAAiB,OAAO,IAAI,GAAG,GAAG;EACpC;EAEA,MAAM,iBAAiB,gBAAgB,OAAO,MAAM,QAAQ,MAAM,IAAI,GAAG,EAAE,MAAM,KAAK,CAAC;EACvF,MAAM,iBAAiB,gBAAgB,OAAO,IAAI,GAAG,EAAE,MAAM,KAAK,CAAC;EACnE,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAExD,SAAS,KAAK,YAAY,KAAK;EAC/B,MAAM,MAAM;CACd,CAAC;AACH;;AAGA,MAAa,YAAY,UAA2B,CAAC,MACnD,cAAc;CAAE,QAAQ;CAAO,GAAG;AAAQ,CAAC;;;;;;AAO7C,SAAgB,SAAS,OAA0B,MAAc,UAAyB;CACxF,MAAM,OACJ,iBAAiB,OACb,QACA,IAAI,KAAK,CAAC,KAAiB,GAAG,EAAE,MAAM,YAAY,2BAA2B,CAAC;CACpF,MAAM,MAAM,IAAI,gBAAgB,IAAI;CACpC,MAAM,IAAI,SAAS,cAAc,GAAG;CACpC,EAAE,OAAO;CACT,EAAE,WAAW;CACb,EAAE,MAAM,UAAU;CAClB,SAAS,KAAK,YAAY,CAAC;CAC3B,EAAE,MAAM;CACR,EAAE,OAAO;CACT,iBAAiB,IAAI,gBAAgB,GAAG,GAAG,GAAI;AACjD;;;;AC7CA,SAAgB,UAAU,EAAE,KAAK,SAAS,WAAW,eAAyC;CAM5F,MAAM,WAAW,IAAI,QAAQ,MAAM;CACnC,MAAM,SAAS,YAAY,IAAI,IAAI,QAAQ,KAAK,QAAQ,IAAI;CAC5D,MAAM,UAAU,UAAU,IAAI,IAAI,MAAM,UAAU,SAAS,CAAC,IAAI;CAChE,IAAI,CAAC,cAAc,KAAK,OAAO,KAAK,CAAC,eAAe,KAAK,OAAO,GAC9D,MAAM,IAAI,MACR,6HAEF;CAIF,OAAO,QAAQ,sBAFmB,mBAAmB,GAAG,IAErC,IADN,UAAU,IAAI,KAAK,MAAM,QAAQ,CAAC,EAAE,GAAG,KAAK,MAAM,QAAQ,CAAC,MAAM,GAClD,IAAI;AAClC;;;;;;;;;;;;;;ACtCA,MAAM,0CAA0B,IAAI,IAAI;CAAC;CAAS;CAAU;CAAW;AAAM,CAAC;;;;;;AAO9E,SAAgB,oBACd,KACA,iBAAmC,yBACpB;CACf,MAAM,UAAU,IAAI,KAAK;CACzB,IAAI,CAAC,SAAS,OAAO;CACrB,MAAM,UAAU,IAAI,IAClB,CAAC,GAAG,cAAc,CAAC,CAAC,KAAK,MAAO,EAAE,SAAS,GAAG,IAAI,EAAE,YAAY,IAAI,GAAG,EAAE,YAAY,EAAE,EAAG,CAC5F;CACA,IAAI;EAGF,MAAM,MAAM,IAAI,IAAI,SAAS,0BAA0B;EACvD,OAAO,QAAQ,IAAI,IAAI,QAAQ,IAAI,UAAU;CAC/C,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/file-picker.ts","../src/clipboard.ts","../src/anchored-position.ts","../src/cursor.ts","../src/external-uri.ts","../src/painted-image.ts"],"sourcesContent":["/**\n * A one-shot file dialog. Opens a throwaway `<input type=file>`, resolves the\n * chosen `File`, or `null` when the dialog is dismissed. MUST be called\n * synchronously from a user gesture (a click) or the browser refuses to open it.\n *\n * A `File` is a `Blob`, which is a `BinarySource` everywhere in the stack, so the\n * caller can hand the result straight to the engine — this module stays a pure\n * DOM utility with no EmbedPDF types.\n */\nconst IMAGE_ACCEPT = 'image/png,image/jpeg,application/pdf';\n\nexport interface PickFileOptions {\n  /** The dialog's `accept` filter. Defaults to PNG / JPEG / PDF. */\n  accept?: string;\n  /** Allow multiple selection (returns the first file). Defaults to false. */\n  multiple?: boolean;\n}\n\n/** Open the file dialog; resolve the picked file, or null if cancelled. */\nexport function pickImageFile(options: PickFileOptions = {}): Promise<File | null> {\n  const { accept = IMAGE_ACCEPT, multiple = false } = options;\n  return new Promise((resolve) => {\n    const input = document.createElement('input');\n    input.type = 'file';\n    input.accept = accept;\n    input.multiple = multiple;\n    input.style.display = 'none';\n\n    let settled = false;\n    const finish = (value: File | null): void => {\n      if (settled) return;\n      settled = true;\n      window.removeEventListener('focus', onFocus);\n      input.remove();\n      resolve(value);\n    };\n\n    // A window refocus means the dialog closed. Give a queued `change` a tick to\n    // win, then treat a bare refocus as a cancel — the fallback for browsers that\n    // predate the `cancel` event.\n    const onFocus = (): void => {\n      setTimeout(() => finish(null), 300);\n    };\n\n    input.addEventListener('change', () => finish(input.files?.[0] ?? null), { once: true });\n    input.addEventListener('cancel', () => finish(null), { once: true });\n    window.addEventListener('focus', onFocus, { once: true });\n\n    document.body.appendChild(input);\n    input.click();\n  });\n}\n\n/** The same dialog with NO type filter — any file (attachments). */\nexport const pickFile = (options: PickFileOptions = {}): Promise<File | null> =>\n  pickImageFile({ accept: '*/*', ...options });\n\n/**\n * Hand bytes to the user as a browser download (a one-shot `<a download>`).\n * The DOM half of \"download this attachment\" — pair with the annotation\n * capability's `downloadAttachment` or the document `attachments.download`.\n */\nexport function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void {\n  const blob =\n    bytes instanceof Blob\n      ? bytes\n      : new Blob([bytes as BlobPart], { type: mimeType ?? 'application/octet-stream' });\n  const url = URL.createObjectURL(blob);\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = name;\n  a.style.display = 'none';\n  document.body.appendChild(a);\n  a.click();\n  a.remove();\n  setTimeout(() => URL.revokeObjectURL(url), 1000);\n}\n","/**\n * Clipboard wiring for text selection — the environmental half of copy.\n *\n * The selection plugin is deliberately DOM-free: its public capability ends\n * at `readText()` (data). Everything that touches `navigator.clipboard` or\n * the native `copy` event lives HERE, structurally typed so this module\n * stays a pure DOM utility with no EmbedPDF dependencies (the selection\n * capability satisfies {@link ClipboardSelectionSource} as-is).\n */\n\n/** The slice of the selection capability clipboard wiring needs. */\nexport interface ClipboardSelectionSource {\n  hasSelection(): boolean;\n  canCopy(): boolean;\n  readText(): Promise<string>;\n  onChange(cb: () => void): () => void;\n  onCommit(cb: () => void): () => void;\n}\n\nexport interface SelectionClipboardOptions {\n  /**\n   * Prefetch the selected text when the selection settles (default true).\n   * This is what makes the NATIVE copy path work: a `copy` event handler\n   * must call `clipboardData.setData` synchronously — awaiting a page-text\n   * read inside it is too late — and it also keeps the async path instant.\n   * The fetch is one versioned, cached, permission-gated read per page;\n   * pass false to make copying strictly on-demand.\n   */\n  prefetch?: boolean;\n  /** Event target to listen on. Defaults to `document`. */\n  target?: Document;\n}\n\nconst PREFETCH_DEBOUNCE_MS = 150;\n\n/**\n * Wire clipboard copy for a selection. Two delivery paths, both fed by the\n * prefetched text:\n *\n *   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page\n *     has a DOM selection or focused editable — e.g. the viewer shell's\n *     focus sink): answered SYNCHRONOUSLY from the cache;\n *   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually\n *     have none, and browsers don't dispatch `copy` then): a keydown\n *     fallback writes via the async Clipboard API inside the keystroke's\n *     user-activation window.\n *\n * Returns the unwire function. Mount once per document view (not per page).\n */\nexport function wireSelectionClipboard(\n  selection: ClipboardSelectionSource,\n  options: SelectionClipboardOptions = {},\n): () => void {\n  const target = options.target ?? document;\n  const prefetch = options.prefetch ?? true;\n  let cached: string | null = null;\n  let generation = 0;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  const refresh = (): void => {\n    cached = null;\n    if (!prefetch || !selection.hasSelection() || !selection.canCopy()) return;\n    const gen = ++generation;\n    selection.readText().then(\n      (text) => {\n        if (gen === generation) cached = text;\n      },\n      () => {}, // denied / failed — the async path will surface it if used\n    );\n  };\n\n  // Commit (gesture end) refreshes immediately; change (drag, programmatic\n  // select) debounces so a drag doesn't fetch per pointer move.\n  const offCommit = selection.onCommit(() => {\n    if (timer) clearTimeout(timer);\n    timer = null;\n    refresh();\n  });\n  const offChange = selection.onChange(() => {\n    generation++;\n    cached = null;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(refresh, PREFETCH_DEBOUNCE_MS);\n  });\n\n  const onCopy = (e: ClipboardEvent): void => {\n    if (cached == null || cached === '' || !selection.hasSelection()) return;\n    e.clipboardData?.setData('text/plain', cached);\n    e.preventDefault();\n  };\n\n  const onKeyDown = (e: KeyboardEvent): void => {\n    if (!(e.metaKey || e.ctrlKey) || e.key.toLowerCase() !== 'c' || e.shiftKey || e.altKey) {\n      return;\n    }\n    if (!selection.hasSelection() || !selection.canCopy()) return;\n    // A live DOM selection means the browser will dispatch `copy` itself and\n    // our synchronous handler answers — don't double-write.\n    const dom = target.getSelection?.();\n    if (dom && !dom.isCollapsed) return;\n    void copySelection(selection); // instant when prefetched; still inside user activation\n  };\n\n  target.addEventListener('copy', onCopy);\n  target.addEventListener('keydown', onKeyDown);\n  return () => {\n    offCommit();\n    offChange();\n    if (timer) clearTimeout(timer);\n    target.removeEventListener('copy', onCopy);\n    target.removeEventListener('keydown', onKeyDown);\n  };\n}\n\n/**\n * Toolbar/menu path: read the selected text and write it to the clipboard\n * via the async Clipboard API. Call from a user-gesture handler (browsers\n * require a secure context + user activation for clipboard writes). Resolves\n * with what was copied ('' when nothing was — nothing is written then, so an\n * empty selection never clobbers the user's clipboard).\n */\nexport async function copySelection(selection: ClipboardSelectionSource): Promise<string> {\n  const text = await selection.readText();\n  if (text !== '') await navigator.clipboard.writeText(text);\n  return text;\n}\n","/**\n * Anchored-overlay geometry for UI floating over page content (selection\n * menus, draft menus, popovers): the projector SNAPSHOT contract, the\n * anchor shape, and the placement math. Pure values and pure functions over\n * structural rect/point shapes — no EmbedPDF types, no framework, no\n * reactive lifecycle — so every framework adapter (React, Vue, Svelte,\n * Angular) shares ONE implementation and binds it with its NATIVE\n * reactivity (context revision, signals, computed, $derived).\n *\n * The boundary laws:\n *   - Placement policy lives HERE, above the projector seam: a projector\n *     only knows geometry — never what is being positioned nor where it\n *     prefers to sit.\n *   - A projector describes the CURRENT projection; it never implements a\n *     framework-style reactive lifecycle. State-driven changes (the Stage\n *     camera) must reach consumers through the framework's own render\n *     cycle so surface and overlay commit TOGETHER; only genuinely\n *     browser-driven changes (a PageView moving because the document\n *     scrolled) use an external listener ({@link observeClientGeometry}).\n */\n\nexport interface AnchoredRect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface AnchoredPoint {\n  x: number;\n  y: number;\n}\n\nexport type AnchoredPlacement = 'top' | 'right' | 'bottom' | 'left';\n\n/** CSS-ready output: absolute/fixed `left`/`top` plus a centering transform. */\nexport interface AnchoredPosition {\n  left: number;\n  top: number;\n  transform: string;\n}\n\n/**\n * Place an upright element around `box` (screen px). `avoid` is a screen\n * point the element must clear (e.g. the rotate knob): the element extends\n * ONLY the edge it sits on, and ONLY when the point protrudes past that\n * edge — so it clears the obstacle without ever shifting off-centre on the\n * other axis. When the point is on another side (e.g. a 90° shape, knob at\n * mid-height for a `top` placement) the edge is untouched and the element\n * stays centred on `box`.\n */\n/** What anchored UI attaches to: a content-space rect on a page, plus\n *  optional content-space points the UI must clear (e.g. a rotate knob).\n *  Structural — plugin anchor reads satisfy it without importing this\n *  package. */\nexport interface AnchorTarget {\n  pon: number;\n  bounds: AnchoredRect;\n  avoid?: AnchoredPoint[];\n}\n\n/**\n * A page surface's PROJECTION SNAPSHOT: how a content-space rect on a page\n * becomes screen coordinates, right now. Provided by `<Stage>`\n * (camera-driven, pure state, no DOM reads) and `<PageView>` (DOM-measured).\n * Deliberately NO subscribe here — when projection changes is a framework\n * binding concern (see the module doc), not part of the snapshot.\n */\nexport interface ViewProjector {\n  /**\n   * Which coordinate space `toScreen` speaks, and therefore how anchored\n   * content mounts:\n   *   - 'overlay': coords are relative to the surface's own positioned\n   *     container → rendered in place, position:absolute. (Stage)\n   *   - 'client': coords are viewport px → portalled to the document body,\n   *     position:fixed, so no ancestor overflow can clip. (PageView)\n   */\n  space: 'overlay' | 'client';\n  /** Content-space rect on a page → coords in `space`. Null: not projectable\n   *  right now (page not shown / not measurable yet). */\n  toScreen(pon: number, rect: AnchoredRect): AnchoredRect | null;\n  toScreenPoint(pon: number, at: AnchoredPoint): AnchoredPoint | null;\n  /** The page's live view facts (for anchor reads that need them — e.g. the\n   *  screen-constant rotate-knob stalk), or null when the page isn't shown. */\n  viewEnv(pon: number): {\n    scale: number;\n    rotation: 0 | 90 | 180 | 270;\n    zoom: number;\n  } | null;\n}\n\n/**\n * THE anchored projection: anchor → screen position, in one pure call —\n * projection, avoid-point transform, and the shared placement policy.\n * Frameworks recompute this inside their native reactive primitive\n * (a React render, a Vue `computed`, an Angular signal, a Svelte\n * `$derived`); nothing here schedules anything.\n */\nexport function projectAnchoredTarget(\n  projector: ViewProjector,\n  anchor: AnchorTarget,\n  placement: AnchoredPlacement,\n  gap: number,\n): AnchoredPosition | null {\n  const box = projector.toScreen(anchor.pon, anchor.bounds);\n  if (!box) return null;\n  const avoid = anchor.avoid?.length\n    ? projector.toScreenPoint(anchor.pon, anchor.avoid[0])\n    : null;\n  return positionAnchoredRect(box, placement, gap, avoid);\n}\n\n/**\n * The one genuinely BROWSER-driven invalidation: an element in normal\n * document flow moves when the document scrolls or the window resizes —\n * no state change announces it. `<PageView>`'s binding registers this;\n * the Stage never does (its camera is state, delivered through render).\n */\nexport function observeClientGeometry(callback: () => void): () => void {\n  window.addEventListener('scroll', callback, true);\n  window.addEventListener('resize', callback);\n  return () => {\n    window.removeEventListener('scroll', callback, true);\n    window.removeEventListener('resize', callback);\n  };\n}\n\nexport function positionAnchoredRect(\n  box: AnchoredRect,\n  placement: AnchoredPlacement,\n  gap: number,\n  avoid?: AnchoredPoint | null,\n): AnchoredPosition {\n  const cx = box.x + box.width / 2;\n  const cy = box.y + box.height / 2;\n\n  switch (placement) {\n    case 'bottom': {\n      const edge = Math.max(box.y + box.height, avoid ? avoid.y : -Infinity);\n      return { left: cx, top: edge + gap, transform: 'translate(-50%, 0)' };\n    }\n    case 'left': {\n      const edge = Math.min(box.x, avoid ? avoid.x : Infinity);\n      return { left: edge - gap, top: cy, transform: 'translate(-100%, -50%)' };\n    }\n    case 'right': {\n      const edge = Math.max(box.x + box.width, avoid ? avoid.x : -Infinity);\n      return { left: edge + gap, top: cy, transform: 'translate(0, -50%)' };\n    }\n    case 'top':\n    default: {\n      const edge = Math.min(box.y, avoid ? avoid.y : Infinity);\n      return { left: cx, top: edge - gap, transform: 'translate(-50%, -100%)' };\n    }\n  }\n}\n","/**\n * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the\n * only zero-latency pointer-locked pixel the web has — the OS composites it),\n * so an app hands its toolbar icon here and assigns the result via the\n * interaction hub's `setToolCursor`.\n *\n * Browser rules baked into this module:\n *   - The SVG must carry explicit `width`/`height` attributes (not just a\n *     viewBox) or Chromium/WebKit ignore it — enforced here.\n *   - The hard ceiling is 128×128 CSS px (bigger falls back to the keyword).\n *     Above 32×32, Chromium temporarily resets the cursor to default while it\n *     would overlap browser UI (anti-spoofing) — fine mid-viewport, so ~40px\n *     compositions are common; stay ≤128.\n *   - The keyword fallback covers browsers that refuse SVG cursor images.\n *\n * Pure string work with no EmbedPDF types — like the file picker, this module\n * is a plain web utility.\n */\n\nexport interface SvgCursorOptions {\n  /** Complete `<svg>` markup, colors baked in (no `currentColor` — a cursor\n   *  image has no cascade to inherit from). */\n  svg: string;\n  /** The click point inside the image, CSS px from the top-left. Default 0,0\n   *  (arrow-style: the image's corner is the tip). */\n  hotspot?: { x: number; y: number };\n  /** Keyword cursor when the image can't render. Default `'crosshair'`. */\n  fallback?: string;\n}\n\n/** Build the CSS cursor value: `url(\"data:image/svg+xml,…\") x y, fallback`. */\nexport function svgCursor({ svg, hotspot, fallback = 'crosshair' }: SvgCursorOptions): string {\n  // Scan only the opening `<svg …>` tag (bounded slice) rather than running\n  // `/<svg[^>]*\\swidth\\s*=/` over the whole string — the unbounded form is\n  // quadratic on pathological inputs (many `<svg` fragments with no `>`),\n  // while accepting exactly the same markup: `[^>]*` could never cross a\n  // `>` either.\n  const tagStart = svg.indexOf('<svg');\n  const tagEnd = tagStart >= 0 ? svg.indexOf('>', tagStart) : -1;\n  const openTag = tagEnd >= 0 ? svg.slice(tagStart, tagEnd + 1) : '';\n  if (!/\\swidth\\s*=/.test(openTag) || !/\\sheight\\s*=/.test(openTag)) {\n    throw new Error(\n      '[web] svgCursor: the <svg> needs explicit width/height attributes — ' +\n        'browsers ignore cursor images without an intrinsic size',\n    );\n  }\n  const uri = `data:image/svg+xml,${encodeURIComponent(svg)}`;\n  const spot = hotspot ? ` ${Math.round(hotspot.x)} ${Math.round(hotspot.y)}` : '';\n  return `url(\"${uri}\")${spot}, ${fallback}`;\n}\n","/**\n * External-URI hygiene for PDF link annotations — written ONCE here so every\n * framework adapter (react, vue, svelte, angular) shares the same policy.\n *\n * PDFs are untrusted input: a link's `/URI` can carry anything, including\n * `javascript:` payloads. The default allowlist covers what a document link\n * legitimately opens; everything else (javascript:, file:, data:, vbscript:,\n * custom app schemes) resolves to `null` and the adapters render the link\n * WITHOUT an href — activation still reports through the plugin, so an\n * embedder that needs a custom scheme can handle it in `onActivate`.\n */\nconst DEFAULT_ALLOWED_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * Validate a link URI for opening in the browser. Returns the URI when its\n * scheme is allowed (scheme-relative and bare URIs resolve as https), else\n * `null`. Never throws — a malformed URI is just an unopenable one.\n */\nexport function sanitizeExternalUri(\n  uri: string,\n  allowedSchemes: Iterable<string> = DEFAULT_ALLOWED_SCHEMES,\n): string | null {\n  const trimmed = uri.trim();\n  if (!trimmed) return null;\n  const allowed = new Set(\n    [...allowedSchemes].map((s) => (s.endsWith(':') ? s.toLowerCase() : `${s.toLowerCase()}:`)),\n  );\n  try {\n    // Base resolves scheme-relative (\"//host\") and bare (\"example.com/x\" is a\n    // relative path → https) forms; an absolute scheme wins over the base.\n    const url = new URL(trimmed, 'https://invalid.example/');\n    return allowed.has(url.protocol) ? trimmed : null;\n  } catch {\n    return null;\n  }\n}\n","/** A browser image source whose object URL has an explicit lifetime. */\nexport interface ObjectUrlImageSource {\n  objectUrl(signal?: AbortSignal): Promise<{ url: string; revoke(): void }>;\n}\n\nexport interface PaintedImageCallbacks {\n  onPainted(): void;\n  onUnpainted(): void;\n}\n\n/**\n * Bind a raster source to an <img> without ever painting its incomplete-image\n * placeholder. The source becomes visible on load; retained coverage is\n * released only after the browser has had one full frame to present it.\n *\n * Call this from the framework's pre-paint mount hook and invoke the returned\n * cleanup on unmount. Keeping this DOM lifecycle here lets every framework\n * adapter remain a ref plus one bind/unbind hook.\n */\nexport function bindPaintedImage(\n  image: HTMLImageElement,\n  source: ObjectUrlImageSource,\n  callbacks: PaintedImageCallbacks,\n): () => void {\n  const controller = new AbortController();\n  let revoke: (() => void) | undefined;\n  let frame = 0;\n  let painted = false;\n\n  // The element is already committed when a mount hook runs. Hide it before\n  // that commit can paint, then reveal only once the bitmap has loaded.\n  image.style.visibility = 'hidden';\n\n  const onLoad = () => {\n    image.style.visibility = 'visible';\n\n    // rAF callbacks run before a frame paints. The first frame presents the\n    // newly visible image while retained coverage remains; the second reports\n    // that presentation opportunity and permits the retained source to leave.\n    frame = requestAnimationFrame(() => {\n      frame = requestAnimationFrame(() => {\n        frame = 0;\n        painted = true;\n        callbacks.onPainted();\n      });\n    });\n  };\n\n  image.addEventListener('load', onLoad, { once: true });\n\n  void source.objectUrl(controller.signal).then(\n    (objectUrl) => {\n      if (controller.signal.aborted) {\n        objectUrl.revoke();\n        return;\n      }\n      revoke = objectUrl.revoke;\n      image.src = objectUrl.url;\n    },\n    () => {\n      // Aborted or unavailable: remain hidden and retain fallback coverage.\n    },\n  );\n\n  return () => {\n    controller.abort();\n    if (frame) cancelAnimationFrame(frame);\n    image.removeEventListener('load', onLoad);\n    image.style.visibility = 'hidden';\n    image.removeAttribute('src');\n    revoke?.();\n    if (painted) callbacks.onUnpainted();\n  };\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -16,6 +16,163 @@ declare const pickFile: (options?: PickFileOptions) => Promise<File | null>;
  */
 declare function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void;
 //#endregion
+//#region src/clipboard.d.ts
+/**
+ * Clipboard wiring for text selection — the environmental half of copy.
+ *
+ * The selection plugin is deliberately DOM-free: its public capability ends
+ * at `readText()` (data). Everything that touches `navigator.clipboard` or
+ * the native `copy` event lives HERE, structurally typed so this module
+ * stays a pure DOM utility with no EmbedPDF dependencies (the selection
+ * capability satisfies {@link ClipboardSelectionSource} as-is).
+ */
+/** The slice of the selection capability clipboard wiring needs. */
+interface ClipboardSelectionSource {
+  hasSelection(): boolean;
+  canCopy(): boolean;
+  readText(): Promise<string>;
+  onChange(cb: () => void): () => void;
+  onCommit(cb: () => void): () => void;
+}
+interface SelectionClipboardOptions {
+  /**
+   * Prefetch the selected text when the selection settles (default true).
+   * This is what makes the NATIVE copy path work: a `copy` event handler
+   * must call `clipboardData.setData` synchronously — awaiting a page-text
+   * read inside it is too late — and it also keeps the async path instant.
+   * The fetch is one versioned, cached, permission-gated read per page;
+   * pass false to make copying strictly on-demand.
+   */
+  prefetch?: boolean;
+  /** Event target to listen on. Defaults to `document`. */
+  target?: Document;
+}
+/**
+ * Wire clipboard copy for a selection. Two delivery paths, both fed by the
+ * prefetched text:
+ *
+ *   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page
+ *     has a DOM selection or focused editable — e.g. the viewer shell's
+ *     focus sink): answered SYNCHRONOUSLY from the cache;
+ *   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually
+ *     have none, and browsers don't dispatch `copy` then): a keydown
+ *     fallback writes via the async Clipboard API inside the keystroke's
+ *     user-activation window.
+ *
+ * Returns the unwire function. Mount once per document view (not per page).
+ */
+declare function wireSelectionClipboard(selection: ClipboardSelectionSource, options?: SelectionClipboardOptions): () => void;
+/**
+ * Toolbar/menu path: read the selected text and write it to the clipboard
+ * via the async Clipboard API. Call from a user-gesture handler (browsers
+ * require a secure context + user activation for clipboard writes). Resolves
+ * with what was copied ('' when nothing was — nothing is written then, so an
+ * empty selection never clobbers the user's clipboard).
+ */
+declare function copySelection(selection: ClipboardSelectionSource): Promise<string>;
+//#endregion
+//#region src/anchored-position.d.ts
+/**
+ * Anchored-overlay geometry for UI floating over page content (selection
+ * menus, draft menus, popovers): the projector SNAPSHOT contract, the
+ * anchor shape, and the placement math. Pure values and pure functions over
+ * structural rect/point shapes — no EmbedPDF types, no framework, no
+ * reactive lifecycle — so every framework adapter (React, Vue, Svelte,
+ * Angular) shares ONE implementation and binds it with its NATIVE
+ * reactivity (context revision, signals, computed, $derived).
+ *
+ * The boundary laws:
+ *   - Placement policy lives HERE, above the projector seam: a projector
+ *     only knows geometry — never what is being positioned nor where it
+ *     prefers to sit.
+ *   - A projector describes the CURRENT projection; it never implements a
+ *     framework-style reactive lifecycle. State-driven changes (the Stage
+ *     camera) must reach consumers through the framework's own render
+ *     cycle so surface and overlay commit TOGETHER; only genuinely
+ *     browser-driven changes (a PageView moving because the document
+ *     scrolled) use an external listener ({@link observeClientGeometry}).
+ */
+interface AnchoredRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface AnchoredPoint {
+  x: number;
+  y: number;
+}
+type AnchoredPlacement = 'top' | 'right' | 'bottom' | 'left';
+/** CSS-ready output: absolute/fixed `left`/`top` plus a centering transform. */
+interface AnchoredPosition {
+  left: number;
+  top: number;
+  transform: string;
+}
+/**
+ * Place an upright element around `box` (screen px). `avoid` is a screen
+ * point the element must clear (e.g. the rotate knob): the element extends
+ * ONLY the edge it sits on, and ONLY when the point protrudes past that
+ * edge — so it clears the obstacle without ever shifting off-centre on the
+ * other axis. When the point is on another side (e.g. a 90° shape, knob at
+ * mid-height for a `top` placement) the edge is untouched and the element
+ * stays centred on `box`.
+ */
+/** What anchored UI attaches to: a content-space rect on a page, plus
+ *  optional content-space points the UI must clear (e.g. a rotate knob).
+ *  Structural — plugin anchor reads satisfy it without importing this
+ *  package. */
+interface AnchorTarget {
+  pon: number;
+  bounds: AnchoredRect;
+  avoid?: AnchoredPoint[];
+}
+/**
+ * A page surface's PROJECTION SNAPSHOT: how a content-space rect on a page
+ * becomes screen coordinates, right now. Provided by `<Stage>`
+ * (camera-driven, pure state, no DOM reads) and `<PageView>` (DOM-measured).
+ * Deliberately NO subscribe here — when projection changes is a framework
+ * binding concern (see the module doc), not part of the snapshot.
+ */
+interface ViewProjector {
+  /**
+   * Which coordinate space `toScreen` speaks, and therefore how anchored
+   * content mounts:
+   *   - 'overlay': coords are relative to the surface's own positioned
+   *     container → rendered in place, position:absolute. (Stage)
+   *   - 'client': coords are viewport px → portalled to the document body,
+   *     position:fixed, so no ancestor overflow can clip. (PageView)
+   */
+  space: 'overlay' | 'client';
+  /** Content-space rect on a page → coords in `space`. Null: not projectable
+   *  right now (page not shown / not measurable yet). */
+  toScreen(pon: number, rect: AnchoredRect): AnchoredRect | null;
+  toScreenPoint(pon: number, at: AnchoredPoint): AnchoredPoint | null;
+  /** The page's live view facts (for anchor reads that need them — e.g. the
+   *  screen-constant rotate-knob stalk), or null when the page isn't shown. */
+  viewEnv(pon: number): {
+    scale: number;
+    rotation: 0 | 90 | 180 | 270;
+    zoom: number;
+  } | null;
+}
+/**
+ * THE anchored projection: anchor → screen position, in one pure call —
+ * projection, avoid-point transform, and the shared placement policy.
+ * Frameworks recompute this inside their native reactive primitive
+ * (a React render, a Vue `computed`, an Angular signal, a Svelte
+ * `$derived`); nothing here schedules anything.
+ */
+declare function projectAnchoredTarget(projector: ViewProjector, anchor: AnchorTarget, placement: AnchoredPlacement, gap: number): AnchoredPosition | null;
+/**
+ * The one genuinely BROWSER-driven invalidation: an element in normal
+ * document flow moves when the document scrolls or the window resizes —
+ * no state change announces it. `<PageView>`'s binding registers this;
+ * the Stage never does (its camera is state, delivered through render).
+ */
+declare function observeClientGeometry(callback: () => void): () => void;
+declare function positionAnchoredRect(box: AnchoredRect, placement: AnchoredPlacement, gap: number, avoid?: AnchoredPoint | null): AnchoredPosition;
+//#endregion
 //#region src/cursor.d.ts
 /**
  * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the
@@ -59,5 +216,28 @@ declare function svgCursor({ svg, hotspot, fallback }: SvgCursorOptions): string
  */
 declare function sanitizeExternalUri(uri: string, allowedSchemes?: Iterable<string>): string | null;
 //#endregion
-export { type PickFileOptions, type SvgCursorOptions, pickFile, pickImageFile, sanitizeExternalUri, saveFile, svgCursor };
+//#region src/painted-image.d.ts
+/** A browser image source whose object URL has an explicit lifetime. */
+interface ObjectUrlImageSource {
+  objectUrl(signal?: AbortSignal): Promise<{
+    url: string;
+    revoke(): void;
+  }>;
+}
+interface PaintedImageCallbacks {
+  onPainted(): void;
+  onUnpainted(): void;
+}
+/**
+ * Bind a raster source to an <img> without ever painting its incomplete-image
+ * placeholder. The source becomes visible on load; retained coverage is
+ * released only after the browser has had one full frame to present it.
+ *
+ * Call this from the framework's pre-paint mount hook and invoke the returned
+ * cleanup on unmount. Keeping this DOM lifecycle here lets every framework
+ * adapter remain a ref plus one bind/unbind hook.
+ */
+declare function bindPaintedImage(image: HTMLImageElement, source: ObjectUrlImageSource, callbacks: PaintedImageCallbacks): () => void;
+//#endregion
+export { type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type ClipboardSelectionSource, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SvgCursorOptions, type ViewProjector, bindPaintedImage, copySelection, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, wireSelectionClipboard };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -16,6 +16,163 @@ declare const pickFile: (options?: PickFileOptions) => Promise<File | null>;
  */
 declare function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void;
 //#endregion
+//#region src/clipboard.d.ts
+/**
+ * Clipboard wiring for text selection — the environmental half of copy.
+ *
+ * The selection plugin is deliberately DOM-free: its public capability ends
+ * at `readText()` (data). Everything that touches `navigator.clipboard` or
+ * the native `copy` event lives HERE, structurally typed so this module
+ * stays a pure DOM utility with no EmbedPDF dependencies (the selection
+ * capability satisfies {@link ClipboardSelectionSource} as-is).
+ */
+/** The slice of the selection capability clipboard wiring needs. */
+interface ClipboardSelectionSource {
+  hasSelection(): boolean;
+  canCopy(): boolean;
+  readText(): Promise<string>;
+  onChange(cb: () => void): () => void;
+  onCommit(cb: () => void): () => void;
+}
+interface SelectionClipboardOptions {
+  /**
+   * Prefetch the selected text when the selection settles (default true).
+   * This is what makes the NATIVE copy path work: a `copy` event handler
+   * must call `clipboardData.setData` synchronously — awaiting a page-text
+   * read inside it is too late — and it also keeps the async path instant.
+   * The fetch is one versioned, cached, permission-gated read per page;
+   * pass false to make copying strictly on-demand.
+   */
+  prefetch?: boolean;
+  /** Event target to listen on. Defaults to `document`. */
+  target?: Document;
+}
+/**
+ * Wire clipboard copy for a selection. Two delivery paths, both fed by the
+ * prefetched text:
+ *
+ *   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page
+ *     has a DOM selection or focused editable — e.g. the viewer shell's
+ *     focus sink): answered SYNCHRONOUSLY from the cache;
+ *   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually
+ *     have none, and browsers don't dispatch `copy` then): a keydown
+ *     fallback writes via the async Clipboard API inside the keystroke's
+ *     user-activation window.
+ *
+ * Returns the unwire function. Mount once per document view (not per page).
+ */
+declare function wireSelectionClipboard(selection: ClipboardSelectionSource, options?: SelectionClipboardOptions): () => void;
+/**
+ * Toolbar/menu path: read the selected text and write it to the clipboard
+ * via the async Clipboard API. Call from a user-gesture handler (browsers
+ * require a secure context + user activation for clipboard writes). Resolves
+ * with what was copied ('' when nothing was — nothing is written then, so an
+ * empty selection never clobbers the user's clipboard).
+ */
+declare function copySelection(selection: ClipboardSelectionSource): Promise<string>;
+//#endregion
+//#region src/anchored-position.d.ts
+/**
+ * Anchored-overlay geometry for UI floating over page content (selection
+ * menus, draft menus, popovers): the projector SNAPSHOT contract, the
+ * anchor shape, and the placement math. Pure values and pure functions over
+ * structural rect/point shapes — no EmbedPDF types, no framework, no
+ * reactive lifecycle — so every framework adapter (React, Vue, Svelte,
+ * Angular) shares ONE implementation and binds it with its NATIVE
+ * reactivity (context revision, signals, computed, $derived).
+ *
+ * The boundary laws:
+ *   - Placement policy lives HERE, above the projector seam: a projector
+ *     only knows geometry — never what is being positioned nor where it
+ *     prefers to sit.
+ *   - A projector describes the CURRENT projection; it never implements a
+ *     framework-style reactive lifecycle. State-driven changes (the Stage
+ *     camera) must reach consumers through the framework's own render
+ *     cycle so surface and overlay commit TOGETHER; only genuinely
+ *     browser-driven changes (a PageView moving because the document
+ *     scrolled) use an external listener ({@link observeClientGeometry}).
+ */
+interface AnchoredRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface AnchoredPoint {
+  x: number;
+  y: number;
+}
+type AnchoredPlacement = 'top' | 'right' | 'bottom' | 'left';
+/** CSS-ready output: absolute/fixed `left`/`top` plus a centering transform. */
+interface AnchoredPosition {
+  left: number;
+  top: number;
+  transform: string;
+}
+/**
+ * Place an upright element around `box` (screen px). `avoid` is a screen
+ * point the element must clear (e.g. the rotate knob): the element extends
+ * ONLY the edge it sits on, and ONLY when the point protrudes past that
+ * edge — so it clears the obstacle without ever shifting off-centre on the
+ * other axis. When the point is on another side (e.g. a 90° shape, knob at
+ * mid-height for a `top` placement) the edge is untouched and the element
+ * stays centred on `box`.
+ */
+/** What anchored UI attaches to: a content-space rect on a page, plus
+ *  optional content-space points the UI must clear (e.g. a rotate knob).
+ *  Structural — plugin anchor reads satisfy it without importing this
+ *  package. */
+interface AnchorTarget {
+  pon: number;
+  bounds: AnchoredRect;
+  avoid?: AnchoredPoint[];
+}
+/**
+ * A page surface's PROJECTION SNAPSHOT: how a content-space rect on a page
+ * becomes screen coordinates, right now. Provided by `<Stage>`
+ * (camera-driven, pure state, no DOM reads) and `<PageView>` (DOM-measured).
+ * Deliberately NO subscribe here — when projection changes is a framework
+ * binding concern (see the module doc), not part of the snapshot.
+ */
+interface ViewProjector {
+  /**
+   * Which coordinate space `toScreen` speaks, and therefore how anchored
+   * content mounts:
+   *   - 'overlay': coords are relative to the surface's own positioned
+   *     container → rendered in place, position:absolute. (Stage)
+   *   - 'client': coords are viewport px → portalled to the document body,
+   *     position:fixed, so no ancestor overflow can clip. (PageView)
+   */
+  space: 'overlay' | 'client';
+  /** Content-space rect on a page → coords in `space`. Null: not projectable
+   *  right now (page not shown / not measurable yet). */
+  toScreen(pon: number, rect: AnchoredRect): AnchoredRect | null;
+  toScreenPoint(pon: number, at: AnchoredPoint): AnchoredPoint | null;
+  /** The page's live view facts (for anchor reads that need them — e.g. the
+   *  screen-constant rotate-knob stalk), or null when the page isn't shown. */
+  viewEnv(pon: number): {
+    scale: number;
+    rotation: 0 | 90 | 180 | 270;
+    zoom: number;
+  } | null;
+}
+/**
+ * THE anchored projection: anchor → screen position, in one pure call —
+ * projection, avoid-point transform, and the shared placement policy.
+ * Frameworks recompute this inside their native reactive primitive
+ * (a React render, a Vue `computed`, an Angular signal, a Svelte
+ * `$derived`); nothing here schedules anything.
+ */
+declare function projectAnchoredTarget(projector: ViewProjector, anchor: AnchorTarget, placement: AnchoredPlacement, gap: number): AnchoredPosition | null;
+/**
+ * The one genuinely BROWSER-driven invalidation: an element in normal
+ * document flow moves when the document scrolls or the window resizes —
+ * no state change announces it. `<PageView>`'s binding registers this;
+ * the Stage never does (its camera is state, delivered through render).
+ */
+declare function observeClientGeometry(callback: () => void): () => void;
+declare function positionAnchoredRect(box: AnchoredRect, placement: AnchoredPlacement, gap: number, avoid?: AnchoredPoint | null): AnchoredPosition;
+//#endregion
 //#region src/cursor.d.ts
 /**
  * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the
@@ -59,5 +216,28 @@ declare function svgCursor({ svg, hotspot, fallback }: SvgCursorOptions): string
  */
 declare function sanitizeExternalUri(uri: string, allowedSchemes?: Iterable<string>): string | null;
 //#endregion
-export { type PickFileOptions, type SvgCursorOptions, pickFile, pickImageFile, sanitizeExternalUri, saveFile, svgCursor };
+//#region src/painted-image.d.ts
+/** A browser image source whose object URL has an explicit lifetime. */
+interface ObjectUrlImageSource {
+  objectUrl(signal?: AbortSignal): Promise<{
+    url: string;
+    revoke(): void;
+  }>;
+}
+interface PaintedImageCallbacks {
+  onPainted(): void;
+  onUnpainted(): void;
+}
+/**
+ * Bind a raster source to an <img> without ever painting its incomplete-image
+ * placeholder. The source becomes visible on load; retained coverage is
+ * released only after the browser has had one full frame to present it.
+ *
+ * Call this from the framework's pre-paint mount hook and invoke the returned
+ * cleanup on unmount. Keeping this DOM lifecycle here lets every framework
+ * adapter remain a ref plus one bind/unbind hook.
+ */
+declare function bindPaintedImage(image: HTMLImageElement, source: ObjectUrlImageSource, callbacks: PaintedImageCallbacks): () => void;
+//#endregion
+export { type AnchorTarget, type AnchoredPlacement, type AnchoredPoint, type AnchoredPosition, type AnchoredRect, type ClipboardSelectionSource, type ObjectUrlImageSource, type PaintedImageCallbacks, type PickFileOptions, type SelectionClipboardOptions, type SvgCursorOptions, type ViewProjector, bindPaintedImage, copySelection, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, wireSelectionClipboard };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -59,6 +59,136 @@ function saveFile(bytes, name, mimeType) {
 	setTimeout(() => URL.revokeObjectURL(url), 1e3);
 }
 //#endregion
+//#region src/clipboard.ts
+const PREFETCH_DEBOUNCE_MS = 150;
+/**
+* Wire clipboard copy for a selection. Two delivery paths, both fed by the
+* prefetched text:
+*
+*   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page
+*     has a DOM selection or focused editable — e.g. the viewer shell's
+*     focus sink): answered SYNCHRONOUSLY from the cache;
+*   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually
+*     have none, and browsers don't dispatch `copy` then): a keydown
+*     fallback writes via the async Clipboard API inside the keystroke's
+*     user-activation window.
+*
+* Returns the unwire function. Mount once per document view (not per page).
+*/
+function wireSelectionClipboard(selection, options = {}) {
+	const target = options.target ?? document;
+	const prefetch = options.prefetch ?? true;
+	let cached = null;
+	let generation = 0;
+	let timer = null;
+	const refresh = () => {
+		cached = null;
+		if (!prefetch || !selection.hasSelection() || !selection.canCopy()) return;
+		const gen = ++generation;
+		selection.readText().then((text) => {
+			if (gen === generation) cached = text;
+		}, () => {});
+	};
+	const offCommit = selection.onCommit(() => {
+		if (timer) clearTimeout(timer);
+		timer = null;
+		refresh();
+	});
+	const offChange = selection.onChange(() => {
+		generation++;
+		cached = null;
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(refresh, PREFETCH_DEBOUNCE_MS);
+	});
+	const onCopy = (e) => {
+		if (cached == null || cached === "" || !selection.hasSelection()) return;
+		e.clipboardData?.setData("text/plain", cached);
+		e.preventDefault();
+	};
+	const onKeyDown = (e) => {
+		if (!(e.metaKey || e.ctrlKey) || e.key.toLowerCase() !== "c" || e.shiftKey || e.altKey) return;
+		if (!selection.hasSelection() || !selection.canCopy()) return;
+		const dom = target.getSelection?.();
+		if (dom && !dom.isCollapsed) return;
+		copySelection(selection);
+	};
+	target.addEventListener("copy", onCopy);
+	target.addEventListener("keydown", onKeyDown);
+	return () => {
+		offCommit();
+		offChange();
+		if (timer) clearTimeout(timer);
+		target.removeEventListener("copy", onCopy);
+		target.removeEventListener("keydown", onKeyDown);
+	};
+}
+/**
+* Toolbar/menu path: read the selected text and write it to the clipboard
+* via the async Clipboard API. Call from a user-gesture handler (browsers
+* require a secure context + user activation for clipboard writes). Resolves
+* with what was copied ('' when nothing was — nothing is written then, so an
+* empty selection never clobbers the user's clipboard).
+*/
+async function copySelection(selection) {
+	const text = await selection.readText();
+	if (text !== "") await navigator.clipboard.writeText(text);
+	return text;
+}
+//#endregion
+//#region src/anchored-position.ts
+/**
+* THE anchored projection: anchor → screen position, in one pure call —
+* projection, avoid-point transform, and the shared placement policy.
+* Frameworks recompute this inside their native reactive primitive
+* (a React render, a Vue `computed`, an Angular signal, a Svelte
+* `$derived`); nothing here schedules anything.
+*/
+function projectAnchoredTarget(projector, anchor, placement, gap) {
+	const box = projector.toScreen(anchor.pon, anchor.bounds);
+	if (!box) return null;
+	return positionAnchoredRect(box, placement, gap, anchor.avoid?.length ? projector.toScreenPoint(anchor.pon, anchor.avoid[0]) : null);
+}
+/**
+* The one genuinely BROWSER-driven invalidation: an element in normal
+* document flow moves when the document scrolls or the window resizes —
+* no state change announces it. `<PageView>`'s binding registers this;
+* the Stage never does (its camera is state, delivered through render).
+*/
+function observeClientGeometry(callback) {
+	window.addEventListener("scroll", callback, true);
+	window.addEventListener("resize", callback);
+	return () => {
+		window.removeEventListener("scroll", callback, true);
+		window.removeEventListener("resize", callback);
+	};
+}
+function positionAnchoredRect(box, placement, gap, avoid) {
+	const cx = box.x + box.width / 2;
+	const cy = box.y + box.height / 2;
+	switch (placement) {
+		case "bottom": return {
+			left: cx,
+			top: Math.max(box.y + box.height, avoid ? avoid.y : -Infinity) + gap,
+			transform: "translate(-50%, 0)"
+		};
+		case "left": return {
+			left: Math.min(box.x, avoid ? avoid.x : Infinity) - gap,
+			top: cy,
+			transform: "translate(-100%, -50%)"
+		};
+		case "right": return {
+			left: Math.max(box.x + box.width, avoid ? avoid.x : -Infinity) + gap,
+			top: cy,
+			transform: "translate(0, -50%)"
+		};
+		default: return {
+			left: cx,
+			top: Math.min(box.y, avoid ? avoid.y : Infinity) - gap,
+			transform: "translate(-50%, -100%)"
+		};
+	}
+}
+//#endregion
 //#region src/cursor.ts
 /** Build the CSS cursor value: `url("data:image/svg+xml,…") x y, fallback`. */
 function svgCursor({ svg, hotspot, fallback = "crosshair" }) {
@@ -104,6 +234,52 @@ function sanitizeExternalUri(uri, allowedSchemes = DEFAULT_ALLOWED_SCHEMES) {
 	}
 }
 //#endregion
-export { pickFile, pickImageFile, sanitizeExternalUri, saveFile, svgCursor };
+//#region src/painted-image.ts
+/**
+* Bind a raster source to an <img> without ever painting its incomplete-image
+* placeholder. The source becomes visible on load; retained coverage is
+* released only after the browser has had one full frame to present it.
+*
+* Call this from the framework's pre-paint mount hook and invoke the returned
+* cleanup on unmount. Keeping this DOM lifecycle here lets every framework
+* adapter remain a ref plus one bind/unbind hook.
+*/
+function bindPaintedImage(image, source, callbacks) {
+	const controller = new AbortController();
+	let revoke;
+	let frame = 0;
+	let painted = false;
+	image.style.visibility = "hidden";
+	const onLoad = () => {
+		image.style.visibility = "visible";
+		frame = requestAnimationFrame(() => {
+			frame = requestAnimationFrame(() => {
+				frame = 0;
+				painted = true;
+				callbacks.onPainted();
+			});
+		});
+	};
+	image.addEventListener("load", onLoad, { once: true });
+	source.objectUrl(controller.signal).then((objectUrl) => {
+		if (controller.signal.aborted) {
+			objectUrl.revoke();
+			return;
+		}
+		revoke = objectUrl.revoke;
+		image.src = objectUrl.url;
+	}, () => {});
+	return () => {
+		controller.abort();
+		if (frame) cancelAnimationFrame(frame);
+		image.removeEventListener("load", onLoad);
+		image.style.visibility = "hidden";
+		image.removeAttribute("src");
+		revoke?.();
+		if (painted) callbacks.onUnpainted();
+	};
+}
+//#endregion
+export { bindPaintedImage, copySelection, observeClientGeometry, pickFile, pickImageFile, positionAnchoredRect, projectAnchoredTarget, sanitizeExternalUri, saveFile, svgCursor, wireSelectionClipboard };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/file-picker.ts","../src/cursor.ts","../src/external-uri.ts"],"sourcesContent":["/**\n * A one-shot file dialog. Opens a throwaway `<input type=file>`, resolves the\n * chosen `File`, or `null` when the dialog is dismissed. MUST be called\n * synchronously from a user gesture (a click) or the browser refuses to open it.\n *\n * A `File` is a `Blob`, which is a `BinarySource` everywhere in the stack, so the\n * caller can hand the result straight to the engine — this module stays a pure\n * DOM utility with no EmbedPDF types.\n */\nconst IMAGE_ACCEPT = 'image/png,image/jpeg,application/pdf';\n\nexport interface PickFileOptions {\n  /** The dialog's `accept` filter. Defaults to PNG / JPEG / PDF. */\n  accept?: string;\n  /** Allow multiple selection (returns the first file). Defaults to false. */\n  multiple?: boolean;\n}\n\n/** Open the file dialog; resolve the picked file, or null if cancelled. */\nexport function pickImageFile(options: PickFileOptions = {}): Promise<File | null> {\n  const { accept = IMAGE_ACCEPT, multiple = false } = options;\n  return new Promise((resolve) => {\n    const input = document.createElement('input');\n    input.type = 'file';\n    input.accept = accept;\n    input.multiple = multiple;\n    input.style.display = 'none';\n\n    let settled = false;\n    const finish = (value: File | null): void => {\n      if (settled) return;\n      settled = true;\n      window.removeEventListener('focus', onFocus);\n      input.remove();\n      resolve(value);\n    };\n\n    // A window refocus means the dialog closed. Give a queued `change` a tick to\n    // win, then treat a bare refocus as a cancel — the fallback for browsers that\n    // predate the `cancel` event.\n    const onFocus = (): void => {\n      setTimeout(() => finish(null), 300);\n    };\n\n    input.addEventListener('change', () => finish(input.files?.[0] ?? null), { once: true });\n    input.addEventListener('cancel', () => finish(null), { once: true });\n    window.addEventListener('focus', onFocus, { once: true });\n\n    document.body.appendChild(input);\n    input.click();\n  });\n}\n\n/** The same dialog with NO type filter — any file (attachments). */\nexport const pickFile = (options: PickFileOptions = {}): Promise<File | null> =>\n  pickImageFile({ accept: '*/*', ...options });\n\n/**\n * Hand bytes to the user as a browser download (a one-shot `<a download>`).\n * The DOM half of \"download this attachment\" — pair with the annotation\n * capability's `downloadAttachment` or the document `attachments.download`.\n */\nexport function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void {\n  const blob =\n    bytes instanceof Blob\n      ? bytes\n      : new Blob([bytes as BlobPart], { type: mimeType ?? 'application/octet-stream' });\n  const url = URL.createObjectURL(blob);\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = name;\n  a.style.display = 'none';\n  document.body.appendChild(a);\n  a.click();\n  a.remove();\n  setTimeout(() => URL.revokeObjectURL(url), 1000);\n}\n","/**\n * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the\n * only zero-latency pointer-locked pixel the web has — the OS composites it),\n * so an app hands its toolbar icon here and assigns the result via the\n * interaction hub's `setToolCursor`.\n *\n * Browser rules baked into this module:\n *   - The SVG must carry explicit `width`/`height` attributes (not just a\n *     viewBox) or Chromium/WebKit ignore it — enforced here.\n *   - The hard ceiling is 128×128 CSS px (bigger falls back to the keyword).\n *     Above 32×32, Chromium temporarily resets the cursor to default while it\n *     would overlap browser UI (anti-spoofing) — fine mid-viewport, so ~40px\n *     compositions are common; stay ≤128.\n *   - The keyword fallback covers browsers that refuse SVG cursor images.\n *\n * Pure string work with no EmbedPDF types — like the file picker, this module\n * is a plain web utility.\n */\n\nexport interface SvgCursorOptions {\n  /** Complete `<svg>` markup, colors baked in (no `currentColor` — a cursor\n   *  image has no cascade to inherit from). */\n  svg: string;\n  /** The click point inside the image, CSS px from the top-left. Default 0,0\n   *  (arrow-style: the image's corner is the tip). */\n  hotspot?: { x: number; y: number };\n  /** Keyword cursor when the image can't render. Default `'crosshair'`. */\n  fallback?: string;\n}\n\n/** Build the CSS cursor value: `url(\"data:image/svg+xml,…\") x y, fallback`. */\nexport function svgCursor({ svg, hotspot, fallback = 'crosshair' }: SvgCursorOptions): string {\n  // Scan only the opening `<svg …>` tag (bounded slice) rather than running\n  // `/<svg[^>]*\\swidth\\s*=/` over the whole string — the unbounded form is\n  // quadratic on pathological inputs (many `<svg` fragments with no `>`),\n  // while accepting exactly the same markup: `[^>]*` could never cross a\n  // `>` either.\n  const tagStart = svg.indexOf('<svg');\n  const tagEnd = tagStart >= 0 ? svg.indexOf('>', tagStart) : -1;\n  const openTag = tagEnd >= 0 ? svg.slice(tagStart, tagEnd + 1) : '';\n  if (!/\\swidth\\s*=/.test(openTag) || !/\\sheight\\s*=/.test(openTag)) {\n    throw new Error(\n      '[web] svgCursor: the <svg> needs explicit width/height attributes — ' +\n        'browsers ignore cursor images without an intrinsic size',\n    );\n  }\n  const uri = `data:image/svg+xml,${encodeURIComponent(svg)}`;\n  const spot = hotspot ? ` ${Math.round(hotspot.x)} ${Math.round(hotspot.y)}` : '';\n  return `url(\"${uri}\")${spot}, ${fallback}`;\n}\n","/**\n * External-URI hygiene for PDF link annotations — written ONCE here so every\n * framework adapter (react, vue, svelte, angular) shares the same policy.\n *\n * PDFs are untrusted input: a link's `/URI` can carry anything, including\n * `javascript:` payloads. The default allowlist covers what a document link\n * legitimately opens; everything else (javascript:, file:, data:, vbscript:,\n * custom app schemes) resolves to `null` and the adapters render the link\n * WITHOUT an href — activation still reports through the plugin, so an\n * embedder that needs a custom scheme can handle it in `onActivate`.\n */\nconst DEFAULT_ALLOWED_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * Validate a link URI for opening in the browser. Returns the URI when its\n * scheme is allowed (scheme-relative and bare URIs resolve as https), else\n * `null`. Never throws — a malformed URI is just an unopenable one.\n */\nexport function sanitizeExternalUri(\n  uri: string,\n  allowedSchemes: Iterable<string> = DEFAULT_ALLOWED_SCHEMES,\n): string | null {\n  const trimmed = uri.trim();\n  if (!trimmed) return null;\n  const allowed = new Set(\n    [...allowedSchemes].map((s) => (s.endsWith(':') ? s.toLowerCase() : `${s.toLowerCase()}:`)),\n  );\n  try {\n    // Base resolves scheme-relative (\"//host\") and bare (\"example.com/x\" is a\n    // relative path → https) forms; an absolute scheme wins over the base.\n    const url = new URL(trimmed, 'https://invalid.example/');\n    return allowed.has(url.protocol) ? trimmed : null;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;;;;;;;;AASA,MAAM,eAAe;;AAUrB,SAAgB,cAAc,UAA2B,CAAC,GAAyB;CACjF,MAAM,EAAE,SAAS,cAAc,WAAW,UAAU;CACpD,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,QAAQ,SAAS,cAAc,OAAO;EAC5C,MAAM,OAAO;EACb,MAAM,SAAS;EACf,MAAM,WAAW;EACjB,MAAM,MAAM,UAAU;EAEtB,IAAI,UAAU;EACd,MAAM,UAAU,UAA6B;GAC3C,IAAI,SAAS;GACb,UAAU;GACV,OAAO,oBAAoB,SAAS,OAAO;GAC3C,MAAM,OAAO;GACb,QAAQ,KAAK;EACf;EAKA,MAAM,gBAAsB;GAC1B,iBAAiB,OAAO,IAAI,GAAG,GAAG;EACpC;EAEA,MAAM,iBAAiB,gBAAgB,OAAO,MAAM,QAAQ,MAAM,IAAI,GAAG,EAAE,MAAM,KAAK,CAAC;EACvF,MAAM,iBAAiB,gBAAgB,OAAO,IAAI,GAAG,EAAE,MAAM,KAAK,CAAC;EACnE,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAExD,SAAS,KAAK,YAAY,KAAK;EAC/B,MAAM,MAAM;CACd,CAAC;AACH;;AAGA,MAAa,YAAY,UAA2B,CAAC,MACnD,cAAc;CAAE,QAAQ;CAAO,GAAG;AAAQ,CAAC;;;;;;AAO7C,SAAgB,SAAS,OAA0B,MAAc,UAAyB;CACxF,MAAM,OACJ,iBAAiB,OACb,QACA,IAAI,KAAK,CAAC,KAAiB,GAAG,EAAE,MAAM,YAAY,2BAA2B,CAAC;CACpF,MAAM,MAAM,IAAI,gBAAgB,IAAI;CACpC,MAAM,IAAI,SAAS,cAAc,GAAG;CACpC,EAAE,OAAO;CACT,EAAE,WAAW;CACb,EAAE,MAAM,UAAU;CAClB,SAAS,KAAK,YAAY,CAAC;CAC3B,EAAE,MAAM;CACR,EAAE,OAAO;CACT,iBAAiB,IAAI,gBAAgB,GAAG,GAAG,GAAI;AACjD;;;;AC7CA,SAAgB,UAAU,EAAE,KAAK,SAAS,WAAW,eAAyC;CAM5F,MAAM,WAAW,IAAI,QAAQ,MAAM;CACnC,MAAM,SAAS,YAAY,IAAI,IAAI,QAAQ,KAAK,QAAQ,IAAI;CAC5D,MAAM,UAAU,UAAU,IAAI,IAAI,MAAM,UAAU,SAAS,CAAC,IAAI;CAChE,IAAI,CAAC,cAAc,KAAK,OAAO,KAAK,CAAC,eAAe,KAAK,OAAO,GAC9D,MAAM,IAAI,MACR,6HAEF;CAIF,OAAO,QAAQ,sBAFmB,mBAAmB,GAAG,IAErC,IADN,UAAU,IAAI,KAAK,MAAM,QAAQ,CAAC,EAAE,GAAG,KAAK,MAAM,QAAQ,CAAC,MAAM,GAClD,IAAI;AAClC;;;;;;;;;;;;;;ACtCA,MAAM,0CAA0B,IAAI,IAAI;CAAC;CAAS;CAAU;CAAW;AAAM,CAAC;;;;;;AAO9E,SAAgB,oBACd,KACA,iBAAmC,yBACpB;CACf,MAAM,UAAU,IAAI,KAAK;CACzB,IAAI,CAAC,SAAS,OAAO;CACrB,MAAM,UAAU,IAAI,IAClB,CAAC,GAAG,cAAc,CAAC,CAAC,KAAK,MAAO,EAAE,SAAS,GAAG,IAAI,EAAE,YAAY,IAAI,GAAG,EAAE,YAAY,EAAE,EAAG,CAC5F;CACA,IAAI;EAGF,MAAM,MAAM,IAAI,IAAI,SAAS,0BAA0B;EACvD,OAAO,QAAQ,IAAI,IAAI,QAAQ,IAAI,UAAU;CAC/C,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/file-picker.ts","../src/clipboard.ts","../src/anchored-position.ts","../src/cursor.ts","../src/external-uri.ts","../src/painted-image.ts"],"sourcesContent":["/**\n * A one-shot file dialog. Opens a throwaway `<input type=file>`, resolves the\n * chosen `File`, or `null` when the dialog is dismissed. MUST be called\n * synchronously from a user gesture (a click) or the browser refuses to open it.\n *\n * A `File` is a `Blob`, which is a `BinarySource` everywhere in the stack, so the\n * caller can hand the result straight to the engine — this module stays a pure\n * DOM utility with no EmbedPDF types.\n */\nconst IMAGE_ACCEPT = 'image/png,image/jpeg,application/pdf';\n\nexport interface PickFileOptions {\n  /** The dialog's `accept` filter. Defaults to PNG / JPEG / PDF. */\n  accept?: string;\n  /** Allow multiple selection (returns the first file). Defaults to false. */\n  multiple?: boolean;\n}\n\n/** Open the file dialog; resolve the picked file, or null if cancelled. */\nexport function pickImageFile(options: PickFileOptions = {}): Promise<File | null> {\n  const { accept = IMAGE_ACCEPT, multiple = false } = options;\n  return new Promise((resolve) => {\n    const input = document.createElement('input');\n    input.type = 'file';\n    input.accept = accept;\n    input.multiple = multiple;\n    input.style.display = 'none';\n\n    let settled = false;\n    const finish = (value: File | null): void => {\n      if (settled) return;\n      settled = true;\n      window.removeEventListener('focus', onFocus);\n      input.remove();\n      resolve(value);\n    };\n\n    // A window refocus means the dialog closed. Give a queued `change` a tick to\n    // win, then treat a bare refocus as a cancel — the fallback for browsers that\n    // predate the `cancel` event.\n    const onFocus = (): void => {\n      setTimeout(() => finish(null), 300);\n    };\n\n    input.addEventListener('change', () => finish(input.files?.[0] ?? null), { once: true });\n    input.addEventListener('cancel', () => finish(null), { once: true });\n    window.addEventListener('focus', onFocus, { once: true });\n\n    document.body.appendChild(input);\n    input.click();\n  });\n}\n\n/** The same dialog with NO type filter — any file (attachments). */\nexport const pickFile = (options: PickFileOptions = {}): Promise<File | null> =>\n  pickImageFile({ accept: '*/*', ...options });\n\n/**\n * Hand bytes to the user as a browser download (a one-shot `<a download>`).\n * The DOM half of \"download this attachment\" — pair with the annotation\n * capability's `downloadAttachment` or the document `attachments.download`.\n */\nexport function saveFile(bytes: Uint8Array | Blob, name: string, mimeType?: string): void {\n  const blob =\n    bytes instanceof Blob\n      ? bytes\n      : new Blob([bytes as BlobPart], { type: mimeType ?? 'application/octet-stream' });\n  const url = URL.createObjectURL(blob);\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = name;\n  a.style.display = 'none';\n  document.body.appendChild(a);\n  a.click();\n  a.remove();\n  setTimeout(() => URL.revokeObjectURL(url), 1000);\n}\n","/**\n * Clipboard wiring for text selection — the environmental half of copy.\n *\n * The selection plugin is deliberately DOM-free: its public capability ends\n * at `readText()` (data). Everything that touches `navigator.clipboard` or\n * the native `copy` event lives HERE, structurally typed so this module\n * stays a pure DOM utility with no EmbedPDF dependencies (the selection\n * capability satisfies {@link ClipboardSelectionSource} as-is).\n */\n\n/** The slice of the selection capability clipboard wiring needs. */\nexport interface ClipboardSelectionSource {\n  hasSelection(): boolean;\n  canCopy(): boolean;\n  readText(): Promise<string>;\n  onChange(cb: () => void): () => void;\n  onCommit(cb: () => void): () => void;\n}\n\nexport interface SelectionClipboardOptions {\n  /**\n   * Prefetch the selected text when the selection settles (default true).\n   * This is what makes the NATIVE copy path work: a `copy` event handler\n   * must call `clipboardData.setData` synchronously — awaiting a page-text\n   * read inside it is too late — and it also keeps the async path instant.\n   * The fetch is one versioned, cached, permission-gated read per page;\n   * pass false to make copying strictly on-demand.\n   */\n  prefetch?: boolean;\n  /** Event target to listen on. Defaults to `document`. */\n  target?: Document;\n}\n\nconst PREFETCH_DEBOUNCE_MS = 150;\n\n/**\n * Wire clipboard copy for a selection. Two delivery paths, both fed by the\n * prefetched text:\n *\n *   - the native `copy` event (menu Edit→Copy, or ctrl/cmd+C while the page\n *     has a DOM selection or focused editable — e.g. the viewer shell's\n *     focus sink): answered SYNCHRONOUSLY from the cache;\n *   - ctrl/cmd+C with no DOM selection (canvas-rendered viewers usually\n *     have none, and browsers don't dispatch `copy` then): a keydown\n *     fallback writes via the async Clipboard API inside the keystroke's\n *     user-activation window.\n *\n * Returns the unwire function. Mount once per document view (not per page).\n */\nexport function wireSelectionClipboard(\n  selection: ClipboardSelectionSource,\n  options: SelectionClipboardOptions = {},\n): () => void {\n  const target = options.target ?? document;\n  const prefetch = options.prefetch ?? true;\n  let cached: string | null = null;\n  let generation = 0;\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  const refresh = (): void => {\n    cached = null;\n    if (!prefetch || !selection.hasSelection() || !selection.canCopy()) return;\n    const gen = ++generation;\n    selection.readText().then(\n      (text) => {\n        if (gen === generation) cached = text;\n      },\n      () => {}, // denied / failed — the async path will surface it if used\n    );\n  };\n\n  // Commit (gesture end) refreshes immediately; change (drag, programmatic\n  // select) debounces so a drag doesn't fetch per pointer move.\n  const offCommit = selection.onCommit(() => {\n    if (timer) clearTimeout(timer);\n    timer = null;\n    refresh();\n  });\n  const offChange = selection.onChange(() => {\n    generation++;\n    cached = null;\n    if (timer) clearTimeout(timer);\n    timer = setTimeout(refresh, PREFETCH_DEBOUNCE_MS);\n  });\n\n  const onCopy = (e: ClipboardEvent): void => {\n    if (cached == null || cached === '' || !selection.hasSelection()) return;\n    e.clipboardData?.setData('text/plain', cached);\n    e.preventDefault();\n  };\n\n  const onKeyDown = (e: KeyboardEvent): void => {\n    if (!(e.metaKey || e.ctrlKey) || e.key.toLowerCase() !== 'c' || e.shiftKey || e.altKey) {\n      return;\n    }\n    if (!selection.hasSelection() || !selection.canCopy()) return;\n    // A live DOM selection means the browser will dispatch `copy` itself and\n    // our synchronous handler answers — don't double-write.\n    const dom = target.getSelection?.();\n    if (dom && !dom.isCollapsed) return;\n    void copySelection(selection); // instant when prefetched; still inside user activation\n  };\n\n  target.addEventListener('copy', onCopy);\n  target.addEventListener('keydown', onKeyDown);\n  return () => {\n    offCommit();\n    offChange();\n    if (timer) clearTimeout(timer);\n    target.removeEventListener('copy', onCopy);\n    target.removeEventListener('keydown', onKeyDown);\n  };\n}\n\n/**\n * Toolbar/menu path: read the selected text and write it to the clipboard\n * via the async Clipboard API. Call from a user-gesture handler (browsers\n * require a secure context + user activation for clipboard writes). Resolves\n * with what was copied ('' when nothing was — nothing is written then, so an\n * empty selection never clobbers the user's clipboard).\n */\nexport async function copySelection(selection: ClipboardSelectionSource): Promise<string> {\n  const text = await selection.readText();\n  if (text !== '') await navigator.clipboard.writeText(text);\n  return text;\n}\n","/**\n * Anchored-overlay geometry for UI floating over page content (selection\n * menus, draft menus, popovers): the projector SNAPSHOT contract, the\n * anchor shape, and the placement math. Pure values and pure functions over\n * structural rect/point shapes — no EmbedPDF types, no framework, no\n * reactive lifecycle — so every framework adapter (React, Vue, Svelte,\n * Angular) shares ONE implementation and binds it with its NATIVE\n * reactivity (context revision, signals, computed, $derived).\n *\n * The boundary laws:\n *   - Placement policy lives HERE, above the projector seam: a projector\n *     only knows geometry — never what is being positioned nor where it\n *     prefers to sit.\n *   - A projector describes the CURRENT projection; it never implements a\n *     framework-style reactive lifecycle. State-driven changes (the Stage\n *     camera) must reach consumers through the framework's own render\n *     cycle so surface and overlay commit TOGETHER; only genuinely\n *     browser-driven changes (a PageView moving because the document\n *     scrolled) use an external listener ({@link observeClientGeometry}).\n */\n\nexport interface AnchoredRect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface AnchoredPoint {\n  x: number;\n  y: number;\n}\n\nexport type AnchoredPlacement = 'top' | 'right' | 'bottom' | 'left';\n\n/** CSS-ready output: absolute/fixed `left`/`top` plus a centering transform. */\nexport interface AnchoredPosition {\n  left: number;\n  top: number;\n  transform: string;\n}\n\n/**\n * Place an upright element around `box` (screen px). `avoid` is a screen\n * point the element must clear (e.g. the rotate knob): the element extends\n * ONLY the edge it sits on, and ONLY when the point protrudes past that\n * edge — so it clears the obstacle without ever shifting off-centre on the\n * other axis. When the point is on another side (e.g. a 90° shape, knob at\n * mid-height for a `top` placement) the edge is untouched and the element\n * stays centred on `box`.\n */\n/** What anchored UI attaches to: a content-space rect on a page, plus\n *  optional content-space points the UI must clear (e.g. a rotate knob).\n *  Structural — plugin anchor reads satisfy it without importing this\n *  package. */\nexport interface AnchorTarget {\n  pon: number;\n  bounds: AnchoredRect;\n  avoid?: AnchoredPoint[];\n}\n\n/**\n * A page surface's PROJECTION SNAPSHOT: how a content-space rect on a page\n * becomes screen coordinates, right now. Provided by `<Stage>`\n * (camera-driven, pure state, no DOM reads) and `<PageView>` (DOM-measured).\n * Deliberately NO subscribe here — when projection changes is a framework\n * binding concern (see the module doc), not part of the snapshot.\n */\nexport interface ViewProjector {\n  /**\n   * Which coordinate space `toScreen` speaks, and therefore how anchored\n   * content mounts:\n   *   - 'overlay': coords are relative to the surface's own positioned\n   *     container → rendered in place, position:absolute. (Stage)\n   *   - 'client': coords are viewport px → portalled to the document body,\n   *     position:fixed, so no ancestor overflow can clip. (PageView)\n   */\n  space: 'overlay' | 'client';\n  /** Content-space rect on a page → coords in `space`. Null: not projectable\n   *  right now (page not shown / not measurable yet). */\n  toScreen(pon: number, rect: AnchoredRect): AnchoredRect | null;\n  toScreenPoint(pon: number, at: AnchoredPoint): AnchoredPoint | null;\n  /** The page's live view facts (for anchor reads that need them — e.g. the\n   *  screen-constant rotate-knob stalk), or null when the page isn't shown. */\n  viewEnv(pon: number): {\n    scale: number;\n    rotation: 0 | 90 | 180 | 270;\n    zoom: number;\n  } | null;\n}\n\n/**\n * THE anchored projection: anchor → screen position, in one pure call —\n * projection, avoid-point transform, and the shared placement policy.\n * Frameworks recompute this inside their native reactive primitive\n * (a React render, a Vue `computed`, an Angular signal, a Svelte\n * `$derived`); nothing here schedules anything.\n */\nexport function projectAnchoredTarget(\n  projector: ViewProjector,\n  anchor: AnchorTarget,\n  placement: AnchoredPlacement,\n  gap: number,\n): AnchoredPosition | null {\n  const box = projector.toScreen(anchor.pon, anchor.bounds);\n  if (!box) return null;\n  const avoid = anchor.avoid?.length\n    ? projector.toScreenPoint(anchor.pon, anchor.avoid[0])\n    : null;\n  return positionAnchoredRect(box, placement, gap, avoid);\n}\n\n/**\n * The one genuinely BROWSER-driven invalidation: an element in normal\n * document flow moves when the document scrolls or the window resizes —\n * no state change announces it. `<PageView>`'s binding registers this;\n * the Stage never does (its camera is state, delivered through render).\n */\nexport function observeClientGeometry(callback: () => void): () => void {\n  window.addEventListener('scroll', callback, true);\n  window.addEventListener('resize', callback);\n  return () => {\n    window.removeEventListener('scroll', callback, true);\n    window.removeEventListener('resize', callback);\n  };\n}\n\nexport function positionAnchoredRect(\n  box: AnchoredRect,\n  placement: AnchoredPlacement,\n  gap: number,\n  avoid?: AnchoredPoint | null,\n): AnchoredPosition {\n  const cx = box.x + box.width / 2;\n  const cy = box.y + box.height / 2;\n\n  switch (placement) {\n    case 'bottom': {\n      const edge = Math.max(box.y + box.height, avoid ? avoid.y : -Infinity);\n      return { left: cx, top: edge + gap, transform: 'translate(-50%, 0)' };\n    }\n    case 'left': {\n      const edge = Math.min(box.x, avoid ? avoid.x : Infinity);\n      return { left: edge - gap, top: cy, transform: 'translate(-100%, -50%)' };\n    }\n    case 'right': {\n      const edge = Math.max(box.x + box.width, avoid ? avoid.x : -Infinity);\n      return { left: edge + gap, top: cy, transform: 'translate(0, -50%)' };\n    }\n    case 'top':\n    default: {\n      const edge = Math.min(box.y, avoid ? avoid.y : Infinity);\n      return { left: cx, top: edge - gap, transform: 'translate(-50%, -100%)' };\n    }\n  }\n}\n","/**\n * SVG → CSS cursor string. The armed-tool indicator is the CURSOR itself (the\n * only zero-latency pointer-locked pixel the web has — the OS composites it),\n * so an app hands its toolbar icon here and assigns the result via the\n * interaction hub's `setToolCursor`.\n *\n * Browser rules baked into this module:\n *   - The SVG must carry explicit `width`/`height` attributes (not just a\n *     viewBox) or Chromium/WebKit ignore it — enforced here.\n *   - The hard ceiling is 128×128 CSS px (bigger falls back to the keyword).\n *     Above 32×32, Chromium temporarily resets the cursor to default while it\n *     would overlap browser UI (anti-spoofing) — fine mid-viewport, so ~40px\n *     compositions are common; stay ≤128.\n *   - The keyword fallback covers browsers that refuse SVG cursor images.\n *\n * Pure string work with no EmbedPDF types — like the file picker, this module\n * is a plain web utility.\n */\n\nexport interface SvgCursorOptions {\n  /** Complete `<svg>` markup, colors baked in (no `currentColor` — a cursor\n   *  image has no cascade to inherit from). */\n  svg: string;\n  /** The click point inside the image, CSS px from the top-left. Default 0,0\n   *  (arrow-style: the image's corner is the tip). */\n  hotspot?: { x: number; y: number };\n  /** Keyword cursor when the image can't render. Default `'crosshair'`. */\n  fallback?: string;\n}\n\n/** Build the CSS cursor value: `url(\"data:image/svg+xml,…\") x y, fallback`. */\nexport function svgCursor({ svg, hotspot, fallback = 'crosshair' }: SvgCursorOptions): string {\n  // Scan only the opening `<svg …>` tag (bounded slice) rather than running\n  // `/<svg[^>]*\\swidth\\s*=/` over the whole string — the unbounded form is\n  // quadratic on pathological inputs (many `<svg` fragments with no `>`),\n  // while accepting exactly the same markup: `[^>]*` could never cross a\n  // `>` either.\n  const tagStart = svg.indexOf('<svg');\n  const tagEnd = tagStart >= 0 ? svg.indexOf('>', tagStart) : -1;\n  const openTag = tagEnd >= 0 ? svg.slice(tagStart, tagEnd + 1) : '';\n  if (!/\\swidth\\s*=/.test(openTag) || !/\\sheight\\s*=/.test(openTag)) {\n    throw new Error(\n      '[web] svgCursor: the <svg> needs explicit width/height attributes — ' +\n        'browsers ignore cursor images without an intrinsic size',\n    );\n  }\n  const uri = `data:image/svg+xml,${encodeURIComponent(svg)}`;\n  const spot = hotspot ? ` ${Math.round(hotspot.x)} ${Math.round(hotspot.y)}` : '';\n  return `url(\"${uri}\")${spot}, ${fallback}`;\n}\n","/**\n * External-URI hygiene for PDF link annotations — written ONCE here so every\n * framework adapter (react, vue, svelte, angular) shares the same policy.\n *\n * PDFs are untrusted input: a link's `/URI` can carry anything, including\n * `javascript:` payloads. The default allowlist covers what a document link\n * legitimately opens; everything else (javascript:, file:, data:, vbscript:,\n * custom app schemes) resolves to `null` and the adapters render the link\n * WITHOUT an href — activation still reports through the plugin, so an\n * embedder that needs a custom scheme can handle it in `onActivate`.\n */\nconst DEFAULT_ALLOWED_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:']);\n\n/**\n * Validate a link URI for opening in the browser. Returns the URI when its\n * scheme is allowed (scheme-relative and bare URIs resolve as https), else\n * `null`. Never throws — a malformed URI is just an unopenable one.\n */\nexport function sanitizeExternalUri(\n  uri: string,\n  allowedSchemes: Iterable<string> = DEFAULT_ALLOWED_SCHEMES,\n): string | null {\n  const trimmed = uri.trim();\n  if (!trimmed) return null;\n  const allowed = new Set(\n    [...allowedSchemes].map((s) => (s.endsWith(':') ? s.toLowerCase() : `${s.toLowerCase()}:`)),\n  );\n  try {\n    // Base resolves scheme-relative (\"//host\") and bare (\"example.com/x\" is a\n    // relative path → https) forms; an absolute scheme wins over the base.\n    const url = new URL(trimmed, 'https://invalid.example/');\n    return allowed.has(url.protocol) ? trimmed : null;\n  } catch {\n    return null;\n  }\n}\n","/** A browser image source whose object URL has an explicit lifetime. */\nexport interface ObjectUrlImageSource {\n  objectUrl(signal?: AbortSignal): Promise<{ url: string; revoke(): void }>;\n}\n\nexport interface PaintedImageCallbacks {\n  onPainted(): void;\n  onUnpainted(): void;\n}\n\n/**\n * Bind a raster source to an <img> without ever painting its incomplete-image\n * placeholder. The source becomes visible on load; retained coverage is\n * released only after the browser has had one full frame to present it.\n *\n * Call this from the framework's pre-paint mount hook and invoke the returned\n * cleanup on unmount. Keeping this DOM lifecycle here lets every framework\n * adapter remain a ref plus one bind/unbind hook.\n */\nexport function bindPaintedImage(\n  image: HTMLImageElement,\n  source: ObjectUrlImageSource,\n  callbacks: PaintedImageCallbacks,\n): () => void {\n  const controller = new AbortController();\n  let revoke: (() => void) | undefined;\n  let frame = 0;\n  let painted = false;\n\n  // The element is already committed when a mount hook runs. Hide it before\n  // that commit can paint, then reveal only once the bitmap has loaded.\n  image.style.visibility = 'hidden';\n\n  const onLoad = () => {\n    image.style.visibility = 'visible';\n\n    // rAF callbacks run before a frame paints. The first frame presents the\n    // newly visible image while retained coverage remains; the second reports\n    // that presentation opportunity and permits the retained source to leave.\n    frame = requestAnimationFrame(() => {\n      frame = requestAnimationFrame(() => {\n        frame = 0;\n        painted = true;\n        callbacks.onPainted();\n      });\n    });\n  };\n\n  image.addEventListener('load', onLoad, { once: true });\n\n  void source.objectUrl(controller.signal).then(\n    (objectUrl) => {\n      if (controller.signal.aborted) {\n        objectUrl.revoke();\n        return;\n      }\n      revoke = objectUrl.revoke;\n      image.src = objectUrl.url;\n    },\n    () => {\n      // Aborted or unavailable: remain hidden and retain fallback coverage.\n    },\n  );\n\n  return () => {\n    controller.abort();\n    if (frame) cancelAnimationFrame(frame);\n    image.removeEventListener('load', onLoad);\n    image.style.visibility = 'hidden';\n    image.removeAttribute('src');\n    revoke?.();\n    if (painted) callbacks.onUnpainted();\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/web",
-  "version": "3.0.0-next.4",
+  "version": "3.0.0-next.6",
   "private": false,
   "description": "Framework-free browser adapters for EmbedPDF v3 — the one home for code that touches window/document (file dialog, clipboard, print…). Imported by the framework layers; never by a plugin or a *-core package, which stay DOM-free.",
   "type": "module",