fix(ui): consolidate unavailable App control tooltips

.jules/palette.md

@@ -1,3 +1,7 @@
-## 2024-05-19 - Replace HTML disabled with aria-disabled="true" for Accessible Tooltips
-**Learning:** Native HTML `disabled` attributes completely hide elements from screen readers and block all pointer/hover events, preventing tooltips from functioning for disabled elements.
-**Action:** Replace `disabled` with `aria-disabled="true"`, enforce block click handlers via `e.preventDefault()`, and add a title tooltip directly to the element to maintain full tooltip accessibility and keyboard focus support for visually impaired and mouse users.
+## 2026-09-09 - Accessible Tooltips on Disabled Elements
+**Learning:** `aria-disabled="true"` exposes unavailable state but does not suppress activation. Icon-only controls therefore need an accessible name independent of the tooltip, and unavailable activation must still be blocked in code.
+**Action:** Keep unavailable icon buttons focusable with `aria-disabled="true"`, give the trigger an `aria-label` matching the Tooltip text, and route pointer or keyboard-generated clicks through `preventUnavailableAction`. Use the design-system Tooltip only to explain the unavailable state; do not log or expose user-controlled values through tooltip copy.
+
+## 2026-09-11 - Preserve doctoring security boundaries during regeneration
+**Learning:** This Tooltip slice cites external MDN, W3C, and Base UI documentation. Two later branch regenerations removed the reviewed `Security Notes` paragraph even though the runtime trust/network boundary had not changed, repeatedly reopening the same governance finding.
+**Action:** When updating `docs/doctoring/sidebar-disabled-tooltips.md`, preserve its `Security Notes` section whenever external references remain. The note must keep those URLs documentation-only and state that this Tooltip slice adds no runtime fetch/navigation, subprocess, IPC, updater, model-download, credential, or trust-boundary path. If that security boundary truly changes, update the note and tests/review evidence explicitly rather than deleting it as formatting or generated-copy cleanup.

apps/desktop/src/App.test.tsx

@@ -225,7 +225,7 @@ describe("App", () => {
     for (const name of ["Import", "Export"]) {
       const navButton = within(primaryNav).getByRole("button", { name });
       expect(navButton).toHaveAttribute("aria-disabled", "true");
-      expect(navButton).toHaveAttribute("title", "Coming soon");
+      expect(navButton).not.toHaveAttribute("title");
       expect(navButton).not.toBeDisabled();
     }
     fireEvent.click(within(primaryNav).getByRole("button", { name: "Import" }));
@@ -236,7 +236,7 @@ describe("App", () => {
     for (const name of ["Import", "Export"]) {
       const navButton = within(compactNav).getByRole("button", { name: `${name} compact view` });
       expect(navButton).toHaveAttribute("aria-disabled", "true");
-      expect(navButton).toHaveAttribute("title", "Coming soon");
+      expect(navButton).not.toHaveAttribute("title");
       expect(navButton).not.toBeDisabled();
     }
     fireEvent.click(within(compactNav).getByRole("button", { name: "Import compact view" }));

apps/desktop/src/App.tsx

@@ -24,6 +24,7 @@ import {
   X,
   type LucideIcon,
 } from "lucide-react";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import {
   SUPPORTED_AUDIO_FORMATS,
   type AnalysisJobRequest,
@@ -565,25 +566,43 @@ export function App() {
               const { label, enabled, active, title } = navButtonState(item);
               const { icon: Icon, view } = item;
 
-              return (
+              const buttonClass = `flex min-h-11 w-full items-center gap-3 rounded-xl px-3 text-left text-sm font-semibold transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 ${
+                active
+                  ? "bg-blue-600/70 text-white shadow-[0_12px_30px_rgba(37,99,235,0.32)]"
+                  : enabled
+                    ? "text-slate-200 hover:bg-white/5"
+                    : "cursor-not-allowed text-slate-500 opacity-70"
+              }`;
+
+              const buttonContent = (
+                <>
+                  <Icon className="size-5" aria-hidden="true" />
+                  {label}
+                </>
+              );
+
+              return enabled ? (
                 <button
                   key={item.labelKey}
                   type="button"
                   aria-current={active ? "page" : undefined}
-                  aria-disabled={enabled ? undefined : true}
-                  title={title}
-                  onClick={enabled && view ? () => handleNavSelect(view) : blockInactiveNavActivation}
-                  className={`flex min-h-11 w-full items-center gap-3 rounded-xl px-3 text-left text-sm font-semibold transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 ${
-                    active
-                      ? "bg-blue-600/70 text-white shadow-[0_12px_30px_rgba(37,99,235,0.32)]"
-                      : enabled
-                        ? "text-slate-200 hover:bg-white/5"
-                        : "cursor-not-allowed text-slate-500 opacity-70"
-                  }`}
+                  onClick={view ? () => handleNavSelect(view) : blockInactiveNavActivation}
+                  className={buttonClass}
                 >
-                  <Icon className="size-5" aria-hidden="true" />
-                  {label}
+                  {buttonContent}
                 </button>
+              ) : (
+                <Tooltip key={item.labelKey}>
+                  <TooltipTrigger
+                    type="button"
+                    aria-disabled="true"
+                    onClick={blockInactiveNavActivation}
+                    className={buttonClass}
+                  >
+                    {buttonContent}
+                  </TooltipTrigger>
+                  {title && <TooltipContent>{title}</TooltipContent>}
+                </Tooltip>
               );
             })}
           </nav>
@@ -611,26 +630,30 @@ export function App() {
             </div>
 
             <div className="flex items-center justify-between text-slate-400">
-              <button
-                type="button"
-                aria-disabled={true}
-                aria-label={t("settingsComingSoon")}
-                title={t("settingsComingSoon")}
-                onClick={preventUnavailableAction}
-                className="inline-flex cursor-not-allowed items-center justify-center rounded-xl p-2 text-slate-600 transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300"
-              >
-                <Settings className="size-5" aria-hidden="true" />
-              </button>
-              <button
-                type="button"
-                aria-disabled={true}
-                aria-label={t("helpComingSoon")}
-                title={t("helpComingSoon")}
-                onClick={preventUnavailableAction}
-                className="inline-flex cursor-not-allowed items-center justify-center rounded-xl p-2 text-slate-600 transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300"
-              >
-                <CircleHelp className="size-5" aria-hidden="true" />
-              </button>
+              <Tooltip>
+                <TooltipTrigger
+                  type="button"
+                  aria-disabled="true"
+                  aria-label={t("settingsComingSoon")}
+                  onClick={preventUnavailableAction}
+                  className="inline-flex cursor-not-allowed items-center justify-center rounded-xl p-2 text-slate-600 transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300"
+                >
+                  <Settings className="size-5" aria-hidden="true" />
+                </TooltipTrigger>
+                <TooltipContent>{t("settingsComingSoon")}</TooltipContent>
+              </Tooltip>
+              <Tooltip>
+                <TooltipTrigger
+                  type="button"
+                  aria-disabled="true"
+                  aria-label={t("helpComingSoon")}
+                  onClick={preventUnavailableAction}
+                  className="inline-flex cursor-not-allowed items-center justify-center rounded-xl p-2 text-slate-600 transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300"
+                >
+                  <CircleHelp className="size-5" aria-hidden="true" />
+                </TooltipTrigger>
+                <TooltipContent>{t("helpComingSoon")}</TooltipContent>
+              </Tooltip>
             </div>
           </div>
         </aside>
@@ -641,26 +664,45 @@ export function App() {
               const { label, enabled, active, title } = navButtonState(item);
               const { icon: Icon, view } = item;
 
-              return (
+              const buttonClass = `inline-flex min-h-10 shrink-0 items-center gap-2 rounded-xl px-3 text-sm font-semibold transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 ${
+                active
+                  ? "bg-blue-600/70 text-white"
+                  : enabled
+                    ? "text-slate-200 hover:bg-white/5"
+                    : "cursor-not-allowed text-slate-500 opacity-70"
+              }`;
+
+              const buttonContent = (
+                <>
+                  <Icon className="size-4" aria-hidden="true" />
+                  {label}
+                </>
+              );
+
+              return enabled ? (
                 <button
                   key={item.labelKey}
                   type="button"
                   aria-current={active ? "page" : undefined}
                   aria-label={`${label} ${t("compactViewSuffix")}`}
-                  aria-disabled={enabled ? undefined : true}
-                  title={title}
-                  onClick={enabled && view ? () => handleNavSelect(view) : blockInactiveNavActivation}
-                  className={`inline-flex min-h-10 shrink-0 items-center gap-2 rounded-xl px-3 text-sm font-semibold transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 ${
-                    active
-                      ? "bg-blue-600/70 text-white"
-                      : enabled
-                        ? "text-slate-200 hover:bg-white/5"
-                        : "cursor-not-allowed text-slate-500 opacity-70"
-                  }`}
+                  onClick={view ? () => handleNavSelect(view) : blockInactiveNavActivation}
+                  className={buttonClass}
                 >
-                  <Icon className="size-4" aria-hidden="true" />
-                  {label}
+                  {buttonContent}
                 </button>
+              ) : (
+                <Tooltip key={item.labelKey}>
+                  <TooltipTrigger
+                    type="button"
+                    aria-label={`${label} ${t("compactViewSuffix")}`}
+                    aria-disabled="true"
+                    onClick={blockInactiveNavActivation}
+                    className={buttonClass}
+                  >
+                    {buttonContent}
+                  </TooltipTrigger>
+                  {title && <TooltipContent>{title}</TooltipContent>}
+                </Tooltip>
               );
             })}
           </nav>
@@ -709,15 +751,17 @@ export function App() {
                         aria-describedby={selectionError && selectionErrorSource === "youtube" ? "selection-error" : undefined}
                       />
                       {youtubeUrl && !analysisInFlight && !isStarting && !isImporting ? (
-                        <button
-                          type="button"
-                          onClick={handleClearYoutubeUrl}
-                          className="absolute right-1 top-1/2 inline-flex size-8 -translate-y-1/2 items-center justify-center rounded-md text-slate-400 transition hover:bg-white/10 hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300"
-                          aria-label={t("clearYoutubeUrl")}
-                          title={t("clearYoutubeUrl")}
-                        >
-                          <X className="size-4" aria-hidden="true" />
-                        </button>
+                        <Tooltip>
+                          <TooltipTrigger
+                            type="button"
+                            onClick={handleClearYoutubeUrl}
+                            className="absolute right-1 top-1/2 inline-flex size-8 -translate-y-1/2 items-center justify-center rounded-md text-slate-400 transition hover:bg-white/10 hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300"
+                            aria-label={t("clearYoutubeUrl")}
+                          >
+                            <X className="size-4" aria-hidden="true" />
+                          </TooltipTrigger>
+                          <TooltipContent>{t("clearYoutubeUrl")}</TooltipContent>
+                        </Tooltip>
                       ) : null}
                     </div>
                   </div>
@@ -756,17 +800,29 @@ export function App() {
                     {t("saveProject")}
                   </Button>
                 ) : (
-                  <Button
-                    aria-disabled="true"
-                    title={t("saveRequiresAnalysis")}
-                    onClick={preventUnavailableAction}
-                    variant="outline"
-                    className="min-h-11 border-white/10 bg-white/5 font-semibold text-slate-100"
-                    aria-label={t("saveProject")}
-                  >
-                    <Save className="mr-2 size-4" aria-hidden="true" />
-                    {t("saveProject")}
-                  </Button>
+                  <>
+                    <Tooltip>
+                      <TooltipTrigger
+                        render={
+                          <Button
+                            aria-disabled="true"
+                            aria-describedby="save-project-unavailable-reason"
+                            onClick={preventUnavailableAction}
+                            variant="outline"
+                            className="min-h-11 border-white/10 bg-white/5 font-semibold text-slate-100"
+                            aria-label={t("saveProject")}
+                          />
+                        }
+                      >
+                        <Save className="mr-2 size-4" aria-hidden="true" />
+                        {t("saveProject")}
+                      </TooltipTrigger>
+                      <TooltipContent>{t("saveRequiresAnalysis")}</TooltipContent>
+                    </Tooltip>
+                    <span id="save-project-unavailable-reason" className="sr-only">
+                      {t("saveRequiresAnalysis")}
+                    </span>
+                  </>
                 )}
                 <Button
                   onClick={handleStartAnalysis}

apps/desktop/src/App.unavailableSave.test.tsx

@@ -0,0 +1,58 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { expect, it, vi } from "vitest";
+import { App } from "./App";
+
+vi.mock("./features/score/pdfjs", () => ({
+  configureScorePdfWorker: vi.fn(),
+  loadScorePdf: vi.fn(() => ({
+    promise: Promise.resolve({ numPages: 1, getPage: vi.fn() }),
+    destroy: vi.fn(() => Promise.resolve())
+  }))
+}));
+
+it("keeps unavailable Save focusable without native-title-only help", () => {
+  const languageSpy = vi.spyOn(window.navigator, "language", "get").mockReturnValue("en-US");
+
+  try {
+    render(<App />);
+
+    const saveButton = screen.getByRole("button", { name: /save project/i });
+    expect(saveButton).toHaveAttribute("aria-disabled", "true");
+    expect(saveButton).not.toHaveAttribute("disabled");
+    expect(saveButton).not.toHaveAttribute("title");
+
+    const descriptionId = saveButton.getAttribute("aria-describedby");
+    expect(descriptionId).toBeTruthy();
+    expect(document.getElementById(descriptionId!)).toHaveTextContent(
+      "Analyze a song to enable saving"
+    );
+
+    fireEvent.click(saveButton);
+    expect(saveButton).toHaveAttribute("aria-disabled", "true");
+  } finally {
+    languageSpy.mockRestore();
+  }
+});
+
+it("keeps App icon tooltip triggers free of native title fallbacks", () => {
+  const languageSpy = vi.spyOn(window.navigator, "language", "get").mockReturnValue("en-US");
+
+  try {
+    render(<App />);
+
+    const settingsButton = screen.getByRole("button", { name: /settings coming soon/i });
+    const helpButton = screen.getByRole("button", { name: /help coming soon/i });
+    expect(settingsButton).not.toHaveAttribute("title");
+    expect(helpButton).not.toHaveAttribute("title");
+
+    const youtubeInput = screen.getByRole("textbox", { name: /youtube url/i });
+    fireEvent.change(youtubeInput, {
+      target: { value: "https://youtube.com/watch?v=abc123DEF45" }
+    });
+
+    const clearButton = screen.getByRole("button", { name: /clear youtube url/i });
+    expect(clearButton).not.toHaveAttribute("title");
+  } finally {
+    languageSpy.mockRestore();
+  }
+});

apps/desktop/src/components/ui/tooltip.resilience.test.tsx

@@ -0,0 +1,51 @@
+import { fireEvent, render, screen } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"
+
+describe("Tooltip resilience contract", () => {
+  it("keeps Base UI trigger button semantics and native props", () => {
+    const onClick = vi.fn()
+
+    render(
+      <Tooltip>
+        <TooltipTrigger
+          type="button"
+          aria-disabled="true"
+          aria-label="Settings coming soon"
+          className="focus-contract"
+          onClick={onClick}
+        >
+          Settings
+        </TooltipTrigger>
+        <TooltipContent>Settings coming soon</TooltipContent>
+      </Tooltip>
+    )
+
+    const trigger = screen.getByRole("button", { name: "Settings coming soon" })
+    expect(trigger.tagName).toBe("BUTTON")
+    expect(trigger).toHaveAttribute("type", "button")
+    expect(trigger).toHaveAttribute("aria-disabled", "true")
+    expect(trigger).toHaveClass("focus-contract")
+
+    fireEvent.click(trigger)
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it("bounds expanded locale copy and disables decorative motion when requested", () => {
+    render(
+      <Tooltip open>
+        <TooltipTrigger aria-label="Settings coming soon">Settings</TooltipTrigger>
+        <TooltipContent>
+          Einstellungen sind in dieser Version noch nicht verfügbar und werden später bereitgestellt.
+        </TooltipContent>
+      </Tooltip>
+    )
+
+    const tooltipContent = document.querySelector('[data-slot="tooltip-content"]')
+    expect(tooltipContent).toBeTruthy()
+    expect(tooltipContent).toHaveClass("max-w-[min(20rem,calc(100vw-2rem))]")
+    expect(tooltipContent).toHaveClass("break-words")
+    expect(tooltipContent).toHaveClass("motion-reduce:transition-none")
+  })
+})

apps/desktop/src/components/ui/tooltip.tsx

@@ -36,8 +36,8 @@ function TooltipContent({
         <TooltipPrimitive.Popup
           data-slot="tooltip-content"
           className={cn(
-            "bg-primary text-primary-foreground w-fit rounded-md px-3 py-1.5 text-xs text-balance",
-            "data-[starting-style]:opacity-0 data-[ending-style]:opacity-0 transition-opacity",
+            "bg-primary text-primary-foreground w-fit max-w-[min(20rem,calc(100vw-2rem))] break-words rounded-md px-3 py-1.5 text-xs text-balance",
+            "data-[starting-style]:opacity-0 data-[ending-style]:opacity-0 transition-opacity motion-reduce:transition-none",
             className
           )}
           {...props}