[muhammad-ali-e]

What

New files in the v1 DocumentViewer (P1-T21, UN-4390):

• components/patterns/document-viewer/PdfPageList.tsx — shows every page of a document in one scrolling column.
• components/patterns/document-viewer/PdfPage.tsx — one page: a placeholder at the page's real size, plus a canvas.
• hooks/usePageWindow.ts — tracks which pages are in view.
• lib/pdf/windowing.ts — the arithmetic: which pages to render, the pixel ratio, and page size at a zoom.

Why

The same viewer has to open 200-page documents. Rendering every page uses far too much memory, so only the pages near the viewport get a canvas.

How

• Page sizes and scrollbar: each page is laid out at its own size, using the sizes usePdfDocument reads at load (UN-4502). The scrollbar is therefore right before anything renders.

• Render window: one IntersectionObserver on the scroll container tracks which pages are in view. Those pages plus 2 on each side get a canvas. When nothing is in view yet, nothing renders.

• Fast scrolling: a page starts rendering one frame after it enters the window. The UN-4501 spike flagged fast scrolling at 2× zoom as the main risk, and with this delay a fast scroll draws nothing for the pages it passes.

• Cancelling and freeing: a page leaving the window, or a zoom change, does four things:

  • cancels the RenderTask in flight
  • calls page.cleanup()
  • sets the canvas width and height to 0
  • removes the canvas

  Zeroing the canvas first matters because Safari keeps a canvas's memory until garbage collection, and caps the total.

• Pixel ratio: the screen's ratio, capped at 2. It is lowered further when a canvas would exceed 16,777,216 px, the largest canvas Safari allocates.

• Zoom: zoom 1 means 100%, i.e. the printed size (96/72 CSS px per PDF point).

• Sizing without inline style: v1 bans the style attribute (S1), so page sizes are set as --page-width / --page-height custom properties through a ref, and ui:w-(--page-width) / ui:h-(--page-height) read them. I've asked Praveen in #engg-unstract-frontend-v1-migration whether they'd prefer an explicit S1 escape for this kind of computed geometry.

• Layout: pages are centred while they fit, and scroll both ways once a zoomed page is wider than the viewer.

• Overlays: renderPageOverlay(index) draws over each page, at the page's size. The highlight layer in UN-4504 uses it.

Can this PR break any existing features. If yes, please list possible items. If no, please explain why. (PS: Admins do not merge the PR without this section filled)

• No. This adds new files under src/v1/ only, and nothing imports them yet. There are no package, config or v0 changes.

Database Migrations

• None

Env Config

• None

Relevant Docs

• The P1-T21 implementation plan, plus the UN-4501 spike results (200-page prototype on the same pdf.js 3.11.174).

Related Issues or PRs

• Jira: UN-4503 (parent UN-4390).
• Stacked on UN-4502 [DEV] Add the v1 PDF loader, document hook and viewer states #2404 (UN-4502), which sits on UN-4299 [FEAT] v1 design tokens, themes and style isolation (P0-T04) #2399 and UN-4270 [FEAT] v1 scaffold, strict TypeScript and import boundary #2380. It will be retargeted as those merge.

Dependencies Versions

• None

Notes on Testing

• bun run typecheck:v1, lint:v1 and test:v1 pass: 79 unit tests and 56 boundary fixtures.
• The new tests use a controllable IntersectionObserver and a mocked pdf.js. They cover:
  • all pages laid out at their own size, with no canvases before layout
  • a scripted scroll through 200 pages: at most 6 canvases ever exist, and at the end only pages 196–199 are live
  • DPR 3 rendering at a ratio of 2, with the canvas sized to match
  • a zoom change cancelling the render in flight
  • leaving the window zeroing the canvas and cleaning up the page
  • a page that leaves before its frame fires never being drawn
• A probe Vite build checked two more things:
  • the ui:w-(--page-width) / ui:h-(--page-height) utilities are generated
  • the worker is emitted as a hashed asset from the ?url import
• The build warns about eval in pdf.js. That is the code path isEvalSupported: false turns off.
• Real-browser checks (the 200-page fixture in Playwright, and highlight rectangles) come in UN-4507.

Screenshots

• None yet. The gallery comes in UN-4507.

Checklist

I have read and understood the Contribution Guidelines.

---

Generated by Claude Code

[muhammad-ali-e]

pre-commit.ci - pr is red because of the base branch, not this PR.

The failing hook is check-shebang-scripts-are-executable, on frontend/scripts/check-v1-styles.mjs. That file has a #! line but no executable bit. It comes from the tokens PR #2399 (UN-4299-design-tokens-themes); this PR doesn't touch it. The hook doesn't fail on #2399 itself only because pre-commit.ci doesn't run on that PR. Running pre-commit run --from-ref $(git merge-base origin/main HEAD) locally reproduces it, and this PR's own files pass every hook.

There's no fix to port yet. The fix is a one-line change on #2399: git add --chmod=+x frontend/scripts/check-v1-styles.mjs (or drop the shebang). Once #2399 has it, this check should go green here without any change to this PR.

---

Generated by Claude Code

[greptile-apps]

via Greptile

Confidence Score: 5/5

[Low impact] The PR appears safe to merge as part of the reviewed stack, including PR #2408's document-switch protection.

Summary

Adds a scrolling PDF page list that keeps canvases near the visible pages.

• PDF pages scroll in one column while only nearby pages render.
• PDF pages redraw off-screen and release their canvases when they leave.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Page sizes and zoom] --> B[Place every page at its own size]
  B --> C[Observe pages in view]
  C --> D[Add two nearby pages on each side]
  D --> E[Draw into a scratch canvas]
  E --> F[Copy the finished picture]
  D --> G[Page leaves the window]
  G --> H[Cancel work and free canvases]

Loading

_{Reviews (4) · Last reviewed commit: "Merge branch 'UN-4502-v1-pdf-loader' int..." · Reviewed by Greptile}

[praveen-formido]

Windowing and the page component. Two visible problems, both in PdfPage.tsx/PdfPageList.tsx: the canvas is blanked before the replacement render starts, so every page in the window flashes on each zoom step, and the overlay children defeat the memo on every window change. The rest are smaller.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud