yamlover 0.3.1 → 0.3.3

package/src/client/renderers/djvu.tsx

@@ -1,97 +1,271 @@
-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
+
+  // Focus the `.filedjvu` scroller on mount so arrows / space / PageUp-Down scroll the document
+  // natively (it's a nested scroller the focused RHS pane can't reach). Skip when chunk-embedded.
+  useEffect(() => {
+    const el = ref.current;
+    if (el && !el.closest(".chunk-body")) el.focus({ preventScroll: true });
+  }, []);
+
+  // 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} tabIndex={0} 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/explorer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { NodeJson, fetchTagged } from "../api";
 import { asLink, Link } from "../render";
 import { typeIcon } from "../icons";
@@ -117,12 +117,46 @@ function isDocFormat(f?: string | null): boolean {
   return !!f && (f.includes("/") || f.startsWith("x-yamlover-"));
 }
 
-function Item({ it, onNavigate }: { it: ExplorerItem; onNavigate: (path: string) => void }) {
+/** The grid item to move to from `cur` for an arrow key. Left/Right step in reading
+ *  order; Up/Down pick the nearest item in the adjacent row, preferring the same
+ *  column — measured from live geometry, so it's correct for the wrapping flex grid
+ *  (variable columns, a short last row) without knowing the column count. */
+function arrowTarget(els: (HTMLElement | null)[], cur: number, key: string, count: number): number {
+  if (key === "ArrowRight") return Math.min(cur + 1, count - 1);
+  if (key === "ArrowLeft") return Math.max(cur - 1, 0);
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  const a = els[cur];
+  if (!a) return cur;
+  const r = a.getBoundingClientRect();
+  const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+  const down = key === "ArrowDown";
+  let best = cur, bestScore = Infinity;
+  for (let i = 0; i < count; i++) {
+    const el = els[i];
+    if (!el || i === cur) continue;
+    const ri = el.getBoundingClientRect();
+    const ix = ri.left + ri.width / 2, iy = ri.top + ri.height / 2;
+    if (down ? iy <= cy + 1 : iy >= cy - 1) continue; // must lie in the arrow's direction
+    const score = Math.abs(ix - cx) * 2 + Math.abs(iy - cy); // prefer same column, nearest row
+    if (score < bestScore) { bestScore = score; best = i; }
+  }
+  return best;
+}
+
+function Item({ it, active, setRef, onFocus, onNavigate }: {
+  it: ExplorerItem;
+  active: boolean;
+  setRef: (el: HTMLElement | null) => void;
+  onFocus: () => void;
+  onNavigate: (path: string) => void;
+}) {
   const link = it.link;
+  const tabIndex = active ? 0 : -1; // roving tabindex: only the selected item is in the tab order
   if (!link) {
     // not a marker (unexpected at depth 1) — an inert label, no navigation
     return (
-      <span className="dirview-item">
+      <span className="dirview-item" ref={setRef} tabIndex={tabIndex} onFocus={onFocus}>
         <span className="dirview-icon t-bin">•</span>
         <span className="dirview-label">{it.key}: {scalarText(it.raw)}</span>
       </span>
@@ -147,6 +181,9 @@ function Item({ it, onNavigate }: { it: ExplorerItem; onNavigate: (path: string)
       className={"dirview-item" + (it.up ? " dirview-up" : "")}
       href={link.path}
       title={displayPath(link.path)}
+      ref={setRef}
+      tabIndex={tabIndex}
+      onFocus={onFocus}
       onClick={(e) => {
         e.preventDefault();
         onNavigate(link.path);
@@ -189,6 +226,43 @@ export function ExplorerView({ node, onNavigate }: { node: NodeJson; onNavigate:
   }
   const items = [...ups, ...members];
 
+  // Roving keyboard focus over the grid: plain arrows walk the icons, Enter opens the
+  // selected one. The item elements are tracked by index for the geometry-based row moves.
+  const gridRef = useRef<HTMLDivElement>(null);
+  const itemEls = useRef<(HTMLElement | null)[]>([]);
+  itemEls.current.length = items.length; // drop stale refs when the member list shrinks
+  const [active, setActive] = useState(0);
+  useEffect(() => {
+    if (active > items.length - 1) setActive(Math.max(0, items.length - 1));
+  }, [items.length, active]);
+
+  // On navigating to a new directory, reset the selection and re-arm autofocus (this
+  // component is reused across nodes, not remounted, so the flag must follow `node.path`).
+  const wantFocus = useRef(true);
+  useEffect(() => { setActive(0); wantFocus.current = true; }, [node.path]);
+  // Focus the first item once the grid has members (a tag's load async), so arrows work right
+  // after navigating here (the RHS pane handed us focus) — once per node, and never when
+  // embedded as a chapter chunk (several grids would fight over focus).
+  useEffect(() => {
+    if (!wantFocus.current || !items.length) return;
+    wantFocus.current = false;
+    if (gridRef.current?.closest(".chunk-body")) return; // embedded — don't steal focus
+    itemEls.current[0]?.focus({ preventScroll: true });
+  }, [items.length, node.path]);
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (e.ctrlKey || e.altKey || e.metaKey || !items.length) return; // Ctrl/Alt+arrows = TOC nav (App)
+    if (e.key === "Enter") {
+      const link = items[active]?.link;
+      if (link) { e.preventDefault(); onNavigate(link.path); }
+      return;
+    }
+    if (!/^(Arrow(Up|Down|Left|Right)|Home|End)$/.test(e.key)) return;
+    e.preventDefault(); // don't also scroll the pane
+    const next = arrowTarget(itemEls.current, active, e.key, items.length);
+    if (next !== active) { setActive(next); itemEls.current[next]?.focus(); }
+  };
+
   // a tag page's description is its BODY (the header bar already names the node)
   const desc = (isTag ? tagBody(node.value) : null) ?? node.description;
   return (
@@ -198,9 +272,20 @@ export function ExplorerView({ node, onNavigate }: { node: NodeJson; onNavigate:
           <p className="tagdesc">{desc}</p>
         </div>
       )}
-      <div className={"dirview" + (explorerViewMode() === "large" ? " dirview-lg" : "")}>
+      <div
+        ref={gridRef}
+        className={"dirview" + (explorerViewMode() === "large" ? " dirview-lg" : "")}
+        onKeyDown={onKeyDown}
+      >
         {items.map((it, i) => (
-          <Item key={`${it.up ? "^" : ""}${it.link?.path ?? it.key}#${i}`} it={it} onNavigate={onNavigate} />
+          <Item
+            key={`${it.up ? "^" : ""}${it.link?.path ?? it.key}#${i}`}
+            it={it}
+            active={i === active}
+            setRef={(el) => { itemEls.current[i] = el; }}
+            onFocus={() => setActive(i)}
+            onNavigate={onNavigate}
+          />
         ))}
         {items.length === 0 && <span className="dirview-empty">empty</span>}
       </div>