[muhammad-ali-e]

What

• src/v1/lib/pdf/pdfjs.ts and types.ts: the only place v1 imports pdf.js.
• src/v1/hooks/usePdfDocument.ts: opens a PDF and tracks it through each state.
• src/v1/components/patterns/document-viewer/ViewerStatus.tsx: renders every state except ready. The page list renders ready (UN-4503).

First of the P1-T21 DocumentViewer sub-tasks (UN-4390).

Why

Six v1 page tasks need one document viewer. This PR is its foundation: one way to load a PDF, with the security defaults set once.

How

• Uses the pdfjs-dist@3.11.174 already in package.json, as Jaseem asked: one pdf.js for the whole frontend.
  • It imports the same default build and worker that v0 ships, so the app has one pdf.js engine and one worker.
  • The worker is bundled with ?url, never fetched from a CDN.
  • Both load on first use (dynamic import), so pdf.js stays out of any bundle that never opens a PDF.
• getDocument always gets isEvalSupported: false (CVE-2024-4367; 3.x has no other fix).
• Sources are {kind: "url", url, withCredentials?, httpHeaders?} or {kind: "data", data}. In-memory bytes are copied first, because pdf.js transfers its buffer to the worker and would empty the caller's copy before a Retry.
• Page sizes are read in parallel, at most 16 at a time. The spike measured about 1 s for 200 pages when they were read one after another.
• usePdfDocument(source) returns {state, retry, submitPassword}. state is one of: empty, loading, password (with an incorrect flag), unsupported, failed (with its message) or ready (document and pageSizes).
  • It reopens only when the URL, the request options or the byte buffer change, so callers can pass a fresh object on every render.
  • The previous loading task is destroyed when the source changes and on unmount, and its late result is ignored.
• Load errors are classified by pdf.js exception name:
  • PasswordException code 1 = password needed, code 2 = wrong password
  • InvalidPDFException = unsupported
  • anything else = failed
• The status messages use ui: tokens only. There's no core Button yet, so these are plain elements with the focus ring. They'll swap to the core component once it exists.

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. Everything is new code under src/v1/, and nothing in v0 or the v1 entry imports it yet. There are no package or config changes, and v0's pdf.js setup is untouched. v1 shares v0's pdf.js module and sets the same GlobalWorkerOptions.workerSrc (the bundled pdf.worker.min.js URL), so loading either one first leaves the other working.

Database Migrations

• None

Env Config

• None

Relevant Docs

• Plan and folder mapping: P1-T21 implementation plan (UN-4390). Spike results are on UN-4501.

Related Issues or PRs

• Jira: UN-4502 (parent UN-4390, P1-T21)
• Stacked on UN-4299 [FEAT] v1 design tokens, themes and style isolation (P0-T04) #2399 (tokens), which is stacked on UN-4270 [FEAT] v1 scaffold, strict TypeScript and import boundary #2380 (scaffold). This will be retargeted to main once both merge.

Dependencies Versions

• None. It uses the existing pdfjs-dist@3.11.174.

Notes on Testing

• bun run typecheck:v1, bun run lint:v1 and bun run test:v1 pass: 65 unit tests and 56 boundary fixtures. biome ci src/ reports no errors.
• The new tests mock pdf.js:
  • eval is always off
  • bytes are copied
  • the source key is stable
  • page sizes are read in parallel and returned in order
  • error classification
  • destroy runs once, and a load destroyed before pdf.js arrives never starts
  • every hook state transition: Retry, password missing then wrong then right, source change, unmount
  • the status component's states and accessibility
• Real rendering against a 200-page fixture was checked in the UN-4501 spike on this same pdf.js version. Browser tests come in UN-4507.

Screenshots

• None. There's no page to mount on 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

[Medium impact] The reviewed changes appear safe to merge.

Summary

Adds the v1 PDF loader, document hook, and viewer status screens.

• The PDF loader opens sources and returns ordered page sizes.
• The PDF hook tracks each load and lets callers retry or answer password prompts.
• The viewer shows a clear message for each state before a PDF is ready.

_{Reviews (4) · Last reviewed commit: "UN-4502 Load the same pdf.js build and w..." · Reviewed by Greptile}

[praveen-formido]

Reviewed as the base of the stack (lens: v1 styles and tokens, plus the loader logic). On the stack tip (68af05717) typecheck:v1, lint:v1 and the 173 v1 tests pass, and the current check-v1-styles.mjs from #2399 reports clean, so the --*-only style objects are fine throughout.

Two things I would fix before this goes in: the password/retry path re-downloads the document (comment on usePdfDocument.ts), and the legacy pdf.js build puts a second engine and worker in the bundle (comment on pdfjs.ts). The rest are smaller.

Stack note: these five fork from #2399 at 8028a7320, before its last commits. Once #2399 merges they retarget to main and need a rebase onto it (for example git rebase --onto main 8028a7320 from the bottom of the stack), otherwise the diffs keep showing the #2399 commits.

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
4 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