yamlover 0.3.0 → 0.3.2

package/dist/server.js

@@ -2345,6 +2345,25 @@ async function walkTreeAsync(absDir, opts = {}) {
   }
   return r.value;
 }
+var BUILTIN_TAG_SCHEMA = "type: object\nformat: x-yamlover-tag\nproperties:\n  color:\n    type: string\nadditionalProperties: *:: yamlover: $defs: tag\n";
+var BUILTIN_TAGS_BODY = '!!<*yamlover:$defs:tag>\ncolors: The palette\n  yellow:\n    color: "#f9e2af"\n  green:\n    color: "#a6e3a1"\n  sky:\n    color: "#89dceb"\n  mauve:\n    color: "#cba6f7"\n  pink:\n    color: "#f5c2e7"\n  peach:\n    color: "#fab387"\n';
+var builtinTemplate = null;
+function builtinYamloverGraft() {
+  builtinTemplate ??= {
+    tag: parseYamlover(BUILTIN_TAG_SCHEMA, "$defs/tag").root,
+    tags: parseYamlover(BUILTIN_TAGS_BODY, "tags/.yamlover/body.yamlover").root
+  };
+  const tagCopy = structuredClone(builtinTemplate.tag);
+  const node = {
+    kind: "mapping",
+    array: false,
+    entries: [
+      { key: "$defs", edge: "contain", value: { kind: "mapping", array: false, entries: [{ key: "tag", edge: "contain", value: tagCopy }] } },
+      { key: "tags", edge: "contain", value: structuredClone(builtinTemplate.tags) }
+    ]
+  };
+  return { node, defs: /* @__PURE__ */ new Map([["tag", tagCopy]]) };
+}
 function* walkTreeGen(absDir, opts = {}) {
   const ctx = { root: path.resolve(absDir), opts, files: /* @__PURE__ */ new Map(), count: 0 };
   const root = yield* dirNode(ctx.root, ctx);
@@ -2352,13 +2371,20 @@ function* walkTreeGen(absDir, opts = {}) {
   const defsRoot = findDefsRoot(absDir);
   const defsDir = path.join(defsRoot, "$defs");
   const arrayRoot = root.array || (root.entries?.length ? root.entries.every((e2) => e2.key === null) : false);
-  if (!arrayRoot && fs.existsSync(defsDir) && root.entries && !root.entries.some((e2) => e2.key === "yamlover")) {
-    const shared = [{ key: "$defs", edge: "contain", value: yield* dirNode(defsDir, ctx) }];
-    const tagsDir = path.join(defsRoot, "tags");
-    if (fs.existsSync(tagsDir)) shared.push({ key: "tags", edge: "contain", value: yield* dirNode(tagsDir, ctx) });
-    root.entries.push({ key: "yamlover", edge: "contain", value: { kind: "mapping", entries: shared, array: false } });
+  let builtinDefs;
+  if (!arrayRoot && root.entries && !root.entries.some((e2) => e2.key === "yamlover")) {
+    if (fs.existsSync(defsDir)) {
+      const shared = [{ key: "$defs", edge: "contain", value: yield* dirNode(defsDir, ctx) }];
+      const tagsDir = path.join(defsRoot, "tags");
+      if (fs.existsSync(tagsDir)) shared.push({ key: "tags", edge: "contain", value: yield* dirNode(tagsDir, ctx) });
+      root.entries.push({ key: "yamlover", edge: "contain", value: { kind: "mapping", entries: shared, array: false } });
+    } else {
+      const built = builtinYamloverGraft();
+      root.entries.push({ key: "yamlover", edge: "contain", value: built.node });
+      builtinDefs = built.defs;
+    }
   }
-  applySchemas(root, defsRoot);
+  applySchemas(root, defsRoot, builtinDefs);
   return {
     doc: { root, source: { concrete: "directory", uri: absDir } },
     files: [...ctx.files.values()]
@@ -2572,7 +2598,7 @@ function findDefsRoot(dir) {
     d = up;
   }
 }
-function applySchemas(root, defsRoot) {
+function applySchemas(root, defsRoot, builtinDefs) {
   const cache = /* @__PURE__ */ new Map();
   const loadDef = (name) => {
     if (!cache.has(name)) {
@@ -2580,7 +2606,7 @@ function applySchemas(root, defsRoot) {
       try {
         cache.set(name, parseYamlover(fs.readFileSync(defFile, "utf8"), defFile).root);
       } catch {
-        cache.set(name, null);
+        cache.set(name, builtinDefs?.get(name) ?? null);
       }
     }
     return cache.get(name);

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "yamlover",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Browse a yamlover tree in the web: npx yamlover <root> serves a React SPA over a directory.",
   "type": "module",
   "license": "MIT",
   "author": "dims",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dims12/yamlover.git",
+    "directory": "tools/server"
+  },
   "keywords": [
     "yamlover",
     "yaml",

package/src/client/App.tsx

@@ -324,7 +324,7 @@ export function App() {
         <nav className="crumbs">
           {crumbs(current, rootLabel).map((c, i) => (
             <span key={c.path}>
-              {i > 0 && <span className="crumb-sep">:</span>}
+              {i > 0 && <span className="crumb-sep">/</span>}
               <a
                 className="crumb"
                 href={c.path}

package/src/client/paths.ts

@@ -25,6 +25,14 @@ export function strToSegs(str: string): Seg[] {
   return out;
 }
 
+/** Canonical key for cross-SCOPE comparison: collapse the colon scope ladder so a
+ *  project ref (`::yamlover:…`), a document ref (`:yamlover:…`), and a server-echoed
+ *  `:`-form path all compare equal. The ladder colons are not tokens (PATH_TOKEN), so
+ *  re-emitting drops them; keys are normalized through one decode→encode pass. */
+export function canonPath(p: string): string {
+  return segsToStr(strToSegs(p));
+}
+
 function safeDecode(s: string): string {
   try {
     return decodeURIComponent(s);
@@ -79,6 +87,25 @@ export function formatFromUrl(fallback: string): string {
   return new URLSearchParams(window.location.search).get("format") || fallback;
 }
 
+/** The current page from the URL's `?page=` (1-based). 1 when absent, ≤1, or not an integer —
+ *  used by paged viewers (PDF/DjVu) to restore where the reader left off. */
+export function pageFromUrl(): number {
+  const n = Number(new URLSearchParams(window.location.search).get("page"));
+  return Number.isInteger(n) && n > 1 ? n : 1;
+}
+
+/** Record the current page in `?page=` via replaceState — preserving every other param, and
+ *  DROPPING the param at page 1 (the implicit default). This does NOT remount the renderer (only
+ *  path/format/refreshSignal do), so a paged viewer can update it freely while scrolling. */
+export function writePageToUrl(n: number): void {
+  const params = new URLSearchParams(window.location.search);
+  if (n > 1) params.set("page", String(n));
+  else params.delete("page");
+  const qs = params.toString();
+  const url = window.location.pathname + (qs ? "?" + qs : "");
+  if (url !== window.location.pathname + window.location.search) window.history.replaceState({}, "", url);
+}
+
 /** Write the JSON path (canonical colon form, converted to the slash-transport URL)
  *  plus `?format=` into the URL. Path navigation pushes a history entry; switching
  *  format replaces. Any other query params already present are kept (e.g. a renderer's
@@ -86,6 +113,9 @@ export function formatFromUrl(fallback: string): string {
 export function writeUrl(path: string, format: string, replace = false): void {
   const params = new URLSearchParams(window.location.search);
   params.set("format", format);
+  // `?page=` is node-specific: a format switch (replace) keeps it, but navigating to another node
+  // (push) must not carry the old node's page over — drop it there.
+  if (!replace) params.delete("page");
   const url = `${urlOfPath(path || ":")}?${params.toString()}`;
   if (url === window.location.pathname + window.location.search) return;
   if (replace) window.history.replaceState({}, "", url);

package/src/client/renderers/annotate.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState, type ReactNode } from "react";
 import { Annotation, TagRef, createTag, fetchAnnotations, fetchNode, saveAnnotation, deleteAnnotation } from "../api";
 import { TAG_FORMAT, explicitColor, resolveTagColor, tagFields } from "./tag";
-import { strToSegs } from "../paths";
+import { canonPath, strToSegs } from "../paths";
 import { touchesYamlover, useDiffBump } from "../live";
 
 /**
@@ -30,12 +30,12 @@ import { touchesYamlover, useDiffBump } from "../live";
 // fetches the real `/yamlover/tags/colors` nodes once per session (useColorTags) so a project
 // that re-themes them wins; the paths and hexes here mirror yamlover/tags/.yamlover/body.yamlover.
 export const COLOR_TAGS: TagRef[] = [
-  { path: ":yamlover:tags:colors:yellow", name: "yellow", color: "#f9e2af" },
-  { path: ":yamlover:tags:colors:green", name: "green", color: "#a6e3a1" },
-  { path: ":yamlover:tags:colors:sky", name: "sky", color: "#89dceb" },
-  { path: ":yamlover:tags:colors:mauve", name: "mauve", color: "#cba6f7" },
-  { path: ":yamlover:tags:colors:pink", name: "pink", color: "#f5c2e7" },
-  { path: ":yamlover:tags:colors:peach", name: "peach", color: "#fab387" },
+  { path: "::yamlover:tags:colors:yellow", name: "yellow", color: "#f9e2af" },
+  { path: "::yamlover:tags:colors:green", name: "green", color: "#a6e3a1" },
+  { path: "::yamlover:tags:colors:sky", name: "sky", color: "#89dceb" },
+  { path: "::yamlover:tags:colors:mauve", name: "mauve", color: "#cba6f7" },
+  { path: "::yamlover:tags:colors:pink", name: "pink", color: "#f5c2e7" },
+  { path: "::yamlover:tags:colors:peach", name: "peach", color: "#fab387" },
 ];
 export const DEFAULT_TAG = COLOR_TAGS[0];
 export const DEFAULT_COLOR = DEFAULT_TAG.color!;
@@ -68,12 +68,15 @@ let colorTagsPromise: Promise<TagRef[]> | null = null;
 export function useColorTags(): TagRef[] {
   const [tags, setTags] = useState<TagRef[]>(COLOR_TAGS);
   useEffect(() => {
-    colorTagsPromise ??= fetchNode(":yamlover:tags:colors", 2)
+    colorTagsPromise ??= fetchNode("::yamlover:tags:colors", 2)
       .then((n) => {
         const out: TagRef[] = [];
         for (const [name, child] of tagFields(n.value)) {
           const color = explicitColor(child);
-          if (color) out.push({ path: `${n.path}/${encodeURIComponent(name)}`, name, color });
+          // PROJECT-scope ref pinned to `::yamlover:tags:colors:<name>` — NOT derived from
+          // `n.path` (the API echoes that in `:`-form, which would mismatch COLOR_TAGS and
+          // resurrect the ghost badge); and `:` not `/` (the pre-SEPARATOR separator bug).
+          if (color) out.push({ path: `::yamlover:tags:colors:${encodeURIComponent(name)}`, name, color });
         }
         return out.length ? out : COLOR_TAGS;
       })
@@ -113,7 +116,7 @@ export function recentTags(): TagRef[] {
 }
 
 function rememberRecent(t: TagRef): void {
-  if (t.path.startsWith(":yamlover:tags:colors:")) return; // the swatch row already shows these
+  if (canonPath(t.path).startsWith(":yamlover:tags:colors:")) return; // the swatch row already shows these
   const next = [t, ...recentTags().filter((r) => r.path !== t.path)].slice(0, 6);
   localStorage.setItem(RECENT_KEY, JSON.stringify(next));
 }
@@ -165,7 +168,7 @@ export function useAnnotations(path: string, bump = 0): Annotation[] {
  *  round-trip lands. */
 export interface MaterialAnnotations {
   annotations: Annotation[];
-  create: (selector: Record<string, unknown> | null, tag: TagRef) => void;
+  create: (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean }) => void;
   remove: (annPath?: string) => void;
   retag: (ann: Annotation, tag: TagRef) => void;
 }
@@ -189,12 +192,18 @@ export function useMaterialAnnotations(path: string): MaterialAnnotations {
   }, [fetched]);
 
   const refresh = () => setBump((b) => b + 1);
-  const create = (selector: Record<string, unknown> | null, tag: TagRef) => {
+  const create = (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean }) => {
     const entry = { path: "(pending)", selector: selector ?? undefined, tag } as Annotation;
     setOptimistic((o) => [...o, entry]);
     createAnnotation(path, selector, tag)
       .then(refresh)
-      .catch((e) => { setOptimistic((o) => o.filter((x) => x !== entry)); window.alert("save failed: " + (e as Error).message); }); // roll back the unsaved mark
+      .catch((e) => {
+        setOptimistic((o) => o.filter((x) => x !== entry)); // roll back the unsaved mark
+        // An IMPLICIT save (clicking away with the pre-selected tag) is best-effort — e.g. the
+        // default tag may not exist in this tree — so it rolls back QUIETLY. Only an explicit
+        // pick (a swatch/badge/✓) reports the failure.
+        if (!opts?.silent) window.alert("save failed: " + (e as Error).message);
+      });
   };
   const remove = (annPath?: string) => {
     if (!annPath || annPath === "(pending)") return;
@@ -228,7 +237,7 @@ function tagNameOf(path: string): string {
 
 /** The floating tag picker — color-tag swatches, recent named-tag badges, a tag-path input, plus
  *  action buttons. Mode decides which buttons show (the hook wires what each does): `create` gets
- *  ✓ confirm + optional ⧉ copy + 🗑 discard; `edit` gets just 🗑 delete (picking a tag re-tags).
+ *  ✓ confirm + optional ⧉ copy + 🗑 discard; `edit` gets ✓ close + 🗑 delete (picking a tag re-tags).
  *  `position: fixed`, so x/y are viewport coords. */
 export function AnnotationMenu({
   x, y, tag, mode, onPick, onConfirm, onCopy, onTrash, menuRef,
@@ -251,10 +260,14 @@ export function AnnotationMenu({
     return () => { on = false; };
   }, []);
 
+  // Compare tag paths on a CANONICAL key — a palette ref is project-scope (`::yamlover:…`)
+  // while a selected/edited tag may arrive `:`-form (the API echoes paths in `:`-form, and
+  // older localStorage holds `:`-form); raw `===` would miss the match and duplicate the tag.
+  const same = (a: string, b: string) => canonPath(a) === canonPath(b);
   // The badge row must always include THE tag this menu is about (`sel`-framed, like the
   // selected color swatch) — which tag is assigned/pre-selected must be visible at a glance,
-  // even when it has aged out of the recents.
-  const badges = colorTags.some((c) => c.path === tag.path) || recents.some((r) => r.path === tag.path)
+  // even when it has aged out of the recents. A PALETTE tag is shown as a swatch, not a badge.
+  const badges = colorTags.some((c) => same(c.path, tag.path)) || recents.some((r) => same(r.path, tag.path))
     ? recents
     : [tag, ...recents];
 
@@ -288,14 +301,14 @@ export function AnnotationMenu({
           <button
             key={t.path}
             type="button"
-            className={"annotate-swatch" + (t.path === tag.path ? " sel" : "")}
+            className={"annotate-swatch" + (same(t.path, tag.path) ? " sel" : "")}
             style={{ background: resolveTagColor(t) }}
             title={`${verb} ${t.name}`}
             onClick={() => onPick(t)}
           />
         ))}
       </div>
-      {onConfirm && <button type="button" className="annotate-tool ok" title={`${verb} ${tag.name} (keep the mark)`} onClick={onConfirm}>✓</button>}
+      {onConfirm && <button type="button" className="annotate-tool ok" title={mode === "edit" ? "close (keep this annotation)" : `${verb} ${tag.name} (keep the mark)`} onClick={onConfirm}>✓</button>}
       {onCopy && <button type="button" className="annotate-tool" title="copy text to clipboard (don't annotate)" onClick={onCopy}>⧉</button>}
       <button type="button" className="annotate-tool danger" title={mode === "edit" ? "delete this annotation" : "discard (don't annotate)"} onClick={onTrash}>🗑</button>
       {badges.length > 0 && (
@@ -303,7 +316,7 @@ export function AnnotationMenu({
           {badges.map((t) => (
             // the frame is a WRAPPER: filter applies before clip-path on the same element, so a
             // ring drawn on the clipped .tagtag itself would be clipped away with it (styles.css)
-            <span key={t.path} className={"tagframe" + (t.path === tag.path ? " sel" : "")}>
+            <span key={t.path} className={"tagframe" + (same(t.path, tag.path) ? " sel" : "")}>
               <button
                 type="button"
                 className="tagtag"
@@ -355,7 +368,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
   const openEdit = (ann: Annotation, screen: { x: number; y: number }) =>
     setMenu({ mode: "edit", ann, x: screen.x, y: screen.y });
 
-  const commitCreate = (t: TagRef, m: MenuState) => { if (m.mode !== "create") return; setTag(t); a.create(m.selector, t); close(); };
+  const commitCreate = (t: TagRef, m: MenuState, silent = false) => { if (m.mode !== "create") return; setTag(t); a.create(m.selector, t, { silent }); close(); };
   const commitRetag = (t: TagRef, m: MenuState) => { if (m.mode !== "edit") return; setTag(t); a.retag(m.ann, t); close(); };
 
   // Outside-click: a create commits with the pre-selected tag (default keeps the mark); an edit closes.
@@ -363,7 +376,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
     if (!menu) return;
     const onDown = (e: MouseEvent) => {
       if (menuRef.current?.contains(e.target as Node)) return;
-      if (menu.mode === "create") commitCreate(tag, menu);
+      if (menu.mode === "create") commitCreate(tag, menu, true); // implicit → best-effort, no error popup
       else close();
     };
     document.addEventListener("mousedown", onDown);
@@ -387,6 +400,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
       <AnnotationMenu
         menuRef={menuRef} x={menu.x} y={menu.y} tag={menu.ann.tag ?? DEFAULT_TAG} mode="edit"
         onPick={(t) => commitRetag(t, menu)}
+        onConfirm={close} // ✓ closes the popup without deleting or re-tagging
         onTrash={() => { a.remove(menu.ann.path); close(); }}
       />
     );

package/src/client/renderers/djvu.tsx

@@ -1,97 +1,264 @@
-import { useEffect, useRef, useState } from "react";
-import { NodeJson, blobUrl } from "../api";
-// The DjVu.js library (GPL-v2), vendored as a prebuilt IIFE bundle. Loaded as a
-// classic <script> so its `var DjVu = (…)()` lands on the global scope; see
-// vendor/README.md for provenance and license.
-import djvuScriptUrl from "../vendor/djvu.js?url";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Annotation, NodeJson, blobUrl } from "../api";
+import { DEFAULT_COLOR, colorOf, editable, useAnnotationMenu, useMaterialAnnotations } from "./annotate";
+import { usePagedScroll } from "./paged";
+import { DecodedPage, decodeDjvuPage, openDjvu } from "./djvuWorker";
 
-declare global {
-  interface Window {
-    DjVu?: any;
-  }
-}
+const num = (v: unknown): number => Number(v) || 0;
+/** A rectangular annotation region on a DjVu page, in the page's NATIVE pixels (like the OCR zones),
+ *  so it's zoom-independent. `ann` is the saved annotation (→ clickable to edit). */
+interface DjvuRegion { page: number; x: number; y: number; w: number; h: number; title?: string; color?: string; ann?: Annotation }
 
-let loading: Promise<any> | null = null;
-/** Inject the vendored bundle once; resolve with the global `DjVu` namespace. */
-function loadDjVu(): Promise<any> {
-  if (window.DjVu) return Promise.resolve(window.DjVu);
-  if (!loading) {
-    loading = new Promise((resolve, reject) => {
-      const s = document.createElement("script");
-      s.src = djvuScriptUrl;
-      s.onload = () => (window.DjVu ? resolve(window.DjVu) : reject(new Error("DjVu failed to load")));
-      s.onerror = () => reject(new Error("could not load djvu.js"));
-      document.head.appendChild(s);
-    });
-  }
-  return loading;
+/** Paints worker-decoded DjVu pixels into a <canvas> at native size (CSS-scaled to the display
+ *  width by the wrapper). putImageData is cheap; no PNG encode and no main-thread decompression. */
+function DjvuCanvas({ image }: { image: ImageData }) {
+  const ref = useRef<HTMLCanvasElement>(null);
+  useLayoutEffect(() => {
+    const c = ref.current;
+    if (!c) return;
+    c.width = image.width;
+    c.height = image.height;
+    c.getContext("2d")?.putImageData(image, 0, 0);
+  }, [image]);
+  return <canvas className="djvu-page" ref={ref} />;
 }
 
 /**
- * Renders an `image/vnd.djvu` document. The browser has no native DjVu support,
- * so we decode it client-side with DjVu.js: fetch the bytes from `/api/blob`,
- * build a `DjVu.Document`, and render each page to a PNG object-URL shown as an
- * `<img>` (cheaper than holding every page as a full-resolution canvas). A plain
- * wheel scrolls the document; ctrl/alt-wheel zooms (scales the page width), matching
- * the image/map/pdf viewers (see the UI guide).
+ * Renders an `image/vnd.djvu` document. DjVu.js decodes pages in a Web Worker (djvuWorker.ts), and
+ * only the pages NEAR the viewport decode (windowed, like the PDF viewer) — so a long scan opens
+ * fast and the main thread stays free to annotate while pages decode. Each decoded page is a
+ * <canvas> (the worker returns ImageData). An OCR text layer (when present) makes text selectable →
+ * a region annotation; pages without OCR get a drag-marquee instead. ctrl/alt-wheel zooms (a CSS
+ * resize — no re-decode), with the reading position anchored across zoom; `?page=` tracks the page.
  */
 export function DjvuView({ node }: { node: NodeJson }) {
   const ref = useRef<HTMLDivElement>(null);
-  const [pages, setPages] = useState<string[]>([]);
   const [count, setCount] = useState(0);
   const [zoom, setZoom] = useState(1);
+  const [width, setWidth] = useState(0); // pane width (so a page caps at ~1000px like PDF, not full pane)
   const [error, setError] = useState<string | null>(null);
+  const [drag, setDrag] = useState<{ page: number; x0: number; y0: number; x1: number; y1: number } | null>(null);
+  const [near, setNear] = useState<Set<number>>(() => new Set()); // pages near the viewport
+  const [decoded, setDecoded] = useState<Map<number, DecodedPage>>(() => new Map()); // near pages' pixels+zones
+  const sizes = useRef(new Map<number, { w: number; h: number }>()); // remembered native sizes → stable placeholders
+
+  // Annotations: a `djvu` rect region (page + native-pixel box) from a text selection on an OCR
+  // page, or a drag-marquee on a page with no OCR. Same picker/flow as image & PDF.
+  const material = useMaterialAnnotations(node.path);
+  const { openCreate, openEdit, palette, preview } = useAnnotationMenu(material);
+  const shown = preview
+    ? [...material.annotations, { path: "(preview)", selector: preview.selector, tag: preview.tag } as Annotation]
+    : material.annotations;
+  const regions: DjvuRegion[] = shown
+    .filter((a) => a.selector?.type === "djvu")
+    .map((a) => ({ page: num(a.selector!.page) || 1, x: num(a.selector!.x), y: num(a.selector!.y), w: num(a.selector!.w), h: num(a.selector!.h), title: a.description, color: colorOf(a), ann: editable(a) ? a : undefined }));
+  const previewColor = preview?.color ?? DEFAULT_COLOR;
+
+  // WINDOWED RENDERING: every page keeps a `.djvu-page-wrap` (so the scroll height is right), but
+  // only near pages decode + mount a canvas; far pages are estimated-height placeholders.
+  const wraps = useRef(new Map<number, HTMLElement>());
+  const getPageEls = () => {
+    const out: HTMLElement[] = [];
+    for (let i = 1; i <= count; i++) { const el = wraps.current.get(i); if (el) out.push(el); }
+    return out;
+  };
+  const paged = usePagedScroll(ref, getPageEls, count > 0 && width > 0);
+  const pagedRef = useRef(paged);
+  pagedRef.current = paged;
+  useLayoutEffect(() => { paged.restoreAnchor(); }, [zoom]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Track the pane width so a page fits but is capped (≤1000px) like the PDF viewer.
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const ro = new ResizeObserver(([e]) => setWidth(e.contentRect.width));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  const dispW = Math.min(width, 1000) * zoom; // each page's displayed width in px
 
-  // ctrl/alt-wheel zooms; a plain wheel is left alone so the pane keeps scrolling.
+  // ctrl/alt-wheel zooms; a plain wheel scrolls. Zoom is a CSS resize (no re-decode), applied live;
+  // the reading position is anchored at the burst start and restored after each step.
   useEffect(() => {
     const el = ref.current;
     if (!el) return;
+    let bursting = false;
+    let end = 0;
     const onWheel = (e: WheelEvent) => {
       if (!(e.ctrlKey || e.altKey || e.metaKey)) return;
       e.preventDefault();
+      if (!bursting) { pagedRef.current.captureAnchor(); bursting = true; }
+      clearTimeout(end);
+      end = window.setTimeout(() => (bursting = false), 250);
       setZoom((z) => Math.min(5, Math.max(0.4, z * (e.deltaY < 0 ? 1.1 : 1 / 1.1))));
     };
     el.addEventListener("wheel", onWheel, { passive: false });
-    return () => el.removeEventListener("wheel", onWheel);
+    return () => { el.removeEventListener("wheel", onWheel); clearTimeout(end); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Open the document in the worker (off the main thread) → page count. Decoding happens lazily,
+  // per near page, in the effect below.
   useEffect(() => {
     let cancelled = false;
-    const created: string[] = [];
-    setPages([]);
-    setCount(0);
-    setError(null);
+    setCount(0); setError(null); setNear(new Set()); setDecoded(new Map());
+    wraps.current.clear(); sizes.current.clear();
     (async () => {
-      const DjVu = await loadDjVu();
       const buf = await fetch(blobUrl(node.path)).then((r) => r.arrayBuffer());
-      const doc = new DjVu.Document(buf);
-      const total = doc.getPagesQuantity();
-      if (!cancelled) setCount(total);
-      // Decode page-by-page and reveal each as it's ready, so a long scanned
-      // document shows its first page quickly instead of blocking on the whole.
-      for (let i = 1; i <= total && !cancelled; i++) {
-        const page = await doc.getPage(i);
-        const { url } = await page.createPngObjectUrl();
-        created.push(url);
-        if (!cancelled) setPages((prev) => [...prev, url]);
-      }
+      const n = await openDjvu(buf, node.path);
+      if (!cancelled) setCount(n);
     })().catch((e) => !cancelled && setError(String((e as Error).message || e)));
-    return () => {
-      cancelled = true;
-      created.forEach(URL.revokeObjectURL);
-    };
+    return () => { cancelled = true; };
   }, [node.path]);
 
+  // Windowed observer (mirror the PDF viewer): mark pages near the viewport.
+  useEffect(() => {
+    if (!count) return;
+    const obs = new IntersectionObserver(
+      (entries) => {
+        setNear((prev) => {
+          const next = new Set(prev);
+          for (const e of entries) {
+            const pn = Number((e.target as HTMLElement).dataset.page);
+            if (e.isIntersecting) next.add(pn);
+            else next.delete(pn);
+          }
+          return next.size === prev.size && [...next].every((p) => prev.has(p)) ? prev : next;
+        });
+      },
+      { root: ref.current, rootMargin: "2000px 0px" },
+    );
+    for (const el of wraps.current.values()) obs.observe(el);
+    return () => obs.disconnect();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [count, width > 0]);
+
+  // Decode near pages (lazy, in the worker); drop decoded pixels that left the window to bound
+  // memory (the worker keeps an LRU cache, so re-entry is fast).
+  useEffect(() => {
+    let alive = true;
+    near.forEach((n) => {
+      if (!decoded.has(n)) {
+        decodeDjvuPage(n)
+          .then((dp) => {
+            sizes.current.set(n, { w: dp.w, h: dp.h });
+            if (alive) setDecoded((m) => new Map(m).set(n, dp));
+          })
+          .catch(() => {});
+      }
+    });
+    setDecoded((m) => {
+      let changed = false;
+      const x = new Map(m);
+      for (const k of x.keys()) if (!near.has(k)) { x.delete(k); changed = true; }
+      return changed ? x : m;
+    });
+    return () => { alive = false; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [near]);
+
+  // A finished text selection on an OCR page → a `djvu` region (its bounding box, in native px).
+  const onMouseUp = () => {
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || !sel.anchorNode) return;
+    const hostEl = sel.anchorNode.nodeType === 1 ? (sel.anchorNode as Element) : sel.anchorNode.parentElement;
+    const wrap = hostEl?.closest(".djvu-page-wrap") as HTMLElement | null;
+    if (!wrap || !ref.current?.contains(wrap)) return;
+    const pn = Number(wrap.dataset.page);
+    const wr = wrap.getBoundingClientRect();
+    const s = wr.width / (decoded.get(pn)?.w || 1); // display px per native px
+    if (!s) return;
+    const sr = sel.getRangeAt(0).getBoundingClientRect();
+    if (sr.width < 2 || sr.height < 2) return;
+    openCreate(
+      { type: "djvu", page: pn, x: Math.round((sr.left - wr.left) / s), y: Math.round((sr.top - wr.top) / s), w: Math.round(sr.width / s), h: Math.round(sr.height / s) },
+      { x: sr.left, y: sr.bottom + 6 },
+    );
+  };
+
+  // Marquee drag on a page with NO OCR: draw a box, convert to native px.
+  const scaleOf = (pn: number, wrap: HTMLElement) => wrap.getBoundingClientRect().width / (decoded.get(pn)?.w || 1);
+  const dragStart = (pn: number, e: React.MouseEvent) => {
+    const wr = e.currentTarget.getBoundingClientRect();
+    const s = scaleOf(pn, e.currentTarget as HTMLElement);
+    setDrag({ page: pn, x0: (e.clientX - wr.left) / s, y0: (e.clientY - wr.top) / s, x1: (e.clientX - wr.left) / s, y1: (e.clientY - wr.top) / s });
+  };
+  const dragMove = (pn: number, e: React.MouseEvent) => {
+    const wr = e.currentTarget.getBoundingClientRect();
+    const s = scaleOf(pn, e.currentTarget as HTMLElement);
+    setDrag((d) => (d ? { ...d, x1: (e.clientX - wr.left) / s, y1: (e.clientY - wr.top) / s } : d));
+  };
+  const dragEnd = (pn: number, e: React.MouseEvent) => {
+    const d = drag;
+    setDrag(null);
+    if (!d || d.page !== pn) return;
+    const s = scaleOf(pn, e.currentTarget as HTMLElement);
+    const left = Math.min(d.x0, d.x1), top = Math.min(d.y0, d.y1), w = Math.abs(d.x1 - d.x0), h = Math.abs(d.y1 - d.y0);
+    if (w * s < 3 || h * s < 3) return; // a click, not a drag
+    const wr = e.currentTarget.getBoundingClientRect();
+    openCreate(
+      { type: "djvu", page: pn, x: Math.round(left), y: Math.round(top), w: Math.round(w), h: Math.round(h) },
+      { x: wr.left + left * s, y: wr.top + (top + h) * s + 6 },
+    );
+  };
+
   if (error) return <div className="error">djvu: {error}</div>;
   return (
-    <div className="filedjvu yo-zoomable" ref={ref}>
-      {count > 0 && pages.length < count && (
-        <div className="loading">decoding djvu… page {pages.length + 1} of {count}</div>
-      )}
-      {count === 0 && pages.length === 0 && <div className="loading">decoding djvu…</div>}
-      {pages.map((url, i) => (
-        <img key={i} className="djvu-page" style={{ width: `${zoom * 100}%` }} src={url} alt={`page ${i + 1}`} />
-      ))}
-    </div>
+    <>
+      <div className="filedjvu yo-zoomable" ref={ref} onMouseUp={onMouseUp}>
+        {count === 0 && <div className="loading">opening djvu…</div>}
+        {width > 0 &&
+          Array.from({ length: count }, (_, i) => {
+            const pn = i + 1;
+            const dp = near.has(pn) ? decoded.get(pn) : undefined;
+            const size = sizes.current.get(pn);
+            const estHeight = dispW * (size ? size.h / size.w : Math.SQRT2);
+            const s = dp ? dispW / dp.w : 0;
+            return (
+              <div
+                key={i}
+                className="djvu-page-wrap"
+                data-page={pn}
+                ref={(el) => { if (el) wraps.current.set(pn, el); else wraps.current.delete(pn); }}
+                style={{ width: dispW, height: dp ? undefined : estHeight }}
+              >
+                {dp ? (
+                  <>
+                    <DjvuCanvas image={dp.image} />
+                    {dp.zones.length > 0 ? (
+                      <div className="djvu-textlayer">
+                        {dp.zones.map((z, j) => (
+                          <span key={j} style={{ left: z.x * s, top: z.y * s, width: z.width * s, height: z.height * s, fontSize: z.height * s }}>{z.text}</span>
+                        ))}
+                      </div>
+                    ) : (
+                      <div className="djvu-marquee" onMouseDown={(e) => dragStart(pn, e)} onMouseMove={(e) => dragMove(pn, e)} onMouseUp={(e) => dragEnd(pn, e)}>
+                        {drag?.page === pn && (
+                          <div className="djvu-region" style={{ left: Math.min(drag.x0, drag.x1) * s, top: Math.min(drag.y0, drag.y1) * s, width: Math.abs(drag.x1 - drag.x0) * s, height: Math.abs(drag.y1 - drag.y0) * s, borderColor: previewColor, background: previewColor + "2e" }} />
+                        )}
+                      </div>
+                    )}
+                    {regions.filter((r) => r.page === pn).map((r, j) => {
+                      const c = r.color || DEFAULT_COLOR;
+                      return (
+                        <div
+                          key={j}
+                          className={"djvu-region" + (r.ann ? " editable" : "")}
+                          title={r.ann ? r.title || "click to recolor or delete" : r.title}
+                          onClick={r.ann ? (e) => { e.stopPropagation(); openEdit(r.ann!, { x: e.clientX, y: e.clientY }); } : undefined}
+                          style={{ left: r.x * s, top: r.y * s, width: r.w * s, height: r.h * s, borderColor: c, background: c + "2e" }}
+                        />
+                      );
+                    })}
+                  </>
+                ) : (
+                  <div className="djvu-placeholder">{near.has(pn) ? "decoding…" : ""}</div>
+                )}
+              </div>
+            );
+          })}
+      </div>
+      {palette}
+    </>
   );
 }

package/src/client/renderers/djvuWorker.ts

@@ -0,0 +1,99 @@
+// Off-main-thread DjVu decoding. The vendored DjVu.js (vendor/djvu.js) doubles as its own Web
+// Worker script (it detects worker context internally); `new DjVu.Worker()` spins that worker from
+// an inline blob. We drive ONE worker + ONE open document at a time (one viewer is open at a time),
+// decoding pages lazily on demand so the main thread never blocks on JB2/IW44 decompression — which
+// is what froze annotation while a big scan decoded. The library bundle itself is injected once as a
+// classic <script> so the `DjVu.Worker` class is available on the main thread.
+import djvuScriptUrl from "../vendor/djvu.js?url";
+
+declare global {
+  interface Window { DjVu?: any }
+}
+
+/** One OCR text zone — absolute pixels in the page's native space (top-left origin). */
+export interface Zone { x: number; y: number; width: number; height: number; text: string }
+/** A decoded page: pixels (paint to a canvas), OCR zones (may be empty), native pixel size. */
+export interface DecodedPage { image: ImageData; zones: Zone[]; w: number; h: number }
+
+let libLoading: Promise<any> | null = null;
+/** Inject the vendored bundle once; resolve with the global `DjVu` namespace (for `DjVu.Worker`). */
+function loadDjVu(): Promise<any> {
+  if (window.DjVu) return Promise.resolve(window.DjVu);
+  libLoading ??= new Promise((resolve, reject) => {
+    const s = document.createElement("script");
+    s.src = djvuScriptUrl;
+    s.onload = () => (window.DjVu ? resolve(window.DjVu) : reject(new Error("DjVu failed to load")));
+    s.onerror = () => reject(new Error("could not load djvu.js"));
+    document.head.appendChild(s);
+  });
+  return libLoading;
+}
+
+let worker: any = null; // the singleton DjVu.Worker (kept alive across viewers, like pdf.js's worker)
+let curKey: string | null = null; // node.path of the currently open document
+let opening: Promise<number> | null = null; // resolves to the page count of the open document
+const cache = new Map<number, DecodedPage>(); // LRU (by re-insertion) of decoded pages — bounds memory
+const inflight = new Map<number, Promise<DecodedPage>>();
+const CACHE_CAP = 6; // few full pages kept; scans are huge (a native page can be ~tens of MB)
+const MAX_RASTER_W = 1500; // cap stored pixels: a scan's native width is overkill for a ~1000px display
+                           // (and at full native res the in-memory ImageData crashes the tab)
+
+/** Open a DjVu document in the worker (re-creating only when the file changes) and resolve its page
+ *  count. The buffer is transferred to the worker. */
+export async function openDjvu(buf: ArrayBuffer, key: string): Promise<number> {
+  const DjVu = await loadDjVu();
+  worker ??= new DjVu.Worker(); // inline-blob worker; no separate script URL needed
+  if (key !== curKey) {
+    curKey = key;
+    cache.clear();
+    inflight.clear();
+    opening = (async () => {
+      await worker.createDocument(buf);
+      return Number(await worker.doc.getPagesQuantity().run()) || 0;
+    })();
+  }
+  return opening!;
+}
+
+/** Resize a (large) ImageData to `targetW` wide, preserving aspect → a smaller ImageData. The
+ *  browser does the resampling in `createImageBitmap` (off the main thread); the full-size source is
+ *  then released. Keeps memory bounded without changing coordinates (native size is tracked apart). */
+async function downscale(full: ImageData, targetW: number): Promise<ImageData> {
+  const targetH = Math.max(1, Math.round((full.height * targetW) / full.width));
+  const bmp = await createImageBitmap(full, { resizeWidth: targetW, resizeHeight: targetH, resizeQuality: "medium" });
+  const cnv = document.createElement("canvas");
+  cnv.width = targetW;
+  cnv.height = targetH;
+  const cx = cnv.getContext("2d")!;
+  cx.drawImage(bmp, 0, 0);
+  bmp.close();
+  return cx.getImageData(0, 0, targetW, targetH);
+}
+
+/** Decode one page (1-based) off the main thread: image + OCR zones + native size, in a single
+ *  batched worker round-trip. Memoized (LRU) so re-scroll/zoom doesn't re-decode. */
+export function decodeDjvuPage(n: number): Promise<DecodedPage> {
+  const hit = cache.get(n);
+  if (hit) { cache.delete(n); cache.set(n, hit); return Promise.resolve(hit); } // LRU touch
+  const pending = inflight.get(n);
+  if (pending) return pending;
+  const p = (async () => {
+    const [full, zones, w, h] = await worker.run(
+      worker.doc.getPage(n).getImageData(),
+      worker.doc.getPage(n).getNormalizedTextZones(),
+      worker.doc.getPage(n).getWidth(),
+      worker.doc.getPage(n).getHeight(),
+    );
+    const nativeW = Number(w) || full.width, nativeH = Number(h) || full.height;
+    // Downscale to a display-adequate raster (the native scan is huge); coordinates stay in NATIVE
+    // px (zones + region selectors), so the smaller canvas is purely a sharpness/memory trade.
+    const image = nativeW > MAX_RASTER_W ? await downscale(full, MAX_RASTER_W) : full;
+    const dp: DecodedPage = { image, zones: Array.isArray(zones) ? zones : [], w: nativeW, h: nativeH };
+    inflight.delete(n);
+    cache.set(n, dp);
+    while (cache.size > CACHE_CAP) cache.delete(cache.keys().next().value as number); // evict oldest
+    return dp;
+  })();
+  inflight.set(n, p);
+  return p;
+}

package/src/client/renderers/paged.ts

@@ -0,0 +1,137 @@
+import { useEffect, useRef } from "react";
+import { pageFromUrl, writePageToUrl } from "../paths";
+
+/** Page-tracking + zoom-anchoring for a vertically-paged viewer (PDF, DjVu). */
+export interface PagedScroll {
+  /** Record {page, fraction-within-page} from the current scroll — call BEFORE a zoom commit. */
+  captureAnchor(): void;
+  /** After the zoom reflow, put that same page+fraction back under the viewport. */
+  restoreAnchor(): void;
+  /** Scroll a 1-based page to the top of the viewport (used for the initial `?page=` restore). */
+  scrollToPage(n: number): void;
+  /** The page the URL asked for on mount (1 if none). */
+  initialPage: number;
+}
+
+/**
+ * Tracks the current page of a paged viewer and keeps it stable across zoom and reload.
+ *
+ * `scrollRef` is the scrolling container; `getPageEls()` returns the page elements top-to-bottom
+ * (1-based by array index, may be short/sparse before everything has rendered); `ready` is true
+ * once pages are laid out enough to measure. While ready it (a) writes the current page to `?page=`
+ * on scroll (rAF-throttled, replaceState — no remount), (b) restores `?page=` once on load
+ * (re-attempting until the target page's height settles, since it may start as a placeholder), and
+ * (c) exposes capture/restore so the caller can hold the reading position across a zoom reflow.
+ *
+ * All geometry uses getBoundingClientRect relative to the scroller, so it is correct regardless of
+ * which element is the page's offsetParent.
+ */
+export function usePagedScroll(
+  scrollRef: React.RefObject<HTMLElement | null>,
+  getPageEls: () => HTMLElement[],
+  ready: boolean,
+): PagedScroll {
+  const initialPage = useRef(pageFromUrl()).current;
+  const anchor = useRef<{ page: number; fraction: number } | null>(null);
+  const suppress = useRef(false); // true around a programmatic scroll → don't write ?page=
+  const restored = useRef(false); // initial ?page= scroll settled
+  const lastH = useRef(0); // target-page height at the last restore attempt (settled when stable)
+
+  // A page's top in the scroller's content coordinates (offsetParent-agnostic).
+  const contentTop = (el: HTMLElement): number => {
+    const sc = scrollRef.current!;
+    return el.getBoundingClientRect().top - sc.getBoundingClientRect().top + sc.scrollTop;
+  };
+  // The 1-based page at the viewport's "reading" line (a bit below the top).
+  const currentPage = (): number => {
+    const sc = scrollRef.current;
+    const els = getPageEls();
+    if (!sc || !els.length) return 1;
+    const probeY = sc.getBoundingClientRect().top + sc.clientHeight * 0.3;
+    for (let i = 0; i < els.length; i++) {
+      const r = els[i]?.getBoundingClientRect();
+      if (r && probeY < r.bottom) return i + 1;
+    }
+    return els.length;
+  };
+  const scrollTo = (top: number) => {
+    const sc = scrollRef.current;
+    if (!sc) return;
+    suppress.current = true;
+    sc.scrollTop = top;
+    setTimeout(() => (suppress.current = false), 120); // outlast the resulting scroll event
+  };
+  const scrollToPage = (n: number) => {
+    const els = getPageEls();
+    if (!els.length) return;
+    const t = els[Math.min(Math.max(n, 1), els.length) - 1];
+    if (t) scrollTo(contentTop(t));
+  };
+
+  // Page tracking — rAF-throttled scroll → ?page=.
+  useEffect(() => {
+    const sc = scrollRef.current;
+    if (!sc || !ready) return;
+    let raf = 0;
+    const onScroll = () => {
+      if (raf) return;
+      raf = requestAnimationFrame(() => {
+        raf = 0;
+        if (!suppress.current) writePageToUrl(currentPage());
+      });
+    };
+    sc.addEventListener("scroll", onScroll, { passive: true });
+    return () => { sc.removeEventListener("scroll", onScroll); if (raf) cancelAnimationFrame(raf); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ready]);
+
+  // Initial ?page= restore — runs each render until the target page's height stabilizes (it may
+  // start as an estimated-height placeholder), then latches `restored`.
+  useEffect(() => {
+    if (restored.current || initialPage <= 1) { restored.current = true; return; }
+    if (!ready) return;
+    const els = getPageEls();
+    const t = els[Math.min(initialPage, els.length) - 1];
+    if (!t) return; // target not laid out yet — a later render retries
+    const h = t.getBoundingClientRect().height;
+    scrollToPage(initialPage);
+    if (h > 0 && h === lastH.current) restored.current = true; // height settled → done
+    lastH.current = h;
+  });
+
+  const captureAnchor = () => {
+    const sc = scrollRef.current;
+    const els = getPageEls();
+    if (!sc || !els.length) { anchor.current = null; return; }
+    const page = currentPage();
+    const t = els[page - 1];
+    const h = t?.getBoundingClientRect().height ?? 0;
+    anchor.current = t ? { page, fraction: h ? (sc.scrollTop - contentTop(t)) / h : 0 } : null;
+  };
+  // Restore the anchored page+fraction, RE-APPLYING over a few frames until scrollTop stabilizes:
+  // a zoom commit resizes far-page placeholders and renders newly-near pages asynchronously, which
+  // shifts everything above the anchor — a single set would land a page or two off (or, when
+  // shrinking hard, at the clamped bottom). Re-applying tracks the anchor page as layout settles.
+  const restoreAnchor = () => {
+    const a = anchor.current;
+    if (!a) return;
+    let tries = 0;
+    let last = -1;
+    suppress.current = true;
+    const apply = () => {
+      const sc = scrollRef.current;
+      const t = getPageEls()[a.page - 1];
+      if (!sc || !t) { suppress.current = false; return; }
+      sc.scrollTop = contentTop(t) + a.fraction * t.getBoundingClientRect().height;
+      if (Math.abs(sc.scrollTop - last) > 1 && tries++ < 8) {
+        last = sc.scrollTop;
+        requestAnimationFrame(apply);
+      } else {
+        setTimeout(() => (suppress.current = false), 120); // settled — release the page-writer
+      }
+    };
+    apply();
+  };
+
+  return { captureAnchor, restoreAnchor, scrollToPage, initialPage };
+}

package/src/client/renderers/pdf.tsx

@@ -4,6 +4,7 @@ import "react-pdf/dist/Page/TextLayer.css";
 import "react-pdf/dist/Page/AnnotationLayer.css";
 import { Annotation, NodeJson, blobUrl } from "../api";
 import { DEFAULT_COLOR, colorOf, editable, useAnnotationMenu, useMaterialAnnotations } from "./annotate";
+import { usePagedScroll } from "./paged";
 
 /** A rectangular annotation region on a PDF page, in points (origin top-left). `ann` is the source
  *  annotation when real/saved (→ clickable to edit); absent for the live preview. */
@@ -31,6 +32,16 @@ export function PdfView({ node }: { node: NodeJson }) {
   const [pages, setPages] = useState(0);
   const [zoom, setZoom] = useState(1); // ctrl/alt-wheel scale factor
   const [orig, setOrig] = useState<Record<number, { w: number; h: number }>>({}); // each page's natural size in points
+  // Pages whose pdf.js TEXT LAYER is unusable for selection — absent (a scanned PDF has no text)
+  // or pathological (some fonts make pdf.js emit glyph boxes many times a line tall, so a text
+  // selection's geometry is garbage). Such pages fall back to a drag-marquee, like images.
+  const [marquee, setMarquee] = useState<Set<number>>(() => new Set());
+  const [drag, setDrag] = useState<{ page: number; x0: number; y0: number; x1: number; y1: number } | null>(null);
+  // Zoom scales the page content via a CSS transform (no re-raster → no blink). The transformed
+  // `.pdf-content` is out of flow, so a `.pdf-sizer` reserves the SCALED footprint to keep the
+  // scrollbar/height right; `contentH` is the content's natural (unscaled) height, measured below.
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [contentH, setContentH] = useState(0);
 
   // WINDOWED RENDERING: every page keeps a wrapper (so the scroll height is right), but only
   // pages near the viewport mount a real <Page> — mounting ALL of them queues every canvas
@@ -72,6 +83,19 @@ export function PdfView({ node }: { node: NodeJson }) {
     .filter((a) => a.selector?.type === "pdf")
     .map((a) => ({ page: num(a.selector!.page) || 1, x: num(a.selector!.x), y: num(a.selector!.y), w: num(a.selector!.w), h: num(a.selector!.h), title: a.description, color: colorOf(a), ann: editable(a) ? a : undefined }));
 
+  // Page tracking + zoom-anchoring (`?page=` in the URL; same page stays put across a zoom). Every
+  // page has a `.pdf-page` wrapper (windowing swaps only the CONTENT), so the list is dense 1..N.
+  const getPageEls = () => {
+    const out: HTMLElement[] = [];
+    for (let i = 1; i <= pages; i++) { const el = wraps.current.get(i); if (el) out.push(el); }
+    return out;
+  };
+  const paged = usePagedScroll(ref, getPageEls, width > 0 && pages > 0);
+  const pagedRef = useRef(paged);
+  pagedRef.current = paged;
+  // After a zoom COMMIT reflows the pages, restore the captured reading position.
+  useLayoutEffect(() => { paged.restoreAnchor(); }, [zoom]); // eslint-disable-line react-hooks/exhaustive-deps
+
   // Track the pane width so pages re-flow on resize.
   useLayoutEffect(() => {
     const el = ref.current;
@@ -81,20 +105,103 @@ export function PdfView({ node }: { node: NodeJson }) {
     return () => ro.disconnect();
   }, []);
 
-  // ctrl/alt-wheel zooms; a plain wheel is left alone so the pane keeps scrolling.
+  // Measure the content's natural (unscaled) height so the sizer can reserve `height*disp`.
+  useLayoutEffect(() => {
+    const el = contentRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver(() => setContentH(el.offsetHeight));
+    ro.observe(el);
+    setContentH(el.offsetHeight);
+    return () => ro.disconnect();
+  }, [pages, width > 0]);
+
+  // ctrl/alt-wheel zooms; a plain wheel is left alone so the pane keeps scrolling. Zoom is applied
+  // as a CSS scale on the content (below) — NOT by re-rastering the pages — so it never blinks; the
+  // reading position is anchored at the start of a wheel burst and restored after each step.
   useEffect(() => {
     const el = ref.current;
     if (!el) return;
+    let bursting = false;
+    let end = 0;
     const onWheel = (e: WheelEvent) => {
       if (!(e.ctrlKey || e.altKey || e.metaKey)) return;
       e.preventDefault();
+      if (!bursting) { pagedRef.current.captureAnchor(); bursting = true; }
+      clearTimeout(end);
+      end = window.setTimeout(() => (bursting = false), 250);
       setZoom((z) => Math.min(5, Math.max(0.4, z * (e.deltaY < 0 ? 1.1 : 1 / 1.1))));
     };
     el.addEventListener("wheel", onWheel, { passive: false });
-    return () => el.removeEventListener("wheel", onWheel);
+    return () => { el.removeEventListener("wheel", onWheel); clearTimeout(end); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  const pageWidth = Math.min(width, 1000) * zoom;
+  // RASTER the pages at a FIXED, zoom-independent width (supersampled by QUALITY so CSS zoom-in
+  // stays crisp to ~QUALITY×), and apply the user's zoom as a CSS scale on the content wrapper.
+  // Because the <Page width> never changes with zoom, pdf.js never re-rasterises (no canvas remount,
+  // no white flash) and the windowed `near` set doesn't churn — zoom is a pure, blink-free reflow.
+  const QUALITY = 2;
+  const pageWidth = Math.min(width, 1000) * QUALITY; // the raster width fed to <Page>
+  const disp = zoom / QUALITY; // CSS zoom on the content; display width = pageWidth*disp = base*zoom
+  const previewColor = preview?.color ?? DEFAULT_COLOR;
+
+  // Judge a page's text layer once it has rendered: unusable when there is no real text (< 3
+  // spans) or a typical glyph box is an implausible fraction of the page height (a normal line is
+  // ~1–2%; the pathological case is ~30%). Unusable pages switch to the marquee overlay below.
+  const judgeTextLayer = (pn: number) => {
+    const wrap = wraps.current.get(pn);
+    const tl = wrap?.querySelector(".textLayer");
+    const pageH = wrap?.getBoundingClientRect().height || 0;
+    let unusable = true;
+    if (tl && pageH) {
+      const hs = [...tl.querySelectorAll("span")]
+        .filter((s) => s.textContent?.trim())
+        .map((s) => s.getBoundingClientRect().height)
+        .sort((a, b) => a - b);
+      unusable = hs.length < 3 || hs[hs.length >> 1] / pageH > 0.05;
+    }
+    setMarquee((m) => {
+      if (unusable === m.has(pn)) return m;
+      const next = new Set(m);
+      if (unusable) next.add(pn);
+      else next.delete(pn);
+      return next;
+    });
+  };
+
+  // Marquee drag on an unusable-text-layer page. The wrapper rect is in DISPLAY (CSS-zoomed) px;
+  // divide by `disp` so coords are in RASTER (content-local) px — the same space the preview rect
+  // and saved regions render in (they live inside the zoomed content), and `/sc` then gives points.
+  const dragStart = (pn: number, e: React.MouseEvent) => {
+    const wrap = wraps.current.get(pn);
+    if (!wrap) return;
+    const pr = wrap.getBoundingClientRect();
+    const x = (e.clientX - pr.left) / disp, y = (e.clientY - pr.top) / disp;
+    setDrag({ page: pn, x0: x, y0: y, x1: x, y1: y });
+  };
+  const dragMove = (e: React.MouseEvent) =>
+    setDrag((d) => {
+      const wrap = d && wraps.current.get(d.page);
+      if (!wrap) return d;
+      const pr = wrap.getBoundingClientRect();
+      return { ...d!, x1: (e.clientX - pr.left) / disp, y1: (e.clientY - pr.top) / disp };
+    });
+  const dragEnd = (pn: number, e: React.MouseEvent) => {
+    const d = drag;
+    setDrag(null);
+    if (!d || d.page !== pn) return;
+    const sc = orig[pn] ? pageWidth / orig[pn].w : 0; // raster px per point
+    const wrap = wraps.current.get(pn);
+    if (!sc || !wrap) return;
+    const pr = wrap.getBoundingClientRect();
+    const x1 = (e.clientX - pr.left) / disp, y1 = (e.clientY - pr.top) / disp; // raster px
+    const left = Math.min(d.x0, x1), top = Math.min(d.y0, y1), w = Math.abs(x1 - d.x0), h = Math.abs(y1 - d.y0);
+    if (w * disp < 3 || h * disp < 3) return; // a click, not a drag (threshold in display px)
+    openCreate(
+      { type: "pdf", page: pn, x: Math.round(left / sc), y: Math.round(top / sc), w: Math.round(w / sc), h: Math.round(h / sc) },
+      { x: pr.left + left * disp, y: pr.top + (top + h) * disp + 6 }, // menu position in viewport px
+    );
+  };
 
   // A finished text selection on a page → a `pdf` region (its bounding box, converted to points).
   const onMouseUp = () => {
@@ -104,13 +211,15 @@ export function PdfView({ node }: { node: NodeJson }) {
     const pageEl = host?.closest(".pdf-page") as HTMLElement | null;
     if (!pageEl || !ref.current?.contains(pageEl)) return;
     const pn = Number(pageEl.dataset.page);
-    const sc = orig[pn] ? pageWidth / orig[pn].w : 0; // rendered px per point
+    const sc = orig[pn] ? pageWidth / orig[pn].w : 0; // raster px per point
     if (!sc) return;
-    const pr = pageEl.getBoundingClientRect();
+    const pr = pageEl.getBoundingClientRect(); // display (CSS-zoomed) px
     const sr = sel.getRangeAt(0).getBoundingClientRect();
     if (sr.width < 2 || sr.height < 2) return;
+    // sr/pr are display px → ÷disp to raster (content-local) px, then ÷sc to points.
+    const k = sc * disp; // display px per point
     openCreate(
-      { type: "pdf", page: pn, x: Math.round((sr.left - pr.left) / sc), y: Math.round((sr.top - pr.top) / sc), w: Math.round(sr.width / sc), h: Math.round(sr.height / sc) },
+      { type: "pdf", page: pn, x: Math.round((sr.left - pr.left) / k), y: Math.round((sr.top - pr.top) / k), w: Math.round(sr.width / k), h: Math.round(sr.height / k) },
       { x: sr.left, y: sr.bottom + 6 },
     );
   };
@@ -124,10 +233,12 @@ export function PdfView({ node }: { node: NodeJson }) {
           loading={<div className="loading">loading PDF…</div>}
           error={<div className="error">could not load PDF</div>}
         >
-          {width > 0 &&
-            Array.from({ length: pages }, (_, i) => {
+          {width > 0 && (
+            <div className="pdf-sizer" style={{ width: pageWidth * disp, height: contentH * disp }}>
+            <div className="pdf-content" ref={contentRef} style={{ width: pageWidth, transform: `scale(${disp})`, transformOrigin: "top left" }}>
+            {Array.from({ length: pages }, (_, i) => {
               const pn = i + 1;
-              const sc = orig[pn] ? pageWidth / orig[pn].w : 0; // rendered px per point — tracks zoom
+              const sc = orig[pn] ? pageWidth / orig[pn].w : 0; // RASTER px per point (regions render inside the CSS-zoomed content)
               // a far page's placeholder: its measured aspect when known, A4 portrait until then
               const estHeight = pageWidth * (orig[pn] ? orig[pn].h / orig[pn].w : Math.SQRT2);
               return (
@@ -146,8 +257,26 @@ export function PdfView({ node }: { node: NodeJson }) {
                         pageNumber={pn}
                         width={pageWidth}
                         onLoadSuccess={(p) => setOrig((o) => (o[pn] ? o : { ...o, [pn]: { w: p.originalWidth || pageWidth, h: p.originalHeight || pageWidth * Math.SQRT2 } }))}
+                        onRenderTextLayerSuccess={() => judgeTextLayer(pn)}
                         loading={<div className="loading" style={{ height: estHeight }}>page {pn}…</div>}
                       />
+                      {/* unusable text layer → a crosshair marquee over the page (drag a box). It
+                          sits ABOVE the text layer but BELOW the region divs (rendered next), so
+                          existing editable regions stay clickable while empty areas start a drag. */}
+                      {marquee.has(pn) && sc > 0 && (
+                        <div className="pdf-marquee" onMouseDown={(e) => dragStart(pn, e)} onMouseMove={dragMove} onMouseUp={(e) => dragEnd(pn, e)}>
+                          {drag?.page === pn && (
+                            <div
+                              className="pdf-region"
+                              style={{
+                                left: Math.min(drag.x0, drag.x1), top: Math.min(drag.y0, drag.y1),
+                                width: Math.abs(drag.x1 - drag.x0), height: Math.abs(drag.y1 - drag.y0),
+                                borderColor: previewColor, background: previewColor + "2e",
+                              }}
+                            />
+                          )}
+                        </div>
+                      )}
                       {sc > 0 &&
                         regions.filter((r) => r.page === pn).map((r, j) => {
                           const c = r.color || DEFAULT_COLOR;
@@ -168,6 +297,9 @@ export function PdfView({ node }: { node: NodeJson }) {
                 </div>
               );
             })}
+            </div>
+            </div>
+          )}
         </Document>
       </div>
       {palette}

package/src/client/styles.css

@@ -544,16 +544,47 @@ a.chunk-index:hover {
   background: #fff;
 }
 .filepdf .react-pdf__Page,
-.djvu-page {
+.djvu-page-wrap {
   margin: 0 0 12px; /* left-aligned (004) */
   box-shadow: 0 1px 6px rgba(0, 0, 0, 0.4);
 }
-/* a decoded DjVu page — width is driven inline by the zoom factor (ctrl/alt-wheel) */
+/* a DjVu page: a positioned wrapper (sized inline to the display width) holding the decoded page
+   <canvas>, its OCR text layer (selectable), the marquee overlay, and the annotation region divs */
+.djvu-page-wrap {
+  position: relative;
+}
 .djvu-page {
   display: block;
+  width: 100%;
   max-width: none;
   background: #fff;
 }
+/* a not-yet-decoded page (windowed rendering) — fills the wrapper's estimated height */
+.djvu-placeholder {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #fff;
+  color: #888;
+  font-size: 12px;
+}
+/* OCR text layer: transparent positioned spans over the page → native browser text selection */
+.djvu-textlayer {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  overflow: hidden;
+  line-height: 1;
+}
+.djvu-textlayer span {
+  position: absolute;
+  color: transparent;
+  white-space: pre;
+  transform-origin: 0 0;
+  cursor: text;
+}
 
 /* rendered Markdown / AsciiDoc body */
 .markup {
@@ -884,14 +915,43 @@ a.chunk-index:hover {
   background: #fff;
   opacity: 0.06;
 }
-.pdf-region {
+/* Zoom is a CSS transform on .pdf-content (scales the rendered pages with NO re-raster → no
+   blink). The transformed content is taken out of flow, so .pdf-sizer reserves its scaled
+   footprint to keep the scroll height correct. */
+.pdf-sizer {
+  position: relative;
+}
+.pdf-content {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+
+/* drag-marquee overlay for pages with no usable text layer (scanned/pathological PDF, or a DjVu
+   with no OCR) — above the text layer (z 2), below the editable region divs so saved regions
+   stay clickable */
+.pdf-marquee,
+.djvu-marquee {
+  position: absolute;
+  inset: 0;
+  z-index: 3;
+  cursor: crosshair;
+  user-select: none;
+}
+.pdf-region,
+.djvu-region {
   position: absolute;
   box-sizing: border-box;
+  /* above the text layer (z 2) and the marquee overlay (z 3) so a saved region is the topmost
+     element at its rectangle — otherwise a text-layer span or the marquee swallows the click and
+     the edit/delete menu never opens */
+  z-index: 4;
   border: 2px solid #f9e2af;
   background: rgba(249, 226, 175, 0.18);
   pointer-events: none; /* the live preview must not block selecting text under it */
 }
-.pdf-region.editable {
+.pdf-region.editable,
+.djvu-region.editable {
   pointer-events: auto; /* a saved region is clickable → the edit menu */
   cursor: pointer;
 }