From ab1700a843ebd8a1b5397b081392ae083a2aa55f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Sat, 16 May 2026 18:42:02 +0200
Subject: [PATCH] fix(onboarding): really stop spotlight tour from blocking the
 quick-add button
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first attempt at the F2 fix (f9b8f3bd) split the spotlight tour
backdrop into four rectangular dim panels around the spotlight rect
and opted each one back into pointer-events: auto with its own
onClick={handleSkip}. The intent was to keep the spotlighted target
clickable while preserving the "tap backdrop to dismiss" affordance.

The flaw: tour-step 1 on the dashboard spotlights the tile-strip,
which sits in the middle of the page. The header "Add" button sits
ABOVE the spotlight. The TOP dim strip (rendered from y=0 down to
where the spotlight begins) therefore covered the entire header
area, so the very target the F2 audit named — the header Add
dropdown — was still being eaten, just by a smaller rectangle.
The four-panel split fixed exactly ONE coordinate (inside the
spotlight rect) and broke every coordinate outside it that a real
user might want to click during the tour: header buttons, the
user-menu avatar, sidebar links, the locale switcher.

This commit ships the contract that Joyride / Shepherd / Intro.js
have all standardised on: the dim is purely visual. The whole
tour layer is pointer-events: none; only the tooltip card opts
back into hit-testing. The four-panel split survives because it
still serves the visual purpose of NOT dimming the spotlighted
target, but each panel is now a <div aria-hidden="true"> with
pointer-events: none — no onClick, no aria-label, no interactive
semantics. The center-placement fallback follows the same shape.
The tooltip's onClick={(e) => e.stopPropagation()} guard came off
because nothing bubbles to the dim any more. Tour state (Skip,
Back, Next) lives entirely on the tooltip's footer buttons,
matching the affordance users expect and keyboard-accessible via
the existing Esc shortcut.

The e2e regression spec at e2e/onboarding-tour-passthrough.spec.ts
gained a third case and tightened the first one. Case 1 now runs
document.elementsFromPoint at the quick-add button's centre, walks
the stack, and asserts that NO element belonging to the tour
overlay has computed pointer-events !== "none". This pinpoints the
regression instead of observing the symptom. Case 2 swapped from
"click a dim strip skips" (an artefact of the failed intermediate
fix) to "the explicit Skip button in the tooltip dismisses the
tour". Case 3 reads computed pointer-events from every
[data-testid="onboarding-tour-dim"] and asserts each is "none" —
the load-bearing invariant the F2 regression violated.

Quality gates: typecheck clean, eslint clean on the touched files,
all 43 onboarding unit tests pass, all 6 F2 e2e cases pass locally
(3 cases x chromium-desktop + chromium-mobile).
---
 .planning/round-v1433-f2-e2e-fix-report.md    | 124 +++++++++++++++
 e2e/onboarding-tour-passthrough.spec.ts       | 149 ++++++++++++++----
 .../onboarding/__tests__/tour.test.tsx        |   6 +-
 src/components/onboarding/tour.tsx            |  82 +++++-----
 4 files changed, 288 insertions(+), 73 deletions(-)
 create mode 100644 .planning/round-v1433-f2-e2e-fix-report.md

diff --git a/.planning/round-v1433-f2-e2e-fix-report.md b/.planning/round-v1433-f2-e2e-fix-report.md
new file mode 100644
index 000000000..a78d2532c
--- /dev/null
+++ b/.planning/round-v1433-f2-e2e-fix-report.md
@@ -0,0 +1,124 @@
+# v1.4.33 F2 — onboarding tour click-blocker, real fix
+
+## Scope
+
+Phase-3-prep flagged that the F2 e2e regression spec at
+`e2e/onboarding-tour-passthrough.spec.ts` still fails on both
+desktop and mobile after the first attempt at the fix
+(commit `f9b8f3bd` — `fix(onboarding): stop spotlight tour from
+intercepting dashboard clicks`). This report covers the diagnosis,
+the real fix, and the hardened regression guard that now ships on
+develop.
+
+## Root cause
+
+The audit finding (`.planning/round-v1433-audit-runtime.md` F2) was
+that the spotlight tour rendered a single full-viewport `<button>`
+with a `clip-path` punching a visual hole around the spotlight.
+`clip-path` only affects painting — the button's hit-box still
+covered every pixel, so clicks aimed at the underlying page hit the
+dim layer and ran `handleSkip` instead of the intended target. The
+worst-case symptom: a brand-new user who landed on the dashboard
+with `onboarding_tour_completed=false` could not click the header
+"Add" dropdown until the tour was dismissed.
+
+The initial fix split the single backdrop into up to four
+rectangular dim panels (top / bottom / left / right strips around
+the spotlight rect), set `pointer-events: none` on the tour root,
+and opted each panel back in with `pointer-events: auto` plus its
+own `onClick={handleSkip}`. The intent was: keep the spotlighted
+target clickable, keep the rest of the dim dismissable on tap.
+
+The flaw: the dashboard's tour-step 1 spotlights the tile-strip,
+which sits in the middle of the page, while the header "Add"
+button sits at the top, ABOVE the spotlight. The TOP dim strip
+(rendered from y=0 down to where the spotlight begins) therefore
+covered the entire header area — so the same click that the
+audit named as the regression target was still being eaten, just
+by a smaller rectangle. The four-panel split addressed exactly
+ONE coordinate (inside the spotlight rect) and broke every other
+coordinate outside it that a real user might want to click during
+the tour: header buttons, the user-menu avatar, sidebar links,
+the locale switcher.
+
+The forensic check is straightforward: at the centre of the
+quick-add button, `document.elementsFromPoint` returns the tour's
+top dim `<button>` above the actual quick-add button. The dim's
+`getComputedStyle(...).pointerEvents` is `"auto"`. The click
+follows the topmost interactive element. Result: skip fires, the
+dropdown never opens.
+
+## The shipped fix
+
+The real contract — the one Joyride, Shepherd, and Intro.js have
+shipped for years — is that the dim layer is purely visual. The
+whole tour overlay is `pointer-events: none`; only the tooltip
+card opts back into hit-testing. Tour state (Skip / Back / Next)
+lives entirely on the tooltip's footer buttons. The page
+underneath stays fully usable while the tour is up. Users dismiss
+via the explicit "Skip tour" button (or the keyboard's `Esc`,
+which was already wired).
+
+Concretely in `src/components/onboarding/tour.tsx`:
+
+- The 4-panel split survives because it still serves the visual
+  purpose of NOT dimming the spotlighted target rectangle, but
+  each panel is now a `<div aria-hidden="true">` with
+  `pointer-events: none`. The `onClick={handleSkip}` and
+  `aria-label` came off — the panels carry no interactive
+  semantics any more.
+- The center-placement fallback (no spotlight target available)
+  follows the same shape: a single full-cover dim `<div>` that is
+  purely visual.
+- The tooltip card keeps `pointer-events: auto` and remains the
+  one and only interactive surface in the tour layer; its
+  `onClick={(e) => e.stopPropagation()}` came off (nothing to
+  stop bubbling to any more — the dim doesn't listen).
+- Comments on the file now spell out WHY the dim is purely
+  visual, in plain terms, with a reference to the failed
+  intermediate attempt so future hands don't reach for the same
+  rectangular-cover approach again.
+
+## E2E spec hardening
+
+`e2e/onboarding-tour-passthrough.spec.ts` now carries three test
+cases per viewport (chromium-desktop + chromium-mobile = 6 total):
+
+1. **Hinzufügen dropdown opens with the tour mounted on the
+   dashboard.** Forensic guard runs `document.elementsFromPoint`
+   at the quick-add button's centre, walks the stack, and
+   asserts that NO element belonging to the tour overlay has
+   computed `pointer-events !== "none"`. The actual click on the
+   button then asserts `aria-expanded="true"` and the dropdown
+   menu items appear. Pinpoints the regression instead of just
+   observing the symptom.
+2. **Explicit Skip button in the tooltip dismisses the tour.**
+   Replaces the previous "click a dim strip skips the tour" case
+   — that contract is gone now (dim is non-interactive). The
+   canonical skip surface is the footer button.
+3. **Dim panels render as non-interactive visual layers.** Reads
+   computed `pointer-events` from every
+   `[data-testid="onboarding-tour-dim"]` and asserts each is
+   `"none"`. This is the load-bearing invariant that the F2
+   regression violated.
+
+## Quality gates
+
+- `pnpm typecheck` — 0 errors
+- `pnpm exec eslint src/components/onboarding/tour.tsx src/components/onboarding/__tests__/tour.test.tsx e2e/onboarding-tour-passthrough.spec.ts` — clean
+- `pnpm test src/components/onboarding src/lib/onboarding` — 43/43 pass
+- `pnpm exec playwright test e2e/onboarding-tour-passthrough.spec.ts` — 6/6 pass (3 × desktop + 3 × mobile)
+
+The pre-existing flakes outside F2 (onboarding-flicker × 2,
+mobile-viewport × 1) stay as-is — they sit on other agents'
+fileset for v1.4.33.
+
+## Files touched
+
+- `src/components/onboarding/tour.tsx` — dim panels turned into
+  non-interactive `<div>`s; root pointer-events comments rewritten;
+  tooltip card's `stopPropagation` removed.
+- `e2e/onboarding-tour-passthrough.spec.ts` — three-case rewrite
+  with `elementsFromPoint` forensic guard.
+- `src/components/onboarding/__tests__/tour.test.tsx` — comment
+  refresh so the unit test's commentary matches the new contract.
diff --git a/e2e/onboarding-tour-passthrough.spec.ts b/e2e/onboarding-tour-passthrough.spec.ts
index 4e881e6ee..5e94b9237 100644
--- a/e2e/onboarding-tour-passthrough.spec.ts
+++ b/e2e/onboarding-tour-passthrough.spec.ts
@@ -6,23 +6,36 @@ import { STORAGE_STATE_PATH } from "./setup/global-setup";
  * v1.4.33 F2 regression guard — the onboarding spotlight tour overlay
  * MUST NOT intercept clicks on elements outside the spotlight area.
  *
- * Before the fix the tour rendered a single full-viewport `<button>` with
- * a `clip-path` punching a visual hole around the spotlight target. The
- * clip-path only changed paint — the button's hit-box still captured
- * every click in the viewport, so a new user could not click the header
- * "Hinzufügen" dropdown (or any other interactive element on the
- * dashboard) without the dim layer eating the click first. The audit
- * (`.planning/round-v1433-audit-runtime.md` F2) flagged this as a
- * Critical block: new users were effectively locked out.
+ * The original v1.4.15 tour rendered a single full-viewport `<button>`
+ * with a `clip-path` punching a hole around the spotlight. The clip-path
+ * only changed paint — the button's hit-box still captured every pixel,
+ * so a new user could not click the header "Hinzufügen" dropdown
+ * (or any other interactive element on the dashboard) without the dim
+ * layer eating the click first.
  *
- * The fix splits the dim backdrop into up to four rectangles around the
- * spotlight (top / bottom / left / right strips) and sets
- * `pointer-events: none` on the tour root so the spotlight area is
- * genuinely click-through. This spec proves the contract: with the
- * tour mid-step on the dashboard, clicking the header "Hinzufügen"
- * button opens its dropdown menu instead of skipping the tour.
+ * The first attempt at a fix split the dim into four panels around the
+ * spotlight rect and gave each panel an `onClick={handleSkip}` with
+ * `pointer-events: auto`. That made the spotlight area click-through
+ * but kept blocking every other interactive element on the page: the
+ * header sits ABOVE the tile-strip spotlight, so the TOP dim strip
+ * still intercepted the click on the Hinzufügen button — exactly the
+ * target the audit named. New users were still locked out.
+ *
+ * The shipped fix makes the dim purely visual. The whole tour layer is
+ * `pointer-events: none`; only the tooltip card opts back into hit
+ * testing. Tour state (Skip / Back / Next) lives entirely on the
+ * tooltip's footer buttons — matching the spotlight-tour conventions
+ * used by Joyride, Shepherd, and Intro.js. The page underneath stays
+ * fully usable during the tour.
+ *
+ * This spec encodes both halves of that contract:
+ *   1. Clicking the header Hinzufügen button mid-tour opens its
+ *      dropdown menu (no element on top of it is `pointer-events:
+ *      auto`).
+ *   2. Clicking the tooltip's explicit Skip button dismisses the tour.
+ *   3. Every dim panel computes `pointer-events: none`.
  */
-test.describe("v1.4.33 F2 — onboarding tour passes clicks through spotlight", () => {
+test.describe("v1.4.33 F2 — onboarding tour passes clicks through to the page", () => {
   test.use({ storageState: STORAGE_STATE_PATH });
 
   test.beforeEach(async ({ page }) => {
@@ -121,27 +134,70 @@ test.describe("v1.4.33 F2 — onboarding tour passes clicks through spotlight",
       page.locator('[data-testid="onboarding-tour-tooltip"]'),
     ).toBeVisible();
 
-    // The header "Hinzufügen" button lives outside the spotlight on
-    // step 1 (which spotlights the tile strip). Clicking it must open
-    // its dropdown menu, NOT dismiss the tour. With the old single-
-    // backdrop overlay this click hit the dim layer and called
-    // `handleSkip` instead.
+    // The header "Hinzufügen" button lives ABOVE the spotlight on
+    // step 1 (which spotlights the tile strip further down the page),
+    // so a naive "dim everything outside the spotlight rect" overlay
+    // covers it. The fix makes the entire tour layer pointer-events:
+    // none — every dim panel and the spotlight ring are visual only.
     const quickAddButton = page.locator('[data-tour-id="dashboard-quick-add"]');
     await expect(quickAddButton).toBeVisible();
+
+    // Forensic guard — at the quick-add button's centre, every element
+    // returned by `elementsFromPoint` that belongs to the tour overlay
+    // MUST be CSS-`pointer-events: none`. If any tour element above the
+    // button has `pointer-events: auto`, the button's click will be
+    // intercepted and the dropdown will not open. This assertion is the
+    // tight version of the regression — it pinpoints WHICH element on
+    // the stack is blocking, instead of just observing the symptom
+    // ("button click did not toggle aria-expanded").
+    const tourBlockers = await page.evaluate(() => {
+      const btn = document.querySelector<HTMLElement>(
+        '[data-tour-id="dashboard-quick-add"]',
+      );
+      if (!btn) return ["no-button"];
+      const rect = btn.getBoundingClientRect();
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      const stack = document.elementsFromPoint(x, y);
+      const offenders: string[] = [];
+      for (const el of stack) {
+        const tour = (el as HTMLElement).closest(
+          '[data-testid="onboarding-tour"]',
+        );
+        if (!tour) continue;
+        const style = window.getComputedStyle(el as HTMLElement);
+        if (style.pointerEvents !== "none") {
+          offenders.push(
+            `${(el as HTMLElement).tagName}#${(el as HTMLElement).id || "-"}.${
+              (el as HTMLElement).className || "-"
+            } pe=${style.pointerEvents}`,
+          );
+        }
+      }
+      return offenders;
+    });
+    expect(
+      tourBlockers,
+      "tour overlay must not place a pointer-events:auto element above the Hinzufügen button",
+    ).toEqual([]);
+
+    // Now the click — Radix's DropdownMenuTrigger flips aria-expanded
+    // to "true" and renders the menu items into a portal as
+    // role="menuitem". With the old single-backdrop overlay this click
+    // hit the dim layer and called `handleSkip`; with the four-panel
+    // overlay the TOP strip still intercepted it; with the shipped fix
+    // the dim is pointer-events:none and the click reaches the button.
     await quickAddButton.click();
 
-    // DropdownMenuTrigger toggles `aria-expanded` — Radix sets it to
-    // "true" once the menu is open. The menu items themselves render
-    // in a Radix portal as `role="menuitem"`.
     await expect(quickAddButton).toHaveAttribute("aria-expanded", "true");
     await expect(page.getByRole("menuitem").first()).toBeVisible();
 
     // The tour stays mounted — the click went to the underlying button,
-    // not the dim layer.
+    // not anything in the tour layer.
     await expect(tourRoot).toBeVisible();
   });
 
-  test("clicking a dim strip outside the spotlight still skips the tour", async ({
+  test("explicit Skip button in the tooltip dismisses the tour", async ({
     page,
   }) => {
     await page.goto("/", { waitUntil: "domcontentloaded" });
@@ -150,14 +206,43 @@ test.describe("v1.4.33 F2 — onboarding tour passes clicks through spotlight",
     const tourRoot = page.locator('[data-testid="onboarding-tour"]');
     await expect(tourRoot).toBeVisible({ timeout: 10_000 });
 
-    // The dim panels are the strips around the spotlight. Clicking any
-    // of them must skip the tour (preserves the "tap backdrop to
-    // dismiss" affordance the v1.4.15 design shipped with).
-    const dimPanel = page.locator('[data-testid="onboarding-tour-dim"]').first();
-    await expect(dimPanel).toBeVisible();
-    await dimPanel.click();
+    // The tooltip's footer Skip button is the canonical skip surface.
+    // The dim panels are purely visual (pointer-events: none) so the
+    // page underneath stays usable; users skip by clicking the explicit
+    // "Skip tour" control, which is also keyboard-accessible (Esc) and
+    // matches industry-standard spotlight-tour patterns.
+    const tooltip = page.locator('[data-testid="onboarding-tour-tooltip"]');
+    await expect(tooltip).toBeVisible();
+    await tooltip.getByRole("button", { name: /skip tour/i }).click();
 
-    // Tour unmounts. Hinzufügen stays usable.
+    // Tour unmounts.
     await expect(tourRoot).toBeHidden({ timeout: 5_000 });
   });
+
+  test("dim panels render as non-interactive visual layers", async ({
+    page,
+  }) => {
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await page.waitForLoadState("networkidle");
+
+    const tourRoot = page.locator('[data-testid="onboarding-tour"]');
+    await expect(tourRoot).toBeVisible({ timeout: 10_000 });
+
+    // Every dim panel must have computed `pointer-events: none`.
+    // This is the load-bearing invariant — the F2 regression was that
+    // these panels had pointer-events: auto and ate clicks aimed at
+    // real interactive elements behind them.
+    const dimPointerEvents = await page.evaluate(() => {
+      const panels = Array.from(
+        document.querySelectorAll<HTMLElement>(
+          '[data-testid="onboarding-tour-dim"]',
+        ),
+      );
+      return panels.map((el) => window.getComputedStyle(el).pointerEvents);
+    });
+    expect(dimPointerEvents.length).toBeGreaterThan(0);
+    for (const pe of dimPointerEvents) {
+      expect(pe).toBe("none");
+    }
+  });
 });
diff --git a/src/components/onboarding/__tests__/tour.test.tsx b/src/components/onboarding/__tests__/tour.test.tsx
index 4bf56bb11..ae74efea3 100644
--- a/src/components/onboarding/__tests__/tour.test.tsx
+++ b/src/components/onboarding/__tests__/tour.test.tsx
@@ -46,8 +46,10 @@ describe("<OnboardingTour>", () => {
 
   it("exposes a skip control with an accessible label", () => {
     const html = renderTour();
-    // The backdrop button doubles as a Skip control with aria-label,
-    // and the explicit footer Skip button.
+    // After v1.4.33 F2 the dim panels are purely visual
+    // (pointer-events: none) so skip lives entirely on the explicit
+    // tooltip-footer Skip button. The visible label still has to be
+    // there — both for sighted users and for screen readers.
     expect(html).toContain("Skip tour");
   });
 
diff --git a/src/components/onboarding/tour.tsx b/src/components/onboarding/tour.tsx
index 23745d50c..f5946e7a3 100644
--- a/src/components/onboarding/tour.tsx
+++ b/src/components/onboarding/tour.tsx
@@ -345,15 +345,24 @@ export function OnboardingTour({
   // header avatar) hit the dim layer and triggered Skip without forwarding
   // the click to the real target. New users were effectively locked out.
   //
-  // Fix: render the dim backdrop as up to four separate rectangles around
-  // the spotlight (top / bottom / left / right of the cutout) so the
-  // spotlight region itself is genuinely click-through. Each rectangle
-  // keeps the "click backdrop = Skip" affordance via its own onClick.
-  // When there is no spotlight rect we fall back to a single full-cover
-  // dim button (legacy center-placement contract — tooltip is centred and
-  // the underlying page is intentionally inert until the user advances).
+  // Initial fix (f9b8f3bd) split the dim into four rectangles around the
+  // spotlight with `pointer-events: auto` + an `onClick={handleSkip}` on
+  // each. That made the spotlight region click-through but kept blocking
+  // every other interactive element on the page (the header sits ABOVE
+  // the tile-strip spotlight, so the top dim strip still ate the click on
+  // the Hinzufügen dropdown — the very target the F2 audit named).
+  //
+  // The right contract: the dim is purely VISUAL. The whole tour layer is
+  // `pointer-events: none`, and only the tooltip card opts back into hit
+  // testing. Skip lives where users expect it — the explicit "Skip tour"
+  // button in the tooltip footer. The page underneath stays fully usable,
+  // matching the spotlight-tour conventions used by Joyride, Shepherd,
+  // and Intro.js. The four-panel split survives because it still serves
+  // the visual purpose of NOT dimming the spotlighted target, but the
+  // panels are now non-interactive `<div>`s without their own click
+  // handlers.
   const backdropClass =
-    "focus-visible:ring-primary cursor-default bg-black/70 transition-opacity duration-150 focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none motion-reduce:transition-none";
+    "pointer-events-none absolute bg-black/70 transition-opacity duration-150 motion-reduce:transition-none";
   const vw = typeof window !== "undefined" ? window.innerWidth : 0;
   const vh = typeof window !== "undefined" ? window.innerHeight : 0;
   const dimRects = rect
@@ -399,15 +408,15 @@ export function OnboardingTour({
       aria-modal="true"
       aria-labelledby="onboarding-tour-title"
       // `pointer-events-none` on the root: the outer container does NOT
-      // capture clicks. Children that need clicks (dim strips, tooltip)
-      // opt back in via `pointer-events-auto`. This guarantees the
-      // spotlight area passes pointer events through to the underlying
-      // page — the exact contract F2 needs.
+      // capture clicks. Only the tooltip card opts back in via
+      // `pointer-events-auto` below. This guarantees that every pixel of
+      // the underlying page — both inside AND outside the spotlight —
+      // passes pointer events through normally; the tour is purely a
+      // visual overlay with its own self-contained controls.
       className="pointer-events-none fixed inset-0 z-[200]"
     >
       {/* Spotlight outline — purely visual ring around the highlighted
-          target. `pointer-events-none` so a click on the ring still
-          reaches the underlying element. */}
+          target. */}
       {rect ? (
         <div
           aria-hidden="true"
@@ -422,39 +431,35 @@ export function OnboardingTour({
         />
       ) : null}
 
-      {/* Backdrop dim panels. Each panel sits OUTSIDE the spotlight rect
-          so the spotlighted target is fully click-through. A click on any
-          dim panel skips the tour (existing "tap backdrop to dismiss"
-          contract). `pointer-events-auto` reactivates click capture for
-          these specific rects only. */}
+      {/* Dim panels — purely visual. Each panel sits OUTSIDE the spotlight
+          rect so the spotlighted target keeps its full brightness. The
+          panels are `pointer-events-none` so the page underneath stays
+          fully clickable: the user can drive the Hinzufügen dropdown,
+          sidebar links, or header avatar mid-tour and only the
+          tooltip-footer Skip / Back / Next buttons drive tour state. */}
       {dimRects
         ? dimRects.map((r, idx) => (
-            <button
+            <div
               key={idx}
-              type="button"
-              aria-label={t("onboarding.tour.skip")}
+              aria-hidden="true"
               data-testid="onboarding-tour-dim"
-              className={`pointer-events-auto absolute ${backdropClass}`}
+              className={backdropClass}
               style={{
                 top: `${r.top}px`,
                 left: `${r.left}px`,
                 width: `${r.width}px`,
                 height: `${r.height}px`,
               }}
-              onClick={handleSkip}
             />
           ))
         : (
-          // Center-placement fallback (no spotlight target available).
-          // The legacy contract is to dim the whole viewport and let any
-          // click count as Skip — the tooltip is the only interactive
-          // surface in this branch.
-          <button
-            type="button"
-            aria-label={t("onboarding.tour.skip")}
+          // Center-placement fallback — no spotlight target available.
+          // Render a single full-cover dim layer. Still purely visual:
+          // skip / back / next live on the tooltip itself.
+          <div
+            aria-hidden="true"
             data-testid="onboarding-tour-dim"
-            className={`pointer-events-auto absolute inset-0 ${backdropClass}`}
-            onClick={handleSkip}
+            className={`${backdropClass} inset-0`}
           />
         )}
 
@@ -468,9 +473,11 @@ export function OnboardingTour({
         {t(stop.titleKey)}
       </p>
 
-      {/* Tooltip card — `pointer-events-auto` to opt back into click
-          capture (the root is `pointer-events-none` so the spotlight
-          area passes clicks through to the underlying page). */}
+      {/* Tooltip card — the only interactive surface in the tour.
+          `pointer-events-auto` opts back into click capture against the
+          root's `pointer-events-none`, so the card's buttons (Skip /
+          Back / Next) work while every other pixel of the overlay
+          passes clicks through to the underlying page. */}
       <div
         ref={tooltipRef}
         data-testid="onboarding-tour-tooltip"
@@ -481,9 +488,6 @@ export function OnboardingTour({
           left: `${tooltipPos.left}px`,
           width: `${TOOLTIP_WIDTH}px`,
         }}
-        // Stop click propagation so a click inside the card doesn't
-        // bubble to the backdrop's Skip handler.
-        onClick={(e) => e.stopPropagation()}
       >
         <header className="flex items-start justify-between gap-3">
           <div>