From d1659c724b36db945568c33cfa6d2e00eccef3c3 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:04:28 +0000
Subject: [PATCH 01/13] feat: improve score viewer disabled button
 accessibility

---
 .../src/features/score/ScoreViewer.test.tsx   | 24 +++++++++++++++----
 .../src/features/score/ScoreViewer.tsx        | 22 +++++++++++++----
 apps/desktop/src/locales/en/common.json       |  2 ++
 apps/desktop/src/locales/ko/common.json       |  2 ++
 4 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.test.tsx b/apps/desktop/src/features/score/ScoreViewer.test.tsx
index 3ac2dd605..67d2b6181 100644
--- a/apps/desktop/src/features/score/ScoreViewer.test.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.test.tsx
@@ -16,7 +16,9 @@ vi.mock("../../i18n", () => ({
       scoreViewerFailedTitle: "Could not display the score",
       scoreViewerRetry: "Retry",
       scoreViewerPrevPage: "Previous page",
+      scoreViewerPrevPageDisabled: "Already on the first page",
       scoreViewerNextPage: "Next page",
+      scoreViewerNextPageDisabled: "Already on the last page",
       scoreViewerPageIndicator: "Page {current} of {total}",
       scoreViewerZoomIn: "Zoom in",
       scoreViewerZoomOut: "Zoom out",
@@ -120,8 +122,8 @@ describe("ScoreViewer", () => {
       expect(page.render).toHaveBeenCalled();
     });
     expect(page.getViewport).toHaveBeenCalledWith({ scale: 1 });
-    expect(screen.getByRole("button", { name: "Previous page" })).toBeDisabled();
-    expect(screen.getByRole("button", { name: "Next page" })).toBeEnabled();
+    expect(screen.getByRole("button", { name: "Previous page" })).toHaveAttribute("aria-disabled", "true");
+    expect(screen.getByRole("button", { name: "Next page" })).toHaveAttribute("aria-disabled", "false");
   });
 
   it("shows the file name when provided", async () => {
@@ -174,14 +176,28 @@ describe("ScoreViewer", () => {
     expect(await screen.findByText("Page 1 of 3")).toBeInTheDocument();
     const previousButton = screen.getByRole("button", { name: "Previous page" });
     const nextButton = screen.getByRole("button", { name: "Next page" });
-    expect(previousButton).toBeDisabled();
+    expect(previousButton).toHaveAttribute("aria-disabled", "true");
+
+    const eventSpy = vi.spyOn(Event.prototype, "preventDefault");
+
+    // clicking an aria-disabled button calls preventDefault and ignores the action
+    fireEvent.click(previousButton);
+    expect(eventSpy).toHaveBeenCalled();
+    expect(screen.getByText("Page 1 of 3")).toBeInTheDocument();
+    eventSpy.mockClear();
 
     fireEvent.click(nextButton);
     expect(screen.getByText("Page 2 of 3")).toBeInTheDocument();
 
     fireEvent.click(nextButton);
     expect(screen.getByText("Page 3 of 3")).toBeInTheDocument();
-    expect(nextButton).toBeDisabled();
+    expect(nextButton).toHaveAttribute("aria-disabled", "true");
+
+    // clicking an aria-disabled button calls preventDefault and ignores the action
+    fireEvent.click(nextButton);
+    expect(eventSpy).toHaveBeenCalled();
+    expect(screen.getByText("Page 3 of 3")).toBeInTheDocument();
+    eventSpy.mockRestore();
 
     await waitFor(() => {
       expect(doc.getPage).toHaveBeenCalledWith(3);
diff --git a/apps/desktop/src/features/score/ScoreViewer.tsx b/apps/desktop/src/features/score/ScoreViewer.tsx
index 82692469e..bb9bd5490 100644
--- a/apps/desktop/src/features/score/ScoreViewer.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.tsx
@@ -292,8 +292,15 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
             size="icon-lg"
             className="size-14"
             aria-label={t("scoreViewerPrevPage")}
-            disabled={pageNumber <= 1}
-            onClick={goToPreviousPage}
+            title={pageNumber <= 1 ? t("scoreViewerPrevPageDisabled") : undefined}
+            aria-disabled={pageNumber <= 1}
+            onClick={(e) => {
+              if (pageNumber <= 1) {
+                e.preventDefault();
+                return;
+              }
+              goToPreviousPage();
+            }}
           >
             <ChevronLeft className="size-6" aria-hidden="true" />
           </Button>
@@ -305,8 +312,15 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
             size="icon-lg"
             className="size-14"
             aria-label={t("scoreViewerNextPage")}
-            disabled={pageNumber >= pageCount}
-            onClick={goToNextPage}
+            title={pageNumber >= pageCount ? t("scoreViewerNextPageDisabled") : undefined}
+            aria-disabled={pageNumber >= pageCount}
+            onClick={(e) => {
+              if (pageNumber >= pageCount) {
+                e.preventDefault();
+                return;
+              }
+              goToNextPage();
+            }}
           >
             <ChevronRight className="size-6" aria-hidden="true" />
           </Button>
diff --git a/apps/desktop/src/locales/en/common.json b/apps/desktop/src/locales/en/common.json
index d803a765e..b583c5ca6 100644
--- a/apps/desktop/src/locales/en/common.json
+++ b/apps/desktop/src/locales/en/common.json
@@ -68,7 +68,9 @@
   "scoreViewerFailedTitle": "Could not display the score",
   "scoreViewerRetry": "Retry",
   "scoreViewerPrevPage": "Previous page",
+  "scoreViewerPrevPageDisabled": "Already on the first page",
   "scoreViewerNextPage": "Next page",
+  "scoreViewerNextPageDisabled": "Already on the last page",
   "scoreViewerPageIndicator": "Page {current} of {total}",
   "scoreViewerZoomIn": "Zoom in",
   "scoreViewerZoomOut": "Zoom out",
diff --git a/apps/desktop/src/locales/ko/common.json b/apps/desktop/src/locales/ko/common.json
index 0f6c6c66d..377c6ead2 100644
--- a/apps/desktop/src/locales/ko/common.json
+++ b/apps/desktop/src/locales/ko/common.json
@@ -68,7 +68,9 @@
   "scoreViewerFailedTitle": "악보를 표시할 수 없습니다",
   "scoreViewerRetry": "다시 시도",
   "scoreViewerPrevPage": "이전 페이지",
+  "scoreViewerPrevPageDisabled": "이미 첫 페이지입니다",
   "scoreViewerNextPage": "다음 페이지",
+  "scoreViewerNextPageDisabled": "이미 마지막 페이지입니다",
   "scoreViewerPageIndicator": "{total}페이지 중 {current}페이지",
   "scoreViewerZoomIn": "확대",
   "scoreViewerZoomOut": "축소",

From e75ac9ff3d13997212aa6dfae7136e219697e584 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:09:28 +0000
Subject: [PATCH 02/13] Trigger CI retry


From 0fbe4216e6d57d103b272796b521569122063689 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:18:57 +0000
Subject: [PATCH 03/13] Trigger CI retry


From 0f1d8e93c912b0851a7f3d4c3597eade612889a7 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:31:12 +0000
Subject: [PATCH 04/13] Trigger CI retry


From 0860d56b5d5ede74e2d5d5f89d56e3d804d167b7 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:37:27 +0000
Subject: [PATCH 05/13] Trigger CI retry


From fe36f60513d413306a5df1eed9b3c938202504af Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:42:07 +0000
Subject: [PATCH 06/13] Trigger CI retry


From a60719290dee1d950948e99cd6b16272bb11538f Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:46:13 +0000
Subject: [PATCH 07/13] Trigger CI retry


From 05a2d8d7cf7cb7a66763919c33122701a7aad9d4 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 04:56:24 +0000
Subject: [PATCH 08/13] Trigger CI retry


From d3b6f0ea45aa4339fa73df3d4265266f74cdd890 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sat, 29 Aug 2026 23:36:37 -0700
Subject: [PATCH 09/13] test(score): cover keyboard disabled reasons

---
 .../src/features/score/ScoreViewer.test.tsx    | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.test.tsx b/apps/desktop/src/features/score/ScoreViewer.test.tsx
index 67d2b6181..d4595d544 100644
--- a/apps/desktop/src/features/score/ScoreViewer.test.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.test.tsx
@@ -167,7 +167,7 @@ describe("ScoreViewer", () => {
     expect(screen.getByText("password protected")).toBeInTheDocument();
   });
 
-  it("navigates pages and clamps at both bounds", async () => {
+  it("navigates pages and exposes unavailable reasons to keyboard focus", async () => {
     const { doc } = createFakeDocument(3);
     mockLoadTaskOnce(Promise.resolve(doc));
 
@@ -177,6 +177,14 @@ describe("ScoreViewer", () => {
     const previousButton = screen.getByRole("button", { name: "Previous page" });
     const nextButton = screen.getByRole("button", { name: "Next page" });
     expect(previousButton).toHaveAttribute("aria-disabled", "true");
+    expect(previousButton).not.toHaveAttribute("title");
+
+    const previousReason = screen.getByRole("tooltip");
+    expect(previousReason).toHaveTextContent("Already on the first page");
+    expect(previousButton).toHaveAttribute("aria-describedby", previousReason.id);
+    previousButton.focus();
+    expect(previousButton).toHaveFocus();
+    expect(previousReason).toHaveClass("group-focus-within:opacity-100");
 
     const eventSpy = vi.spyOn(Event.prototype, "preventDefault");
 
@@ -192,6 +200,14 @@ describe("ScoreViewer", () => {
     fireEvent.click(nextButton);
     expect(screen.getByText("Page 3 of 3")).toBeInTheDocument();
     expect(nextButton).toHaveAttribute("aria-disabled", "true");
+    expect(nextButton).not.toHaveAttribute("title");
+
+    const nextReason = screen.getByRole("tooltip");
+    expect(nextReason).toHaveTextContent("Already on the last page");
+    expect(nextButton).toHaveAttribute("aria-describedby", nextReason.id);
+    nextButton.focus();
+    expect(nextButton).toHaveFocus();
+    expect(nextReason).toHaveClass("group-focus-within:opacity-100");
 
     // clicking an aria-disabled button calls preventDefault and ignores the action
     fireEvent.click(nextButton);

From 20681e1c7f54031b01aac8cc467d668b7f9cf017 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sat, 29 Aug 2026 23:37:26 -0700
Subject: [PATCH 10/13] fix(score): expose disabled reasons on focus

---
 .../src/features/score/ScoreViewer.tsx        | 98 ++++++++++++-------
 1 file changed, 63 insertions(+), 35 deletions(-)

diff --git a/apps/desktop/src/features/score/ScoreViewer.tsx b/apps/desktop/src/features/score/ScoreViewer.tsx
index bb9bd5490..121817d3c 100644
--- a/apps/desktop/src/features/score/ScoreViewer.tsx
+++ b/apps/desktop/src/features/score/ScoreViewer.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
 import type { PDFDocumentProxy, RenderTask } from "pdfjs-dist";
 import {
   AlertCircle,
@@ -47,6 +47,8 @@ const MAX_ZOOM = 4;
  */
 export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps) {
   const t = useMemo(() => createTranslator(detectPreferredLocale()), []);
+  const previousPageDisabledReasonId = useId();
+  const nextPageDisabledReasonId = useId();
   const [status, setStatus] = useState<ScoreViewerStatus>("LOADING");
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const [pdfDocument, setPdfDocument] = useState<PDFDocumentProxy | null>(null);
@@ -241,6 +243,10 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
   const pageIndicator = t("scoreViewerPageIndicator")
     .replace("{current}", String(pageNumber))
     .replace("{total}", String(pageCount));
+  const previousPageUnavailable = pageNumber <= 1;
+  const nextPageUnavailable = pageNumber >= pageCount;
+  const unavailableReasonClassName =
+    "pointer-events-none absolute bottom-full left-1/2 z-10 mb-2 w-max max-w-48 -translate-x-1/2 rounded-md border border-white/10 bg-slate-950 px-2 py-1 text-center text-xs text-slate-100 opacity-0 shadow-lg transition-opacity group-hover:opacity-100 group-focus-within:opacity-100";
 
   return (
     <Card className="border-cyan-300/20 bg-slate-950/75 backdrop-blur-xl">
@@ -287,43 +293,65 @@ export function ScoreViewer({ data, fileName, onStatusChange }: ScoreViewerProps
           <canvas ref={canvasRef} className="mx-auto block max-w-none" />
         </div>
         <div className="flex items-center justify-center gap-4">
-          <Button
-            variant="outline"
-            size="icon-lg"
-            className="size-14"
-            aria-label={t("scoreViewerPrevPage")}
-            title={pageNumber <= 1 ? t("scoreViewerPrevPageDisabled") : undefined}
-            aria-disabled={pageNumber <= 1}
-            onClick={(e) => {
-              if (pageNumber <= 1) {
-                e.preventDefault();
-                return;
-              }
-              goToPreviousPage();
-            }}
-          >
-            <ChevronLeft className="size-6" aria-hidden="true" />
-          </Button>
+          <span className="group relative inline-flex">
+            <Button
+              variant="outline"
+              size="icon-lg"
+              className="size-14"
+              aria-label={t("scoreViewerPrevPage")}
+              aria-disabled={previousPageUnavailable}
+              aria-describedby={previousPageUnavailable ? previousPageDisabledReasonId : undefined}
+              onClick={(e) => {
+                if (previousPageUnavailable) {
+                  e.preventDefault();
+                  return;
+                }
+                goToPreviousPage();
+              }}
+            >
+              <ChevronLeft className="size-6" aria-hidden="true" />
+            </Button>
+            {previousPageUnavailable && (
+              <span
+                id={previousPageDisabledReasonId}
+                role="tooltip"
+                className={unavailableReasonClassName}
+              >
+                {t("scoreViewerPrevPageDisabled")}
+              </span>
+            )}
+          </span>
           <span className="min-w-28 text-center text-sm font-semibold text-slate-200">
             {pageIndicator}
           </span>
-          <Button
-            variant="outline"
-            size="icon-lg"
-            className="size-14"
-            aria-label={t("scoreViewerNextPage")}
-            title={pageNumber >= pageCount ? t("scoreViewerNextPageDisabled") : undefined}
-            aria-disabled={pageNumber >= pageCount}
-            onClick={(e) => {
-              if (pageNumber >= pageCount) {
-                e.preventDefault();
-                return;
-              }
-              goToNextPage();
-            }}
-          >
-            <ChevronRight className="size-6" aria-hidden="true" />
-          </Button>
+          <span className="group relative inline-flex">
+            <Button
+              variant="outline"
+              size="icon-lg"
+              className="size-14"
+              aria-label={t("scoreViewerNextPage")}
+              aria-disabled={nextPageUnavailable}
+              aria-describedby={nextPageUnavailable ? nextPageDisabledReasonId : undefined}
+              onClick={(e) => {
+                if (nextPageUnavailable) {
+                  e.preventDefault();
+                  return;
+                }
+                goToNextPage();
+              }}
+            >
+              <ChevronRight className="size-6" aria-hidden="true" />
+            </Button>
+            {nextPageUnavailable && (
+              <span
+                id={nextPageDisabledReasonId}
+                role="tooltip"
+                className={unavailableReasonClassName}
+              >
+                {t("scoreViewerNextPageDisabled")}
+              </span>
+            )}
+          </span>
         </div>
       </CardContent>
     </Card>

From ab98a80c029dad24c0e069f2bfa089177700eaf2 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 07:02:00 +0000
Subject: [PATCH 11/13] Trigger CI retry


From 498b8496303bdc546e2e9604b9a06fa23e7df4b2 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 08:42:22 +0000
Subject: [PATCH 12/13] Trigger CI retry


From d083f29906abbb70ea72d99c34aa583a9f8efb23 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sun, 30 Aug 2026 09:14:51 +0000
Subject: [PATCH 13/13] Trigger CI retry