From 3fb96a3f01a127520e726fbe99023dafa4701f14 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 21:48:56 +0900
Subject: [PATCH 01/15] test(temporal): require semantic stability identifiers

---
 .../tests/test_temporal_naming_contract.py    | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 services/analysis-engine/tests/test_temporal_naming_contract.py

diff --git a/services/analysis-engine/tests/test_temporal_naming_contract.py b/services/analysis-engine/tests/test_temporal_naming_contract.py
new file mode 100644
index 000000000..053eab323
--- /dev/null
+++ b/services/analysis-engine/tests/test_temporal_naming_contract.py
@@ -0,0 +1,73 @@
+"""Naming-contract regression tests for temporal stability internals."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+
+TEMPORAL_STABILITY_MODULE = (
+    Path(__file__).resolve().parents[1]
+    / "src"
+    / "bandscope_analysis"
+    / "temporal"
+    / "stability.py"
+)
+
+LEGACY_UNDERSPECIFIED_IDENTIFIERS = frozenset(
+    {
+        "after",
+        "beats",
+        "before",
+        "bpms",
+        "changes",
+        "cv",
+        "deviation",
+        "entry",
+        "flagged",
+        "index",
+        "intervals",
+        "run",
+        "ties",
+        "window",
+    }
+)
+
+REQUIRED_SEMANTIC_IDENTIFIERS = frozenset(
+    {
+        "after_bpm_median",
+        "beat_intervals",
+        "beat_times_array",
+        "before_bpm_median",
+        "bpm_variation_coefficient",
+        "comparison_window_beats",
+        "flagged_boundaries",
+        "flagged_boundary",
+        "local_bpm_values",
+        "relative_bpm_deviation",
+        "tempo_change_run",
+        "tempo_changes",
+        "tied_boundaries",
+    }
+)
+
+
+def _module_identifiers(source_text: str) -> set[str]:
+    """Return organization-owned Python identifiers declared or referenced by the module."""
+    syntax_tree = ast.parse(source_text)
+    identifiers = {
+        node.id for node in ast.walk(syntax_tree) if isinstance(node, ast.Name)
+    }
+    identifiers.update(
+        node.arg for node in ast.walk(syntax_tree) if isinstance(node, ast.arg)
+    )
+    return identifiers
+
+
+def test_temporal_stability_internal_identifiers_are_semantically_specific() -> None:
+    """Require bounded-context names instead of generic one-word temporal identifiers."""
+    source_text = TEMPORAL_STABILITY_MODULE.read_text(encoding="utf-8")
+    identifiers = _module_identifiers(source_text)
+
+    assert not LEGACY_UNDERSPECIFIED_IDENTIFIERS.intersection(identifiers)
+    assert REQUIRED_SEMANTIC_IDENTIFIERS.issubset(identifiers)

From 3f08af6eadf8bb4defcc5ba8020d5f142cee14aa Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 21:49:46 +0900
Subject: [PATCH 02/15] refactor(temporal): use semantic stability identifiers

---
 .../bandscope_analysis/temporal/stability.py  | 140 +++++++++++-------
 1 file changed, 88 insertions(+), 52 deletions(-)

diff --git a/services/analysis-engine/src/bandscope_analysis/temporal/stability.py b/services/analysis-engine/src/bandscope_analysis/temporal/stability.py
index 316b36602..a6863499f 100644
--- a/services/analysis-engine/src/bandscope_analysis/temporal/stability.py
+++ b/services/analysis-engine/src/bandscope_analysis/temporal/stability.py
@@ -94,25 +94,28 @@ def _safe_default() -> TempoStability:
     }
 
 
-def _classify_stability(cv: float) -> Literal["steady", "loose", "variable"]:
+def _classify_stability(
+    bpm_variation_coefficient: float,
+) -> Literal["steady", "loose", "variable"]:
     """Map a coefficient of variation to a stability label.
 
     Args:
-        cv: Coefficient of variation of the local BPM series.
+        bpm_variation_coefficient: Coefficient of variation of the local BPM series.
 
     Returns:
-        "steady" if cv < 0.04, "loose" if cv < 0.10, else "variable".
+        "steady" if the coefficient is below 0.04, "loose" if it is below
+        0.10, else "variable".
     """
-    if cv < STEADY_CV_THRESHOLD:
+    if bpm_variation_coefficient < STEADY_CV_THRESHOLD:
         return "steady"
-    if cv < LOOSE_CV_THRESHOLD:
+    if bpm_variation_coefficient < LOOSE_CV_THRESHOLD:
         return "loose"
     return "variable"
 
 
 def _summarize_run(
-    run: list[tuple[int, float, float, float]],
-    beats: NDArray[np.float64],
+    tempo_change_run: list[tuple[int, float, float, float]],
+    beat_times_array: NDArray[np.float64],
 ) -> TempoChange:
     """Collapse a run of adjacent flagged boundaries into one tempo change.
 
@@ -121,26 +124,31 @@ def _summarize_run(
     chosen so the reported time sits at the center of the transition.
 
     Args:
-        run: Adjacent flagged boundaries as (index, deviation, before
-            median BPM, after median BPM) tuples, in ascending index order.
-        beats: Beat times in seconds, aligned with boundary indices.
+        tempo_change_run: Adjacent flagged boundaries as (index, deviation,
+            before median BPM, after median BPM) tuples, in ascending index
+            order.
+        beat_times_array: Beat times in seconds, aligned with boundary indices.
 
     Returns:
         The merged TempoChange with rounded outputs.
     """
-    max_deviation = max(entry[1] for entry in run)
-    ties = [entry for entry in run if entry[1] >= max_deviation - 1e-9]
-    index, _, before_bpm, after_bpm = ties[len(ties) // 2]
+    max_deviation = max(flagged_boundary[1] for flagged_boundary in tempo_change_run)
+    tied_boundaries = [
+        flagged_boundary
+        for flagged_boundary in tempo_change_run
+        if flagged_boundary[1] >= max_deviation - 1e-9
+    ]
+    boundary_index, _, before_bpm, after_bpm = tied_boundaries[len(tied_boundaries) // 2]
     return {
-        "time": round(float(beats[index]), 3),
+        "time": round(float(beat_times_array[boundary_index]), 3),
         "from_bpm": round(before_bpm, 1),
         "to_bpm": round(after_bpm, 1),
     }
 
 
 def _detect_tempo_changes(
-    bpms: NDArray[np.float64],
-    beats: NDArray[np.float64],
+    local_bpm_values: NDArray[np.float64],
+    beat_times_array: NDArray[np.float64],
 ) -> list[TempoChange]:
     """Detect sustained tempo shifts in a local BPM series.
 
@@ -150,37 +158,65 @@ def _detect_tempo_changes(
     merged into a single change.
 
     Args:
-        bpms: Per-beat local BPM series (one value per inter-beat
-            interval); ``bpms[i]`` spans beats ``i`` to ``i + 1``.
-        beats: Beat times in seconds; ``len(beats) == len(bpms) + 1``.
+        local_bpm_values: Per-beat local BPM series (one value per inter-beat
+            interval); each value spans one consecutive beat interval.
+        beat_times_array: Beat times in seconds; there is one more beat time
+            than local BPM value.
 
     Returns:
         Detected tempo changes in chronological order; empty if the track
         is too short for a robust window comparison.
     """
-    n_bpm = len(bpms)
-    window = min(CHANGE_WINDOW_BEATS, n_bpm // 2)
-    if window < MIN_CHANGE_WINDOW_BEATS:
+    bpm_value_count = len(local_bpm_values)
+    comparison_window_beats = min(CHANGE_WINDOW_BEATS, bpm_value_count // 2)
+    if comparison_window_beats < MIN_CHANGE_WINDOW_BEATS:
         return []
 
-    flagged: list[tuple[int, float, float, float]] = []
-    for k in range(window, n_bpm - window + 1):
-        before = float(np.median(bpms[k - window : k]))
-        after = float(np.median(bpms[k : k + window]))
-        deviation = abs(after - before) / before
-        if deviation > CHANGE_RATIO_THRESHOLD:
-            flagged.append((k, deviation, before, after))
-
-    changes: list[TempoChange] = []
-    run: list[tuple[int, float, float, float]] = []
-    for entry in flagged:
-        if run and entry[0] != run[-1][0] + 1:
-            changes.append(_summarize_run(run, beats))
-            run = []
-        run.append(entry)
-    if run:
-        changes.append(_summarize_run(run, beats))
-    return changes
+    flagged_boundaries: list[tuple[int, float, float, float]] = []
+    for boundary_index in range(
+        comparison_window_beats,
+        bpm_value_count - comparison_window_beats + 1,
+    ):
+        before_bpm_median = float(
+            np.median(
+                local_bpm_values[
+                    boundary_index - comparison_window_beats : boundary_index
+                ]
+            )
+        )
+        after_bpm_median = float(
+            np.median(
+                local_bpm_values[
+                    boundary_index : boundary_index + comparison_window_beats
+                ]
+            )
+        )
+        relative_bpm_deviation = (
+            abs(after_bpm_median - before_bpm_median) / before_bpm_median
+        )
+        if relative_bpm_deviation > CHANGE_RATIO_THRESHOLD:
+            flagged_boundaries.append(
+                (
+                    boundary_index,
+                    relative_bpm_deviation,
+                    before_bpm_median,
+                    after_bpm_median,
+                )
+            )
+
+    tempo_changes: list[TempoChange] = []
+    tempo_change_run: list[tuple[int, float, float, float]] = []
+    for flagged_boundary in flagged_boundaries:
+        if (
+            tempo_change_run
+            and flagged_boundary[0] != tempo_change_run[-1][0] + 1
+        ):
+            tempo_changes.append(_summarize_run(tempo_change_run, beat_times_array))
+            tempo_change_run = []
+        tempo_change_run.append(flagged_boundary)
+    if tempo_change_run:
+        tempo_changes.append(_summarize_run(tempo_change_run, beat_times_array))
+    return tempo_changes
 
 
 def analyze_tempo_stability(
@@ -203,28 +239,28 @@ def analyze_tempo_stability(
         beats, non-finite values, or non-increasing times) yields the
         safe default instead of raising.
     """
-    beats: NDArray[np.float64] = np.asarray(beat_times, dtype=np.float64)
-    if beats.ndim != 1 or len(beats) < MIN_BEATS:
+    beat_times_array: NDArray[np.float64] = np.asarray(beat_times, dtype=np.float64)
+    if beat_times_array.ndim != 1 or len(beat_times_array) < MIN_BEATS:
         return _safe_default()
-    if not np.all(np.isfinite(beats)):
+    if not np.all(np.isfinite(beat_times_array)):
         return _safe_default()
 
-    intervals = np.diff(beats)
-    if not np.all(intervals > 0.0):
+    beat_intervals = np.diff(beat_times_array)
+    if not np.all(beat_intervals > 0.0):
         return _safe_default()
 
     with np.errstate(divide="ignore", over="ignore"):
-        bpms: NDArray[np.float64] = 60.0 / intervals
-    if not np.all(np.isfinite(bpms)):
+        local_bpm_values: NDArray[np.float64] = 60.0 / beat_intervals
+    if not np.all(np.isfinite(local_bpm_values)):
         return _safe_default()
 
-    bpm_median = float(np.median(bpms))
-    bpm_stdev = float(np.std(bpms))
-    cv = bpm_stdev / bpm_median
+    bpm_median = float(np.median(local_bpm_values))
+    bpm_stdev = float(np.std(local_bpm_values))
+    bpm_variation_coefficient = bpm_stdev / bpm_median
 
     return {
         "bpm_median": round(bpm_median, 2),
         "bpm_stdev": round(bpm_stdev, 2),
-        "stability": _classify_stability(cv),
-        "tempo_changes": _detect_tempo_changes(bpms, beats),
+        "stability": _classify_stability(bpm_variation_coefficient),
+        "tempo_changes": _detect_tempo_changes(local_bpm_values, beat_times_array),
     }

From 3c6bb2d0a34b9f41b0f4986b6bd9ddf7bc99e1b9 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 21:50:29 +0900
Subject: [PATCH 03/15] test(temporal): keep naming guard semantic

---
 .../tests/test_temporal_naming_contract.py           | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/services/analysis-engine/tests/test_temporal_naming_contract.py b/services/analysis-engine/tests/test_temporal_naming_contract.py
index 053eab323..919e01665 100644
--- a/services/analysis-engine/tests/test_temporal_naming_contract.py
+++ b/services/analysis-engine/tests/test_temporal_naming_contract.py
@@ -55,19 +55,19 @@
 def _module_identifiers(source_text: str) -> set[str]:
     """Return organization-owned Python identifiers declared or referenced by the module."""
     syntax_tree = ast.parse(source_text)
-    identifiers = {
+    module_identifiers = {
         node.id for node in ast.walk(syntax_tree) if isinstance(node, ast.Name)
     }
-    identifiers.update(
+    module_identifiers.update(
         node.arg for node in ast.walk(syntax_tree) if isinstance(node, ast.arg)
     )
-    return identifiers
+    return module_identifiers
 
 
 def test_temporal_stability_internal_identifiers_are_semantically_specific() -> None:
     """Require bounded-context names instead of generic one-word temporal identifiers."""
     source_text = TEMPORAL_STABILITY_MODULE.read_text(encoding="utf-8")
-    identifiers = _module_identifiers(source_text)
+    module_identifiers = _module_identifiers(source_text)
 
-    assert not LEGACY_UNDERSPECIFIED_IDENTIFIERS.intersection(identifiers)
-    assert REQUIRED_SEMANTIC_IDENTIFIERS.issubset(identifiers)
+    assert not LEGACY_UNDERSPECIFIED_IDENTIFIERS.intersection(module_identifiers)
+    assert REQUIRED_SEMANTIC_IDENTIFIERS.issubset(module_identifiers)

From 4e0b2b5133e673f670e4d685500d2e1fa1afd544 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 21:58:15 +0900
Subject: [PATCH 04/15] test(score): require semantic PDF byte prop

---
 .../src/features/score/ScoreViewer.test.tsx   | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.test.tsx b/apps/desktop/src/features/score/ScoreViewer.test.tsx
index 3ac2dd605..6f06ea55a 100644
--- a/apps/desktop/src/features/score/ScoreViewer.test.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.test.tsx
@@ -86,9 +86,9 @@ describe("ScoreViewer", () => {
     vi.unstubAllGlobals();
   });
 
-  it("renders the empty placeholder without loading when no data is attached", () => {
+  it("renders the empty placeholder without loading when no score PDF bytes are attached", () => {
     const onStatusChange = vi.fn();
-    render(<ScoreViewer data={null} onStatusChange={onStatusChange} />);
+    render(<ScoreViewer scorePdfBytes={null} onStatusChange={onStatusChange} />);
 
     expect(
       screen.getByText("No score PDF attached. Attach a validated score PDF to view it here.")
@@ -103,7 +103,7 @@ describe("ScoreViewer", () => {
     const { doc, page } = createFakeDocument(3);
     const onStatusChange = vi.fn();
 
-    render(<ScoreViewer data={SAMPLE_BYTES} onStatusChange={onStatusChange} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} onStatusChange={onStatusChange} />);
 
     expect(screen.getByRole("status")).toBeInTheDocument();
     expect(screen.getByText("Loading score PDF...")).toBeInTheDocument();
@@ -128,7 +128,7 @@ describe("ScoreViewer", () => {
     const { doc } = createFakeDocument(1);
     mockLoadTaskOnce(Promise.resolve(doc));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} fileName="setlist-opener.pdf" />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} fileName="setlist-opener.pdf" />);
 
     expect(await screen.findByText("setlist-opener.pdf")).toBeInTheDocument();
   });
@@ -139,7 +139,7 @@ describe("ScoreViewer", () => {
     mockLoadTaskOnce(Promise.resolve(doc));
     const onStatusChange = vi.fn();
 
-    render(<ScoreViewer data={SAMPLE_BYTES} onStatusChange={onStatusChange} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} onStatusChange={onStatusChange} />);
 
     expect(await screen.findByRole("alert")).toBeInTheDocument();
     expect(screen.getByText("Could not display the score")).toBeInTheDocument();
@@ -159,7 +159,7 @@ describe("ScoreViewer", () => {
   it("stringifies non-Error load failures", async () => {
     mockLoadTaskOnce(Promise.reject("password protected"));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByRole("alert")).toBeInTheDocument();
     expect(screen.getByText("password protected")).toBeInTheDocument();
@@ -169,7 +169,7 @@ describe("ScoreViewer", () => {
     const { doc } = createFakeDocument(3);
     mockLoadTaskOnce(Promise.resolve(doc));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 3")).toBeInTheDocument();
     const previousButton = screen.getByRole("button", { name: "Previous page" });
@@ -198,7 +198,7 @@ describe("ScoreViewer", () => {
     const { doc, page } = createFakeDocument(1);
     mockLoadTaskOnce(Promise.resolve(doc));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 1")).toBeInTheDocument();
     const zoomInButton = screen.getByRole("button", { name: "Zoom in" });
@@ -245,7 +245,7 @@ describe("ScoreViewer", () => {
     const { doc, page } = createFakeDocument(1);
     mockLoadTaskOnce(Promise.resolve(doc));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 1")).toBeInTheDocument();
 
@@ -278,7 +278,7 @@ describe("ScoreViewer", () => {
     const { doc } = createFakeDocument(1, page);
     mockLoadTaskOnce(Promise.resolve(doc));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 1")).toBeInTheDocument();
     await waitFor(() => {
@@ -294,7 +294,7 @@ describe("ScoreViewer", () => {
     } as unknown as PDFDocumentProxy;
     mockLoadTaskOnce(Promise.resolve(doc));
 
-    render(<ScoreViewer data={SAMPLE_BYTES} />);
+    render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 1")).toBeInTheDocument();
     await waitFor(() => {
@@ -311,7 +311,7 @@ describe("ScoreViewer", () => {
     const onStatusChange = vi.fn();
 
     const { unmount } = render(
-      <ScoreViewer data={SAMPLE_BYTES} onStatusChange={onStatusChange} />
+      <ScoreViewer scorePdfBytes={SAMPLE_BYTES} onStatusChange={onStatusChange} />
     );
     unmount();
 
@@ -330,7 +330,7 @@ describe("ScoreViewer", () => {
     const onStatusChange = vi.fn();
 
     const { unmount } = render(
-      <ScoreViewer data={SAMPLE_BYTES} onStatusChange={onStatusChange} />
+      <ScoreViewer scorePdfBytes={SAMPLE_BYTES} onStatusChange={onStatusChange} />
     );
     unmount();
 

From 492346e2183a6bc0714377acf9a58fdab32169c4 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 21:59:15 +0900
Subject: [PATCH 05/15] refactor(score): use semantic viewer identifiers

---
 .../src/features/score/ScoreViewer.tsx        | 104 +++++++++---------
 1 file changed, 55 insertions(+), 49 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.tsx b/apps/desktop/src/features/score/ScoreViewer.tsx
index 82692469e..fa34ef066 100644
--- a/apps/desktop/src/features/score/ScoreViewer.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.tsx
@@ -27,7 +27,7 @@ export interface ScoreViewerProps {
    * loads arbitrary URLs; callers (PR3 wires Tauri `read_score_pdf`) must
    * hand it bytes they already validated.
    */
-  data: Uint8Array | null;
+  scorePdfBytes: Uint8Array | null;
   /** Optional display name of the attached score file. */
   fileName?: string;
   /** Optional observer notified on every LOADING/FAILED/READY transition. */
@@ -45,14 +45,14 @@ const MAX_ZOOM = 4;
  * error with retry, READY canvas) plus rehearsal-friendly page navigation
  * and zoom in/out/fit-width controls.
  */
-export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps) {
-  const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
-  const [status, setStatus] = useState<ScoreViewerStatus>("LOADING");
+export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreViewerProps) {
+  const scoreTranslator = useMemo(() => createTranslator(detectPreferredLocale()), []);
+  const [viewerStatus, setViewerStatus] = useState<ScoreViewerStatus>("LOADING");
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const [pdfDocument, setPdfDocument] = useState<PDFDocumentProxy | null>(null);
   const [pageNumber, setPageNumber] = useState(1);
   const [pageCount, setPageCount] = useState(0);
-  const [zoom, setZoom] = useState(1);
+  const [zoomScale, setZoomScale] = useState(1);
   const [fitWidth, setFitWidth] = useState(true);
   const [containerWidth, setContainerWidth] = useState(0);
   const [retryToken, setRetryToken] = useState(0);
@@ -60,22 +60,22 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
   const containerRef = useRef<HTMLDivElement | null>(null);
 
   useEffect(() => {
-    if (data !== null) {
-      onStatusChange?.(status);
+    if (scorePdfBytes !== null) {
+      onStatusChange?.(viewerStatus);
     }
-  }, [data, status, onStatusChange]);
+  }, [scorePdfBytes, viewerStatus, onStatusChange]);
 
   useEffect(() => {
-    if (data === null) {
+    if (scorePdfBytes === null) {
       return;
     }
 
     let cancelled = false;
-    setStatus("LOADING");
+    setViewerStatus("LOADING");
     setErrorMessage(null);
     setPdfDocument(null);
 
-    const loadingTask = loadScorePdf(data);
+    const loadingTask = loadScorePdf(scorePdfBytes);
     loadingTask.promise
       .then((loadedDocument) => {
         if (cancelled) {
@@ -84,40 +84,44 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
         setPdfDocument(loadedDocument);
         setPageCount(loadedDocument.numPages);
         setPageNumber(1);
-        setStatus("READY");
+        setViewerStatus("READY");
       })
       .catch((error: unknown) => {
         if (cancelled) {
           return;
         }
         setErrorMessage(error instanceof Error ? error.message : String(error));
-        setStatus("FAILED");
+        setViewerStatus("FAILED");
       });
 
     return () => {
       cancelled = true;
       void loadingTask.destroy().catch(() => undefined);
     };
-  }, [data, retryToken]);
+  }, [scorePdfBytes, retryToken]);
 
   useEffect(() => {
-    const container = containerRef.current;
-    if (status !== "READY" || !container || typeof ResizeObserver === "undefined") {
+    const viewerContainer = containerRef.current;
+    if (
+      viewerStatus !== "READY" ||
+      !viewerContainer ||
+      typeof ResizeObserver === "undefined"
+    ) {
       return;
     }
 
-    const observer = new ResizeObserver((entries) => {
+    const resizeObserver = new ResizeObserver((entries) => {
       for (const entry of entries) {
         setContainerWidth(entry.contentRect.width);
       }
     });
-    observer.observe(container);
-    return () => observer.disconnect();
-  }, [status]);
+    resizeObserver.observe(viewerContainer);
+    return () => resizeObserver.disconnect();
+  }, [viewerStatus]);
 
   useEffect(() => {
-    const canvas = canvasRef.current;
-    if (status !== "READY" || !pdfDocument || !canvas) {
+    const scoreCanvas = canvasRef.current;
+    if (viewerStatus !== "READY" || !pdfDocument || !scoreCanvas) {
       return;
     }
 
@@ -126,17 +130,17 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
 
     pdfDocument
       .getPage(pageNumber)
-      .then((page) => {
+      .then((pdfPage) => {
         if (cancelled) {
           return;
         }
-        const baseViewport = page.getViewport({ scale: 1 });
-        const scale =
-          fitWidth && containerWidth > 0 ? containerWidth / baseViewport.width : zoom;
-        const viewport = page.getViewport({ scale });
-        canvas.width = Math.floor(viewport.width);
-        canvas.height = Math.floor(viewport.height);
-        renderTask = page.render({ canvas, viewport });
+        const baseViewport = pdfPage.getViewport({ scale: 1 });
+        const viewportScale =
+          fitWidth && containerWidth > 0 ? containerWidth / baseViewport.width : zoomScale;
+        const pageViewport = pdfPage.getViewport({ scale: viewportScale });
+        scoreCanvas.width = Math.floor(pageViewport.width);
+        scoreCanvas.height = Math.floor(pageViewport.height);
+        renderTask = pdfPage.render({ canvas: scoreCanvas, viewport: pageViewport });
         renderTask.promise.catch(() => {
           // Cancelled renders (rapid page/zoom changes) are expected.
         });
@@ -149,7 +153,7 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
       cancelled = true;
       renderTask?.cancel();
     };
-  }, [status, pdfDocument, pageNumber, zoom, fitWidth, containerWidth]);
+  }, [viewerStatus, pdfDocument, pageNumber, zoomScale, fitWidth, containerWidth]);
 
   /** Move to the previous page, clamped at the first page. */
   const goToPreviousPage = () => {
@@ -164,13 +168,13 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
   /** Switch to manual zoom and enlarge, clamped at the maximum scale. */
   const zoomIn = () => {
     setFitWidth(false);
-    setZoom((current) => Math.min(MAX_ZOOM, current * ZOOM_STEP));
+    setZoomScale((current) => Math.min(MAX_ZOOM, current * ZOOM_STEP));
   };
 
   /** Switch to manual zoom and shrink, clamped at the minimum scale. */
   const zoomOut = () => {
     setFitWidth(false);
-    setZoom((current) => Math.max(MIN_ZOOM, current / ZOOM_STEP));
+    setZoomScale((current) => Math.max(MIN_ZOOM, current / ZOOM_STEP));
   };
 
   /** Re-enable fit-width so the page tracks the container size. */
@@ -179,24 +183,24 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
   };
 
   /** Re-run the load state machine with the same validated bytes. */
-  const retry = () => {
+  const retryPdfLoad = () => {
     setRetryToken((current) => current + 1);
   };
 
-  if (data === null) {
+  if (scorePdfBytes === null) {
     return (
       <Card className="border-2 border-dashed border-cyan-300/20 bg-slate-950/50 backdrop-blur-xl">
         <CardContent className="flex flex-col items-center justify-center py-16 text-center">
           <div className="mb-4 rounded-full border border-cyan-300/30 bg-cyan-300/10 p-4 text-cyan-200">
             <FileMusic className="size-8" aria-hidden="true" />
           </div>
-          <p className="max-w-sm text-slate-400">{t("scoreViewerEmpty")}</p>
+          <p className="max-w-sm text-slate-400">{scoreTranslator("scoreViewerEmpty")}</p>
         </CardContent>
       </Card>
     );
   }
 
-  if (status === "LOADING") {
+  if (viewerStatus === "LOADING") {
     return (
       <Card
         className="border-cyan-300/20 bg-slate-950/75 backdrop-blur-xl"
@@ -206,13 +210,13 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
       >
         <CardContent className="flex flex-col items-center justify-center py-16 text-center">
           <Loader2 className="mb-4 size-10 animate-spin text-cyan-300" aria-hidden="true" />
-          <p className="animate-pulse text-slate-400">{t("scoreViewerLoading")}</p>
+          <p className="animate-pulse text-slate-400">{scoreTranslator("scoreViewerLoading")}</p>
         </CardContent>
       </Card>
     );
   }
 
-  if (status === "FAILED") {
+  if (viewerStatus === "FAILED") {
     return (
       <Card
         className="border-rose-300/30 bg-rose-950/40 backdrop-blur-xl"
@@ -223,22 +227,24 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
           <div className="mb-4 rounded-full border border-rose-300/30 bg-rose-300/10 p-4 text-rose-200">
             <AlertCircle className="size-8" aria-hidden="true" />
           </div>
-          <h3 className="mb-2 text-lg font-black text-rose-100">{t("scoreViewerFailedTitle")}</h3>
+          <h3 className="mb-2 text-lg font-black text-rose-100">
+            {scoreTranslator("scoreViewerFailedTitle")}
+          </h3>
           {errorMessage && (
             <p className="mb-4 rounded-md bg-rose-300/10 px-4 py-2 text-sm font-medium text-rose-100">
               {errorMessage}
             </p>
           )}
-          <Button variant="outline" className="h-12 min-w-32 text-base" onClick={retry}>
+          <Button variant="outline" className="h-12 min-w-32 text-base" onClick={retryPdfLoad}>
             <RotateCw aria-hidden="true" />
-            {t("scoreViewerRetry")}
+            {scoreTranslator("scoreViewerRetry")}
           </Button>
         </CardContent>
       </Card>
     );
   }
 
-  const pageIndicator = t("scoreViewerPageIndicator")
+  const pageIndicator = scoreTranslator("scoreViewerPageIndicator")
     .replace("{current}", String(pageNumber))
     .replace("{total}", String(pageCount));
 
@@ -257,7 +263,7 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
               variant="outline"
               size="icon-lg"
               className="size-12"
-              aria-label={t("scoreViewerZoomOut")}
+              aria-label={scoreTranslator("scoreViewerZoomOut")}
               onClick={zoomOut}
             >
               <ZoomOut aria-hidden="true" />
@@ -266,7 +272,7 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
               variant="outline"
               size="icon-lg"
               className="size-12"
-              aria-label={t("scoreViewerZoomIn")}
+              aria-label={scoreTranslator("scoreViewerZoomIn")}
               onClick={zoomIn}
             >
               <ZoomIn aria-hidden="true" />
@@ -274,12 +280,12 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
             <Button
               variant={fitWidth ? "secondary" : "outline"}
               className="h-12 px-4 text-base"
-              aria-label={t("scoreViewerFitWidth")}
+              aria-label={scoreTranslator("scoreViewerFitWidth")}
               aria-pressed={fitWidth}
               onClick={fitToWidth}
             >
               <MoveHorizontal aria-hidden="true" />
-              {t("scoreViewerFitWidth")}
+              {scoreTranslator("scoreViewerFitWidth")}
             </Button>
           </div>
         </div>
@@ -291,7 +297,7 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
             variant="outline"
             size="icon-lg"
             className="size-14"
-            aria-label={t("scoreViewerPrevPage")}
+            aria-label={scoreTranslator("scoreViewerPrevPage")}
             disabled={pageNumber <= 1}
             onClick={goToPreviousPage}
           >
@@ -304,7 +310,7 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
             variant="outline"
             size="icon-lg"
             className="size-14"
-            aria-label={t("scoreViewerNextPage")}
+            aria-label={scoreTranslator("scoreViewerNextPage")}
             disabled={pageNumber >= pageCount}
             onClick={goToNextPage}
           >

From 3c68966cc3251f4e389382d033fb96b02f31863b Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 22:00:06 +0900
Subject: [PATCH 06/15] refactor(score): propagate semantic PDF byte prop

---
 apps/desktop/src/features/score/ScoreView.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/score/ScoreView.tsx b/apps/desktop/src/features/score/ScoreView.tsx
index 72732450f..cead34022 100644
--- a/apps/desktop/src/features/score/ScoreView.tsx
+++ b/apps/desktop/src/features/score/ScoreView.tsx
@@ -223,7 +223,7 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
           </CardContent>
         </Card>
       ) : (
-        <ScoreViewer data={pdfBytes} fileName={selected?.fileName} />
+        <ScoreViewer scorePdfBytes={pdfBytes} fileName={selected?.fileName} />
       )}
     </section>
   );

From 3562504091802b658fb9df7645a7e35009dff04b Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 22:00:31 +0900
Subject: [PATCH 07/15] refactor(score): isolate PDF.js data field at adapter

---
 apps/desktop/src/features/score/pdfjs.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/features/score/pdfjs.ts b/apps/desktop/src/features/score/pdfjs.ts
index ec622d42d..280d09946 100644
--- a/apps/desktop/src/features/score/pdfjs.ts
+++ b/apps/desktop/src/features/score/pdfjs.ts
@@ -31,10 +31,11 @@ export function configureScorePdfWorker(): void {
  * to a no-op hook and unknown named entities are preserved literally rather
  * than dereferenced, so no external-entity resolver is exposed by this API.
  */
-export function loadScorePdf(data: Uint8Array): PDFDocumentLoadingTask {
+export function loadScorePdf(scorePdfBytes: Uint8Array): PDFDocumentLoadingTask {
   configureScorePdfWorker();
   return getDocument({
-    data: new Uint8Array(data),
+    // `data` is the pdf.js vendor contract; keep it at this adapter boundary.
+    data: new Uint8Array(scorePdfBytes),
     enableXfa: false,
     useWorkerFetch: false
   });

From 5794465d48fb8d9ff2ff941d891053fe8facc5e9 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 22:01:02 +0900
Subject: [PATCH 08/15] test(score): prove PDF.js adapter naming boundary

---
 apps/desktop/src/features/score/pdfjs.test.ts | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/apps/desktop/src/features/score/pdfjs.test.ts b/apps/desktop/src/features/score/pdfjs.test.ts
index 8b494ca70..10a446665 100644
--- a/apps/desktop/src/features/score/pdfjs.test.ts
+++ b/apps/desktop/src/features/score/pdfjs.test.ts
@@ -26,29 +26,29 @@ describe("score PDF.js boundary", () => {
     expect(GlobalWorkerOptions.workerSrc).toBe("/assets/pdf.worker.min.mjs");
   });
 
-  it("copies validated bytes through the hardened data-only API", () => {
-    const source = new Uint8Array([0x25, 0x50, 0x44, 0x46]);
+  it("translates semantic score PDF bytes to the vendor data field", () => {
+    const scorePdfBytes = new Uint8Array([0x25, 0x50, 0x44, 0x46]);
 
-    loadScorePdf(source);
+    loadScorePdf(scorePdfBytes);
 
     expect(getDocument).toHaveBeenCalledTimes(1);
-    const parameters = vi.mocked(getDocument).mock.calls[0]?.[0];
-    expect(parameters).toBeTypeOf("object");
-    expect(Object.keys(parameters as object)).toEqual([
+    const pdfDocumentParameters = vi.mocked(getDocument).mock.calls[0]?.[0];
+    expect(pdfDocumentParameters).toBeTypeOf("object");
+    expect(Object.keys(pdfDocumentParameters as object)).toEqual([
       "data",
       "enableXfa",
       "useWorkerFetch"
     ]);
-    const hardenedParameters = parameters as {
+    const hardenedPdfParameters = pdfDocumentParameters as {
       data: Uint8Array;
       enableXfa: boolean;
       useWorkerFetch: boolean;
     };
-    expect(hardenedParameters.data).toEqual(source);
-    expect(hardenedParameters.data).not.toBe(source);
-    source[0] = 0x00;
-    expect(hardenedParameters.data[0]).toBe(0x25);
-    expect(hardenedParameters.enableXfa).toBe(false);
-    expect(hardenedParameters.useWorkerFetch).toBe(false);
+    expect(hardenedPdfParameters.data).toEqual(scorePdfBytes);
+    expect(hardenedPdfParameters.data).not.toBe(scorePdfBytes);
+    scorePdfBytes[0] = 0x00;
+    expect(hardenedPdfParameters.data[0]).toBe(0x25);
+    expect(hardenedPdfParameters.enableXfa).toBe(false);
+    expect(hardenedPdfParameters.useWorkerFetch).toBe(false);
   });
 });
\ No newline at end of file

From 25ea6dff470bbeb0059291757f4a5e85c74dcb05 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 22:04:04 +0900
Subject: [PATCH 09/15] refactor(score): name viewer status callback
 semantically

---
 apps/desktop/src/features/score/ScoreViewer.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.tsx b/apps/desktop/src/features/score/ScoreViewer.tsx
index fa34ef066..43ae19589 100644
--- a/apps/desktop/src/features/score/ScoreViewer.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.tsx
@@ -31,7 +31,7 @@ export interface ScoreViewerProps {
   /** Optional display name of the attached score file. */
   fileName?: string;
   /** Optional observer notified on every LOADING/FAILED/READY transition. */
-  onStatusChange?: (status: ScoreViewerStatus) => void;
+  onStatusChange?: (viewerStatus: ScoreViewerStatus) => void;
 }
 
 const ZOOM_STEP = 1.25;

From bdd1cb2e130d1bc08a89fcf233738cb1d394431a Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 23:23:25 +0900
Subject: [PATCH 10/15] refactor(score): qualify cancellation identifiers

---
 apps/desktop/src/features/score/ScoreViewer.tsx | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.tsx b/apps/desktop/src/features/score/ScoreViewer.tsx
index 43ae19589..82a81a42a 100644
--- a/apps/desktop/src/features/score/ScoreViewer.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.tsx
@@ -70,7 +70,7 @@ export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreVi
       return;
     }
 
-    let cancelled = false;
+    let pdfLoadCancelled = false;
     setViewerStatus("LOADING");
     setErrorMessage(null);
     setPdfDocument(null);
@@ -78,7 +78,7 @@ export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreVi
     const loadingTask = loadScorePdf(scorePdfBytes);
     loadingTask.promise
       .then((loadedDocument) => {
-        if (cancelled) {
+        if (pdfLoadCancelled) {
           return;
         }
         setPdfDocument(loadedDocument);
@@ -87,7 +87,7 @@ export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreVi
         setViewerStatus("READY");
       })
       .catch((error: unknown) => {
-        if (cancelled) {
+        if (pdfLoadCancelled) {
           return;
         }
         setErrorMessage(error instanceof Error ? error.message : String(error));
@@ -95,7 +95,7 @@ export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreVi
       });
 
     return () => {
-      cancelled = true;
+      pdfLoadCancelled = true;
       void loadingTask.destroy().catch(() => undefined);
     };
   }, [scorePdfBytes, retryToken]);
@@ -125,13 +125,13 @@ export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreVi
       return;
     }
 
-    let cancelled = false;
+    let pageRenderCancelled = false;
     let renderTask: RenderTask | null = null;
 
     pdfDocument
       .getPage(pageNumber)
       .then((pdfPage) => {
-        if (cancelled) {
+        if (pageRenderCancelled) {
           return;
         }
         const baseViewport = pdfPage.getViewport({ scale: 1 });
@@ -150,7 +150,7 @@ export function ScoreViewer({ scorePdfBytes, fileName, onStatusChange }: ScoreVi
       });
 
     return () => {
-      cancelled = true;
+      pageRenderCancelled = true;
       renderTask?.cancel();
     };
   }, [viewerStatus, pdfDocument, pageNumber, zoomScale, fitWidth, containerWidth]);

From 29fd07fb8decdc936904bd1fd6739c34fc6d3363 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 23:25:19 +0900
Subject: [PATCH 11/15] refactor(score): qualify PDF test identifiers

---
 .../src/features/score/ScoreViewer.test.tsx   | 94 +++++++++----------
 1 file changed, 47 insertions(+), 47 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.test.tsx b/apps/desktop/src/features/score/ScoreViewer.test.tsx
index 6f06ea55a..68f58825d 100644
--- a/apps/desktop/src/features/score/ScoreViewer.test.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.test.tsx
@@ -9,7 +9,7 @@ vi.mock("./pdfjs", () => ({
 }));
 
 vi.mock("../../i18n", () => ({
-  createTranslator: () => (key: string) =>
+  createTranslator: () => (translationKey: string) =>
     ({
       scoreViewerEmpty: "No score PDF attached. Attach a validated score PDF to view it here.",
       scoreViewerLoading: "Loading score PDF...",
@@ -21,7 +21,7 @@ vi.mock("../../i18n", () => ({
       scoreViewerZoomIn: "Zoom in",
       scoreViewerZoomOut: "Zoom out",
       scoreViewerFitWidth: "Fit width"
-    })[key] ?? key,
+    })[translationKey] ?? translationKey,
   detectPreferredLocale: () => "en"
 }));
 
@@ -53,26 +53,26 @@ function createFakePage(renderPromise: Promise<void> = Promise.resolve()) {
   };
 }
 
-function createFakeDocument(numPages = 3, page = createFakePage()) {
+function createFakeDocument(pageCount = 3, pdfPage = createFakePage()) {
   return {
-    page,
-    doc: {
-      numPages,
-      getPage: vi.fn(() => Promise.resolve(page))
+    pdfPage,
+    pdfDocument: {
+      numPages: pageCount,
+      getPage: vi.fn(() => Promise.resolve(pdfPage))
     } as unknown as PDFDocumentProxy
   };
 }
 
 function mockLoadTaskOnce(
-  promise: Promise<unknown>,
-  destroy: () => Promise<void> = () => Promise.resolve()
+  loadingPromise: Promise<unknown>,
+  destroyCallback: () => Promise<void> = () => Promise.resolve()
 ) {
-  const destroyMock = vi.fn(destroy);
+  const destroyMock = vi.fn(destroyCallback);
   vi.mocked(loadScorePdf).mockReturnValueOnce({
-    promise,
+    promise: loadingPromise,
     destroy: destroyMock
   } as unknown as PDFDocumentLoadingTask);
-  return { destroy: destroyMock };
+  return { destroyMock };
 }
 
 const SAMPLE_BYTES = new Uint8Array([0x25, 0x50, 0x44, 0x46]);
@@ -100,7 +100,7 @@ describe("ScoreViewer", () => {
   it("transitions from LOADING to READY and renders the first page", async () => {
     const deferred = createDeferred<PDFDocumentProxy>();
     mockLoadTaskOnce(deferred.promise);
-    const { doc, page } = createFakeDocument(3);
+    const { pdfDocument, pdfPage } = createFakeDocument(3);
     const onStatusChange = vi.fn();
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} onStatusChange={onStatusChange} />);
@@ -111,22 +111,22 @@ describe("ScoreViewer", () => {
     expect(loadScorePdf).toHaveBeenCalledWith(SAMPLE_BYTES);
 
     await act(async () => {
-      deferred.resolve(doc);
+      deferred.resolve(pdfDocument);
     });
 
     expect(await screen.findByText("Page 1 of 3")).toBeInTheDocument();
     expect(onStatusChange).toHaveBeenLastCalledWith("READY");
     await waitFor(() => {
-      expect(page.render).toHaveBeenCalled();
+      expect(pdfPage.render).toHaveBeenCalled();
     });
-    expect(page.getViewport).toHaveBeenCalledWith({ scale: 1 });
+    expect(pdfPage.getViewport).toHaveBeenCalledWith({ scale: 1 });
     expect(screen.getByRole("button", { name: "Previous page" })).toBeDisabled();
     expect(screen.getByRole("button", { name: "Next page" })).toBeEnabled();
   });
 
   it("shows the file name when provided", async () => {
-    const { doc } = createFakeDocument(1);
-    mockLoadTaskOnce(Promise.resolve(doc));
+    const { pdfDocument } = createFakeDocument(1);
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} fileName="setlist-opener.pdf" />);
 
@@ -135,8 +135,8 @@ describe("ScoreViewer", () => {
 
   it("transitions to FAILED with the error message and recovers on retry", async () => {
     mockLoadTaskOnce(Promise.reject(new Error("broken bytes")));
-    const { doc } = createFakeDocument(2);
-    mockLoadTaskOnce(Promise.resolve(doc));
+    const { pdfDocument } = createFakeDocument(2);
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
     const onStatusChange = vi.fn();
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} onStatusChange={onStatusChange} />);
@@ -166,8 +166,8 @@ describe("ScoreViewer", () => {
   });
 
   it("navigates pages and clamps at both bounds", async () => {
-    const { doc } = createFakeDocument(3);
-    mockLoadTaskOnce(Promise.resolve(doc));
+    const { pdfDocument } = createFakeDocument(3);
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
@@ -184,19 +184,19 @@ describe("ScoreViewer", () => {
     expect(nextButton).toBeDisabled();
 
     await waitFor(() => {
-      expect(doc.getPage).toHaveBeenCalledWith(3);
+      expect(pdfDocument.getPage).toHaveBeenCalledWith(3);
     });
 
     fireEvent.click(previousButton);
     expect(screen.getByText("Page 2 of 3")).toBeInTheDocument();
     await waitFor(() => {
-      expect(doc.getPage).toHaveBeenCalledWith(2);
+      expect(pdfDocument.getPage).toHaveBeenCalledWith(2);
     });
   });
 
   it("zooms in and out with clamping and returns to fit-width", async () => {
-    const { doc, page } = createFakeDocument(1);
-    mockLoadTaskOnce(Promise.resolve(doc));
+    const { pdfDocument, pdfPage } = createFakeDocument(1);
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
@@ -209,21 +209,21 @@ describe("ScoreViewer", () => {
     fireEvent.click(zoomInButton);
     expect(fitWidthButton).toHaveAttribute("aria-pressed", "false");
     await waitFor(() => {
-      expect(page.getViewport).toHaveBeenCalledWith({ scale: 1.25 });
+      expect(pdfPage.getViewport).toHaveBeenCalledWith({ scale: 1.25 });
     });
 
-    for (let clicks = 0; clicks < 8; clicks += 1) {
+    for (let zoomClickCount = 0; zoomClickCount < 8; zoomClickCount += 1) {
       fireEvent.click(zoomInButton);
     }
     await waitFor(() => {
-      expect(page.getViewport).toHaveBeenCalledWith({ scale: 4 });
+      expect(pdfPage.getViewport).toHaveBeenCalledWith({ scale: 4 });
     });
 
-    for (let clicks = 0; clicks < 12; clicks += 1) {
+    for (let zoomClickCount = 0; zoomClickCount < 12; zoomClickCount += 1) {
       fireEvent.click(zoomOutButton);
     }
     await waitFor(() => {
-      expect(page.getViewport).toHaveBeenCalledWith({ scale: 0.5 });
+      expect(pdfPage.getViewport).toHaveBeenCalledWith({ scale: 0.5 });
     });
 
     fireEvent.click(fitWidthButton);
@@ -233,8 +233,8 @@ describe("ScoreViewer", () => {
   it("re-renders at fit-width scale when the container resizes", async () => {
     let resizeCallback: ResizeObserverCallback | null = null;
     class FakeResizeObserver {
-      constructor(callback: ResizeObserverCallback) {
-        resizeCallback = callback;
+      constructor(resizeObserverCallback: ResizeObserverCallback) {
+        resizeCallback = resizeObserverCallback;
       }
       observe() {}
       unobserve() {}
@@ -242,8 +242,8 @@ describe("ScoreViewer", () => {
     }
     vi.stubGlobal("ResizeObserver", FakeResizeObserver);
 
-    const { doc, page } = createFakeDocument(1);
-    mockLoadTaskOnce(Promise.resolve(doc));
+    const { pdfDocument, pdfPage } = createFakeDocument(1);
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
@@ -267,45 +267,45 @@ describe("ScoreViewer", () => {
     });
 
     await waitFor(() => {
-      expect(page.getViewport).toHaveBeenCalledWith({ scale: 0.5 });
+      expect(pdfPage.getViewport).toHaveBeenCalledWith({ scale: 0.5 });
     });
   });
 
   it("keeps the READY layout when a page render is cancelled mid-flight", async () => {
     const renderFailure = Promise.reject(new Error("Rendering cancelled"));
     renderFailure.catch(() => undefined);
-    const page = createFakePage(renderFailure);
-    const { doc } = createFakeDocument(1, page);
-    mockLoadTaskOnce(Promise.resolve(doc));
+    const pdfPage = createFakePage(renderFailure);
+    const { pdfDocument } = createFakeDocument(1, pdfPage);
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 1")).toBeInTheDocument();
     await waitFor(() => {
-      expect(page.render).toHaveBeenCalled();
+      expect(pdfPage.render).toHaveBeenCalled();
     });
     expect(screen.getByText("Page 1 of 1")).toBeInTheDocument();
   });
 
   it("keeps the READY layout when fetching a page fails after load", async () => {
-    const doc = {
+    const pdfDocument = {
       numPages: 1,
       getPage: vi.fn(() => Promise.reject(new Error("destroyed")))
     } as unknown as PDFDocumentProxy;
-    mockLoadTaskOnce(Promise.resolve(doc));
+    mockLoadTaskOnce(Promise.resolve(pdfDocument));
 
     render(<ScoreViewer scorePdfBytes={SAMPLE_BYTES} />);
 
     expect(await screen.findByText("Page 1 of 1")).toBeInTheDocument();
     await waitFor(() => {
-      expect(doc.getPage).toHaveBeenCalled();
+      expect(pdfDocument.getPage).toHaveBeenCalled();
     });
     expect(screen.getByText("Page 1 of 1")).toBeInTheDocument();
   });
 
   it("destroys the loading task on unmount and ignores late results", async () => {
     const deferred = createDeferred<PDFDocumentProxy>();
-    const { destroy } = mockLoadTaskOnce(deferred.promise, () =>
+    const { destroyMock } = mockLoadTaskOnce(deferred.promise, () =>
       Promise.reject(new Error("already destroyed"))
     );
     const onStatusChange = vi.fn();
@@ -315,11 +315,11 @@ describe("ScoreViewer", () => {
     );
     unmount();
 
-    expect(destroy).toHaveBeenCalledTimes(1);
+    expect(destroyMock).toHaveBeenCalledTimes(1);
 
-    const { doc } = createFakeDocument(1);
+    const { pdfDocument } = createFakeDocument(1);
     await act(async () => {
-      deferred.resolve(doc);
+      deferred.resolve(pdfDocument);
     });
     expect(onStatusChange).not.toHaveBeenCalledWith("READY");
   });

From 16ea794447afcdcce68ac83c09deedcb6833be78 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 23:30:25 +0900
Subject: [PATCH 12/15] fix(score): align viewer mock with semantic PDF prop

---
 apps/desktop/src/features/score/ScoreView.test.tsx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreView.test.tsx b/apps/desktop/src/features/score/ScoreView.test.tsx
index de4ccb95c..e733076ec 100644
--- a/apps/desktop/src/features/score/ScoreView.test.tsx
+++ b/apps/desktop/src/features/score/ScoreView.test.tsx
@@ -9,16 +9,16 @@ vi.mock("@tauri-apps/api/core", () => ({
 }));
 
 vi.mock("./ScoreViewer", () => ({
-  ScoreViewer: ({ data, fileName }: { data: Uint8Array | null; fileName?: string }) => (
+  ScoreViewer: ({ scorePdfBytes, fileName }: { scorePdfBytes: Uint8Array | null; fileName?: string }) => (
     <div data-testid="score-viewer">
-      {data ? `bytes:${data.length}` : "no-data"}
+      {scorePdfBytes ? `bytes:${scorePdfBytes.length}` : "no-data"}
       {fileName ? `:${fileName}` : ""}
     </div>
   )
 }));
 
 vi.mock("../../i18n", () => ({
-  createTranslator: () => (key: string) =>
+  createTranslator: () => (translationKey: string) =>
     ({
       scoreViewTitle: "Score",
       scoreViewSubtitle: "Attach validated PDF scores to the current song.",
@@ -34,7 +34,7 @@ vi.mock("../../i18n", () => ({
       scoreReadFailed: "Could not open the score PDF.",
       scoreRemoveFailed: "Could not remove the score PDF.",
       scoreRequiresProject: "Scores attach to the active analysis project."
-    })[key] ?? key,
+    })[translationKey] ?? translationKey,
   detectPreferredLocale: () => "en"
 }));
 
@@ -413,4 +413,4 @@ describe("ScoreView", () => {
     });
     expect(screen.getByTestId("score-viewer")).toHaveTextContent("no-data");
   });
-});
+});
\ No newline at end of file

From 1571ed5ec00cc1a141c566a90fa0017d358a0c4c Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 23:31:29 +0900
Subject: [PATCH 13/15] refactor(score): qualify score view identifiers

---
 apps/desktop/src/features/score/ScoreView.tsx | 137 +++++++++++-------
 1 file changed, 84 insertions(+), 53 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreView.tsx b/apps/desktop/src/features/score/ScoreView.tsx
index cead34022..ba6416e83 100644
--- a/apps/desktop/src/features/score/ScoreView.tsx
+++ b/apps/desktop/src/features/score/ScoreView.tsx
@@ -26,10 +26,15 @@ export interface ScoreViewProps {
  * Extract the first line of a bridge error for display, falling back to the
  * provided message when the error carries no usable text.
  */
-function bridgeErrorDetail(error: unknown, fallback: string): string {
-  const raw = error instanceof Error ? error.message : typeof error === "string" ? error : null;
-  const firstLine = raw?.split(/\r?\n/)[0]?.trim();
-  return firstLine ? firstLine : fallback;
+function bridgeErrorDetail(bridgeError: unknown, fallbackMessage: string): string {
+  const rawErrorMessage =
+    bridgeError instanceof Error
+      ? bridgeError.message
+      : typeof bridgeError === "string"
+        ? bridgeError
+        : null;
+  const firstErrorLine = rawErrorMessage?.split(/\r?\n/)[0]?.trim();
+  return firstErrorLine ? firstErrorLine : fallbackMessage;
 }
 
 /**
@@ -38,13 +43,18 @@ function bridgeErrorDetail(error: unknown, fallback: string): string {
  * embedded viewer, and removes attachments (metadata plus stored copy).
  */
 export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
-  const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
-  const attachments = useMemo(() => song.scoreAttachments ?? [], [song.scoreAttachments]);
-  const [selected, setSelected] = useState<ScoreAttachment | null>(null);
+  const scoreTranslator = useMemo(() => createTranslator(detectPreferredLocale()), []);
+  const scoreAttachments = useMemo(
+    () => song.scoreAttachments ?? [],
+    [song.scoreAttachments]
+  );
+  const [selectedScoreAttachment, setSelectedScoreAttachment] = useState<ScoreAttachment | null>(
+    null
+  );
   const [pdfBytes, setPdfBytes] = useState<Uint8Array | null>(null);
   const [isAttaching, setIsAttaching] = useState(false);
   const [isOpening, setIsOpening] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  const [scoreError, setScoreError] = useState<string | null>(null);
   const readRequestRef = useRef(0);
 
   /**
@@ -52,22 +62,27 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
    * the active project id explicitly; the storage controls are only wired up
    * (and enabled) when a workspace is present, so this never runs without one.
    */
-  const openAttachment = async (activeProjectId: string, attachment: ScoreAttachment) => {
+  const openAttachment = async (
+    activeProjectId: string,
+    scoreAttachment: ScoreAttachment
+  ) => {
     const requestId = readRequestRef.current + 1;
     readRequestRef.current = requestId;
-    setSelected(attachment);
+    setSelectedScoreAttachment(scoreAttachment);
     setPdfBytes(null);
-    setError(null);
+    setScoreError(null);
     setIsOpening(true);
     try {
-      const bytes = await readScorePdf(activeProjectId, attachment.id);
+      const scorePdfBytes = await readScorePdf(activeProjectId, scoreAttachment.id);
       if (readRequestRef.current === requestId) {
-        setPdfBytes(bytes);
+        setPdfBytes(scorePdfBytes);
       }
     } catch (readError) {
       if (readRequestRef.current === requestId) {
-        setSelected(null);
-        setError(`${t("scoreReadFailed")} ${bridgeErrorDetail(readError, "")}`.trim());
+        setSelectedScoreAttachment(null);
+        setScoreError(
+          `${scoreTranslator("scoreReadFailed")} ${bridgeErrorDetail(readError, "")}`.trim()
+        );
       }
     } finally {
       if (readRequestRef.current === requestId) {
@@ -82,56 +97,66 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
    * started; the active project id is supplied by the enabled control.
    */
   const handleAttach = async (activeProjectId: string) => {
-    setError(null);
+    setScoreError(null);
     setIsAttaching(true);
     try {
-      const result = await attachScorePdf(activeProjectId, song.id);
-      const attachment: ScoreAttachment = { id: result.id, fileName: result.fileName };
-      onSongUpdate({ ...song, scoreAttachments: [...attachments, attachment] });
+      const attachmentResult = await attachScorePdf(activeProjectId, song.id);
+      const scoreAttachment: ScoreAttachment = {
+        id: attachmentResult.id,
+        fileName: attachmentResult.fileName
+      };
+      onSongUpdate({ ...song, scoreAttachments: [...scoreAttachments, scoreAttachment] });
       setIsAttaching(false);
-      await openAttachment(activeProjectId, attachment);
+      await openAttachment(activeProjectId, scoreAttachment);
     } catch (attachError) {
       setIsAttaching(false);
-      setError(bridgeErrorDetail(attachError, t("scoreAttachFailed")));
+      setScoreError(bridgeErrorDetail(attachError, scoreTranslator("scoreAttachFailed")));
     }
   };
 
   /** Remove an attachment after confirmation (metadata and stored copy). */
-  const handleRemove = async (activeProjectId: string, attachment: ScoreAttachment) => {
-    const confirmed = window.confirm(
-      t("scoreRemoveConfirm").replace("{fileName}", attachment.fileName)
+  const handleRemove = async (
+    activeProjectId: string,
+    scoreAttachment: ScoreAttachment
+  ) => {
+    const removalConfirmed = window.confirm(
+      scoreTranslator("scoreRemoveConfirm").replace("{fileName}", scoreAttachment.fileName)
     );
-    if (!confirmed) {
+    if (!removalConfirmed) {
       return;
     }
-    setError(null);
+    setScoreError(null);
     try {
-      await removeScorePdf(activeProjectId, attachment.id);
+      await removeScorePdf(activeProjectId, scoreAttachment.id);
       onSongUpdate({
         ...song,
-        scoreAttachments: attachments.filter((entry) => entry.id !== attachment.id)
+        scoreAttachments: scoreAttachments.filter(
+          (scoreAttachmentEntry) => scoreAttachmentEntry.id !== scoreAttachment.id
+        )
       });
-      if (selected?.id === attachment.id) {
+      if (selectedScoreAttachment?.id === scoreAttachment.id) {
         readRequestRef.current += 1;
-        setSelected(null);
+        setSelectedScoreAttachment(null);
         setPdfBytes(null);
         setIsOpening(false);
       }
     } catch (removeError) {
-      setError(bridgeErrorDetail(removeError, t("scoreRemoveFailed")));
+      setScoreError(bridgeErrorDetail(removeError, scoreTranslator("scoreRemoveFailed")));
     }
   };
 
   return (
-    <section aria-label={t("scoreViewTitle")} className="flex flex-col gap-4">
+    <section aria-label={scoreTranslator("scoreViewTitle")} className="flex flex-col gap-4">
       <Card className="border-cyan-300/20 bg-slate-950/75 backdrop-blur-xl">
         <CardContent className="flex flex-col gap-4">
           <div className="flex flex-wrap items-start justify-between gap-3">
             <div>
               <h2 className="text-xl font-black tracking-tight text-white">
-                {t("scoreViewTitle")} · {song.title}
+                {scoreTranslator("scoreViewTitle")} · {song.title}
               </h2>
-              <p className="mt-1 max-w-2xl text-sm text-slate-400">{t("scoreViewSubtitle")}</p>
+              <p className="mt-1 max-w-2xl text-sm text-slate-400">
+                {scoreTranslator("scoreViewSubtitle")}
+              </p>
             </div>
             <Button
               onClick={projectId ? () => void handleAttach(projectId) : undefined}
@@ -144,60 +169,66 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
               ) : (
                 <FilePlus2 className="mr-2 size-4" aria-hidden="true" />
               )}
-              {isAttaching ? t("scoreAttaching") : t("scoreAttach")}
+              {isAttaching ? scoreTranslator("scoreAttaching") : scoreTranslator("scoreAttach")}
             </Button>
           </div>
 
           {!projectId && (
             <p className="rounded-xl border border-amber-300/25 bg-amber-300/10 px-4 py-3 text-sm font-medium text-amber-100">
-              {t("scoreRequiresProject")}
+              {scoreTranslator("scoreRequiresProject")}
             </p>
           )}
 
-          {error && (
+          {scoreError && (
             <p
               className="rounded-xl border border-rose-300/25 bg-rose-400/10 px-4 py-3 text-sm font-medium text-rose-100"
               role="alert"
               aria-live="assertive"
             >
-              {error}
+              {scoreError}
             </p>
           )}
 
           <div>
             <h3 className="mb-2 text-xs font-bold uppercase tracking-[0.22em] text-slate-400">
-              {t("scoreListTitle")}
+              {scoreTranslator("scoreListTitle")}
             </h3>
-            {attachments.length === 0 ? (
-              <p className="text-sm text-slate-400">{t("scoreListEmpty")}</p>
+            {scoreAttachments.length === 0 ? (
+              <p className="text-sm text-slate-400">{scoreTranslator("scoreListEmpty")}</p>
             ) : (
               <ul className="flex flex-col gap-2">
-                {attachments.map((attachment) => (
+                {scoreAttachments.map((scoreAttachment) => (
                   <li
-                    key={attachment.id}
+                    key={scoreAttachment.id}
                     className={`flex items-center justify-between gap-3 rounded-xl border px-3 py-2 transition ${
-                      selected?.id === attachment.id
+                      selectedScoreAttachment?.id === scoreAttachment.id
                         ? "border-cyan-300/40 bg-cyan-300/10"
                         : "border-white/10 bg-white/[0.04]"
                     }`}
                   >
                     <button
                       type="button"
-                      onClick={projectId ? () => void openAttachment(projectId, attachment) : undefined}
+                      onClick={
+                        projectId ? () => void openAttachment(projectId, scoreAttachment) : undefined
+                      }
                       disabled={!projectId}
-                      aria-current={selected?.id === attachment.id ? "true" : undefined}
-                      aria-label={`${t("scoreOpen")}: ${attachment.fileName}`}
+                      aria-current={
+                        selectedScoreAttachment?.id === scoreAttachment.id ? "true" : undefined
+                      }
+                      aria-label={`${scoreTranslator("scoreOpen")}: ${scoreAttachment.fileName}`}
                       className="flex min-h-10 min-w-0 flex-1 items-center gap-2 text-left text-sm font-semibold text-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 disabled:cursor-not-allowed disabled:opacity-60"
                     >
                       <FileMusic className="size-4 shrink-0 text-cyan-300" aria-hidden="true" />
-                      <span className="truncate">{attachment.fileName}</span>
+                      <span className="truncate">{scoreAttachment.fileName}</span>
                     </button>
                     <Button
                       variant="outline"
                       size="icon"
-                      onClick={projectId ? () => void handleRemove(projectId, attachment) : undefined}
+                      onClick={
+                        projectId ? () => void handleRemove(projectId, scoreAttachment) : undefined
+                      }
                       disabled={!projectId}
-                      aria-label={`${t("scoreRemove")}: ${attachment.fileName}`}
+                      aria-label={`${scoreTranslator("scoreRemove")}: ${scoreAttachment.fileName}`}
                       className="size-10 border-rose-300/25 text-rose-200 hover:bg-rose-400/10"
                     >
                       <Trash2 className="size-4" aria-hidden="true" />
@@ -218,12 +249,12 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
           aria-busy="true"
         >
           <CardContent className="flex flex-col items-center justify-center py-16 text-center">
-            <Loader2 className="mb-4 size-10 animate-spin text-cyan-300" aria-hidden="true" />
-            <p className="animate-pulse text-slate-400">{t("scoreOpening")}</p>
+            <Loader2 className="mb-4 size-10 animate-spin" aria-hidden="true" />
+            <p className="animate-pulse text-slate-400">{scoreTranslator("scoreOpening")}</p>
           </CardContent>
         </Card>
       ) : (
-        <ScoreViewer scorePdfBytes={pdfBytes} fileName={selected?.fileName} />
+        <ScoreViewer scorePdfBytes={pdfBytes} fileName={selectedScoreAttachment?.fileName} />
       )}
     </section>
   );

From b2e7cdb3f1c473b95e6887dacc38f51eb8c3a5b7 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Wed, 2 Sep 2026 23:32:23 +0900
Subject: [PATCH 14/15] fix(score): preserve opening spinner presentation

---
 apps/desktop/src/features/score/ScoreView.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/score/ScoreView.tsx b/apps/desktop/src/features/score/ScoreView.tsx
index ba6416e83..146ba2da9 100644
--- a/apps/desktop/src/features/score/ScoreView.tsx
+++ b/apps/desktop/src/features/score/ScoreView.tsx
@@ -249,7 +249,7 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
           aria-busy="true"
         >
           <CardContent className="flex flex-col items-center justify-center py-16 text-center">
-            <Loader2 className="mb-4 size-10 animate-spin" aria-hidden="true" />
+            <Loader2 className="mb-4 size-10 animate-spin text-cyan-300" aria-hidden="true" />
             <p className="animate-pulse text-slate-400">{scoreTranslator("scoreOpening")}</p>
           </CardContent>
         </Card>

From b112c9fd05a40d8ee62aad351c54b68052a5a575 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Thu, 3 Sep 2026 16:05:02 +0900
Subject: [PATCH 15/15] fix(ci): normalize temporal naming test imports

---
 services/analysis-engine/tests/test_temporal_naming_contract.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/services/analysis-engine/tests/test_temporal_naming_contract.py b/services/analysis-engine/tests/test_temporal_naming_contract.py
index 919e01665..603f3882b 100644
--- a/services/analysis-engine/tests/test_temporal_naming_contract.py
+++ b/services/analysis-engine/tests/test_temporal_naming_contract.py
@@ -1,7 +1,5 @@
 """Naming-contract regression tests for temporal stability internals."""
 
-from __future__ import annotations
-
 import ast
 from pathlib import Path