feat(score): ScoreViewer with locally-bundled pdf.js (clearfolio contract, PR 2/3)

[seonghobae]

Pull Request

Summary

• Adds ScoreViewer, the React viewer for the 악보 (Score PDF) feature (PR 2 of 3). It renders validated in-memory PDF bytes with pdf.js on a canvas, following the clearfolio viewer contract: a strict LOADING -> READY / LOADING -> FAILED -> retry state machine and a validated-resource-only rule (the component only accepts Uint8Array bytes via props; it never loads arbitrary URLs).
• Rehearsal-friendly controls: large touch targets for prev/next page (size-14 buttons), a "Page x of y" indicator, zoom in/out with clamping (0.5x-4x), and fit-width mode that re-renders on container resize via ResizeObserver.
• This PR is intentionally independent of PR 1 (feat(score): score PDF storage + IPC (clearfolio viewer contract, PR 1/3) #581, Tauri attach_score_pdf/read_score_pdf/remove_score_pdf). PR 3 will wire the IPC bytes into this component's data prop.
• New i18n keys were added for all user-visible copy in both en and ko locales.
• src/features/score/ScoreViewer.tsx is added to the measured coverage include list in apps/desktop/vite.config.ts and sits at 100% statements/branches/functions/lines.

CSP / worker bundling note

Tauri's CSP is script-src 'self', so the pdf.js worker must never come from a CDN. The worker is bundled locally by Vite:

• src/features/score/pdfjs.ts imports pdfjs-dist/build/pdf.worker.min.mjs?url and assigns it to GlobalWorkerOptions.workerSrc.
• Vite resolves this from the pinned local package and emits it as a same-origin asset (dist/assets/pdf.worker.min-<hash>.mjs, verified in an app-mode production build), which pdf.js loads as a module worker from 'self'. No CDN, no remote script, no data: script.
• The helper also copies the caller's bytes before handing them to pdf.js, because pdf.js transfers the buffer to the worker (which would detach the caller's copy and break retry).

Verification

• npm run lint (workspace eslint + docs/security-notes/security-gates/supply-chain/github-bootstrap/python checks) — pass
• npm run typecheck (tsc all workspaces + mypy) — pass
• npm run test (desktop vitest incl. coverage thresholds + pytest --cov-fail-under=100) — pass; see pre-existing flakiness note below
• npm run build — pass
• npm audit — 0 vulnerabilities

Pre-existing App.test.tsx flakiness (not introduced here)

On a clean origin/develop checkout, the full-suite vitest run --coverage intermittently fails up to 9 src/App.test.tsx cases with 5s timeouts under parallel load (all pass when the file runs in isolation). The same load-dependent behavior appears on this branch unchanged; the final full-suite runs here were fully green (133/133). The 12 new ScoreViewer tests pass deterministically in isolation and in the full suite.

Security Notes

Attack surface

• Untrusted input is the PDF byte stream passed via the data prop (in PR 3 this comes from the PR 1 Tauri read_score_pdf command, which validates the stored resource). Malformed or hostile PDFs are parsed by pdf.js inside a dedicated worker.

Trust boundary

• The viewer accepts bytes only from its caller (validated-resource-only). It exposes no URL/path prop, performs no network fetches, and never dereferences user-controlled URLs. Rendering is canvas-only; no HTML injection surface (dangerouslySetInnerHTML is banned repo-wide by check:security-gates).

Mitigations

• pdf.js pinned to an exact, audited version (pdfjs-dist@6.1.200, npm audit clean; not affected by CVE-2024-4367 which was fixed in 4.2.67).
• Worker is bundled from the local package and served same-origin, satisfying script-src 'self'; pdf.js isEvalSupported is irrelevant here because the strict CSP already blocks eval paths.
• Parse failures land in the FAILED state with the error message rendered as text content only.
• Loading tasks are destroyed on unmount/retry so a hostile document cannot outlive its component.

Test points

• ScoreViewer.test.tsx covers loading -> ready, loading -> failed -> retry -> ready, non-Error rejection stringification, page-navigation clamping at both bounds, zoom clamping (0.5x-4x), fit-width resize re-render, render-task cancellation, post-destroy getPage failure, and destroy-on-unmount with late resolve/reject ignored.

Dependency and Supply Chain

• No new direct dependency was added
• If a new dependency was added, this PR explains why it is needed
• runtime / dev / build / test classification is recorded
• alternatives were considered
• maintainer trust and update health were checked
• license fit was checked
• known security issues were checked
• transitive footprint impact was considered
• SBOM or supplemental inventory impact was recorded

New dependency admission evidence: pdfjs-dist@6.1.200 (exact pin)

• Why needed: render score PDFs on canvas inside the desktop WebView; no existing dependency can parse/rasterize PDF.
• Classification: runtime dependency of @bandscope/desktop (ships in the bundled frontend).
• Alternatives considered: react-pdf (wraps pdfjs-dist anyway, adds an extra maintainer surface for no benefit here), embedding a native PDF renderer via Tauri plugin (heavier, platform-divergent), <embed>/WebView-native PDF viewing (not available/portable in Tauri WebViews and violates the validated-resource-only contract). Direct pdfjs-dist is the smallest trusted surface.
• Maintainer trust / health: Mozilla's pdf.js, actively maintained (used by Firefox's built-in viewer), frequent releases; 6.1.200 is the current stable line.
• License: Apache-2.0 — compatible with the repository's licensing.
• Known security issues: npm audit reports 0 vulnerabilities for the workspace after admission. Historical CVE-2024-4367 (arbitrary JS via malicious PDF fonts) was patched in 4.2.67; 6.1.200 is unaffected, and the strict CSP (script-src 'self', no unsafe-eval) is a compensating control.
• Transitive footprint: zero required runtime dependencies (pdfjs-dist declares no dependencies). Its single optional dependency, @napi-rs/canvas (Node-side rasterization), lands in package-lock.json as optional: true platform packages but is never imported by, or bundled into, the browser build that ships in the app. Supply-chain cost is effectively a single Mozilla-owned package.
• Version policy: pinned exactly ("pdfjs-dist": "6.1.200", no range) per docs/security/dependency-policy.md; package-lock.json updated in this PR.
• SBOM impact: covered automatically by the npm lockfile-driven CycloneDX SBOM workflow; no bundled binary or model artifact is introduced, so supply-chain/supplemental-component-inventory.json is unchanged.
• Release/distribution risk: adds ~1.3 MB worker + ~0.4 MB library to the packaged frontend assets; all assets are same-origin and local, so no new network or update-channel exposure for public GitHub release flows.

i18n impact

• No user-visible string changed
• Korean and English locale impact was updated (10 new scoreViewer* keys in src/locales/en/common.json and src/locales/ko/common.json)

Reviewer checklist

• Gitflow target branch is correct (feat/score-pdf-viewer -> develop)
• protected-branch rules were not weakened
• required checks are expected to stay green

🤖 Generated with Claude Code

https://claude.ai/code/session_01RjGVapDZ3k7V7zKYk16P4C

[opencode-agent]

OpenCode Review Overview

• Head SHA: 6050020d6cc4e069db869b7f37b728245feb1454
• Workflow run: 29176966698
• Workflow attempt: 1
• Gate result: APPROVE (approval step)

Pull request overview

OpenCode reviewed the current-head bounded evidence and found no blocking issues.

Findings

No blocking findings.

Summary

Approval sufficiency: bounded evidence supplied affirmative approval evidence for changed files, coverage/docstring posture, risk surfaces, and current-head verification; approval is not based merely on the absence of known blockers.
Verification posture: CodeGraph evidence was initialized and bounded current-head evidence reviewed for changed-file evidence including apps/desktop/package.json, apps/desktop/src/features/score/ScoreViewer.test.tsx, apps/desktop/src/features/score/ScoreViewer.tsx, apps/desktop/src/features/score/pdfjs.ts, apps/desktop/src/locales/en/common.json, and 3 more.
Linter/static: workflow/static review evidence is bounded by the current-head GitHub Checks gate and changed-file evidence.
TDD/regression: coverage execution evidence and focused changed hunks were reviewed from bounded-review-evidence.md.
Coverage: coverage execution evidence reports supported repository test suites passed.
Docstring coverage: coverage execution evidence reports configured repository docstring gates passed or docstring coverage was advisory.
DAG: CodeGraph/source-backed behavior map connects apps/desktop/package.json to the affected review, runtime, or workflow path and required checks.
PoC/execution: coverage-evidence job executed on the current head and reported PASS.
DDD/domain: workflow and repository-governance invariants were reviewed against changed files in bounded evidence.
CDD/context: CodeGraph evidence, changed-file history, and focused hunks were reviewed from bounded-review-evidence.md.
Similar issues: changed-file history evidence was reviewed for comparable local precedents.
Claim/concept check: bounded evidence, repository source, current-head workflow evidence, and, where numeric, scientific, statistical, or literature-backed claims are affected, original-paper/formula evidence and parameter-recovery expectations were used for claims.
Standards search: standards and external-source checks are delegated to configured OpenCode web_search/Context7/DeepWiki sources when applicable; no evidence-backed standards blocker is present in bounded evidence.
Compatibility/convention: changed workflow/script conventions, object naming, and reserved-word safety for schema/API/config/code surfaces were checked in bounded evidence.
Breaking-change/backcompat: deployment evidence and changed-file history were checked for backward-compatibility risk.
Performance: changed surfaces were checked for performance risk in bounded evidence.
Developer experience: changed automation, review, test, setup, and maintenance surfaces were checked for helpful or obstructive DX impact in bounded evidence.
User experience: connected user, operator, API, CLI, documentation, review-comment, status-check, rendering, and workflow-reader behavior was checked for contradictions against code, docs, and tests in bounded evidence.
Visual/DOM: Playwright visual, DOM locator, ARIA snapshot, console, and responsive evidence were checked when a web UI surface was present; for non-web surfaces, API/CLI/log/docs/workflow interaction evidence was reviewed instead.
Accessibility/i18n: accessibility, localization, and human-readable text surfaces were checked where UI, CLI, API message, docs, logs, or review text changed.
Supply-chain/license: dependency, package, model, container, and external-tool changes were checked in bounded evidence.
Packaging: package, build, test, lint, and security contracts were checked in bounded evidence.
Security/privacy: workflow-token, review-gate, and repository-automation security/privacy boundaries were checked in bounded evidence.

• Result: APPROVE
• Reason: PR introduces a well-tested ScoreViewer component with PDF.js integration, adhering to repository standards.
• Head SHA: 6050020d6cc4e069db869b7f37b728245feb1454
• Workflow run: 29176966698
• Workflow attempt: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (8 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (8 files)"]
  R1 --> V1["required checks"]

Loading

[opencode-agent]

Pull request overview

OpenCode reviewed the current-head bounded evidence and found no blocking issues.

Findings

No blocking findings.

Summary

Approval sufficiency: bounded evidence supplied affirmative approval evidence for changed files, coverage/docstring posture, risk surfaces, and current-head verification; approval is not based merely on the absence of known blockers.
Verification posture: CodeGraph evidence was initialized and bounded current-head evidence reviewed for changed-file evidence including apps/desktop/package.json, apps/desktop/src/features/score/ScoreViewer.test.tsx, apps/desktop/src/features/score/ScoreViewer.tsx, apps/desktop/src/features/score/pdfjs.ts, apps/desktop/src/locales/en/common.json, and 3 more.
Linter/static: workflow/static review evidence is bounded by the current-head GitHub Checks gate and changed-file evidence.
TDD/regression: coverage execution evidence and focused changed hunks were reviewed from bounded-review-evidence.md.
Coverage: coverage execution evidence reports supported repository test suites passed.
Docstring coverage: coverage execution evidence reports configured repository docstring gates passed or docstring coverage was advisory.
DAG: CodeGraph/source-backed behavior map connects apps/desktop/package.json to the affected review, runtime, or workflow path and required checks.
PoC/execution: coverage-evidence job executed on the current head and reported PASS.
DDD/domain: workflow and repository-governance invariants were reviewed against changed files in bounded evidence.
CDD/context: CodeGraph evidence, changed-file history, and focused hunks were reviewed from bounded-review-evidence.md.
Similar issues: changed-file history evidence was reviewed for comparable local precedents.
Claim/concept check: bounded evidence, repository source, current-head workflow evidence, and, where numeric, scientific, statistical, or literature-backed claims are affected, original-paper/formula evidence and parameter-recovery expectations were used for claims.
Standards search: standards and external-source checks are delegated to configured OpenCode web_search/Context7/DeepWiki sources when applicable; no evidence-backed standards blocker is present in bounded evidence.
Compatibility/convention: changed workflow/script conventions, object naming, and reserved-word safety for schema/API/config/code surfaces were checked in bounded evidence.
Breaking-change/backcompat: deployment evidence and changed-file history were checked for backward-compatibility risk.
Performance: changed surfaces were checked for performance risk in bounded evidence.
Developer experience: changed automation, review, test, setup, and maintenance surfaces were checked for helpful or obstructive DX impact in bounded evidence.
User experience: connected user, operator, API, CLI, documentation, review-comment, status-check, rendering, and workflow-reader behavior was checked for contradictions against code, docs, and tests in bounded evidence.
Visual/DOM: Playwright visual, DOM locator, ARIA snapshot, console, and responsive evidence were checked when a web UI surface was present; for non-web surfaces, API/CLI/log/docs/workflow interaction evidence was reviewed instead.
Accessibility/i18n: accessibility, localization, and human-readable text surfaces were checked where UI, CLI, API message, docs, logs, or review text changed.
Supply-chain/license: dependency, package, model, container, and external-tool changes were checked in bounded evidence.
Packaging: package, build, test, lint, and security contracts were checked in bounded evidence.
Security/privacy: workflow-token, review-gate, and repository-automation security/privacy boundaries were checked in bounded evidence.

• Result: APPROVE
• Reason: PR introduces a well-tested ScoreViewer component with PDF.js integration, adhering to repository standards.
• Head SHA: 6050020d6cc4e069db869b7f37b728245feb1454
• Workflow run: 29176966698
• Workflow attempt: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (8 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (8 files)"]
  R1 --> V1["required checks"]

Loading