[onboarding] First-run guided tour with spotlight + accent glow (#59, phase 1)

New-user onboarding per docs/onboarding-plan.md: on the first login of a pubkey
on a device, a skippable guided tour escorts the user around bitvid — a scrim
dims the page with a spotlight CUTOUT over each step's anchor, ringed by a
pulsing glow driven by the theme's accent tokens, plus an anchored popover with
Back/Next/Skip, progress dots, and arrow/Esc keyboard nav.

- js/ui/onboarding/tourEngine.js: dependency-free engine. Spotlight = one
  element whose 200vmax box-shadow (--surface-overlay-darker) dims everything
  except the cutout; an ::after ring animates between --color-accent and
  --color-accent-strong. Positioning via CSS custom properties set from JS (the
  sanctioned dynamic-var pattern; visual styling lives in an injected token-only
  stylesheet). Steps with missing anchors auto-skip, so one script serves all
  layouts. Repositions on resize/scroll.
- js/ui/onboarding/bitvidTour.js: the step script (welcome → feeds →
  subscriptions → upload → profile → setup CTAs that deep-link into the storage
  and wallet panes via profileController.show).
- js/services/onboardingService.js: once-per-pubkey-per-device flags
  (bitvid:onboarding:v1, settingsRestorePrompt-style).
- app.maybeOfferOnboardingTour fires 3.5s after login (feed already rendered
  thanks to the warm cold-boot work; never blocks login);
  app.startOnboardingTour({force}) + a "Take the tour" button in the profile
  modal footer make it re-launchable.
- Lint allowlists: tourEngine.js added to the inline-style allowlist (CSS-var
  positioning, VideoCard precedent) and the design-token ALLOWED_FILES
  (injected stylesheet geometry, RevertModal precedent) — all colors are tokens.

Tests: tests/onboarding-tour.test.mjs (5 — flag lifecycle, tour render/advance/
finish, skip teardown, missing-anchor exclusion, once-vs-force offering, final
CTA deep-link + completion). Lint + build green.

Phases 2-4 (getting-started checklist, empty-state upgrades, fresh-npub create-
account + key backup + kind-0 bootstrap) tracked in the plan + TODO #59.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

js/ui/profileModalController.js

@@ -662,6 +662,7 @@ export class ProfileModalController {
     this.lockNowButton = document.getElementById("profileLockNowBtn") || null;
     this.mobileLockNowButton =
       document.getElementById("profileMobileLockNowBtn") || null;
+    this.takeTourButton = document.getElementById("profileTakeTourBtn") || null;
     this.channelLink = document.getElementById("profileChannelLink") || null;
     this.addAccountButton =
       document.getElementById("profileAddAccountBtn") || null;
@@ -1715,6 +1716,22 @@ export class ProfileModalController {
       this.mobileLockNowButton.addEventListener("click", handleLockNow);
     }
 
+    if (this.takeTourButton instanceof HTMLElement) {
+      this.takeTourButton.addEventListener("click", () => {
+        // Close the modal first so the tour spotlights the app, not the modal.
+        try {
+          this.hide({ silent: true });
+        } catch (error) {
+          devLogger.warn("[profileModal] Failed to hide before tour:", error);
+        }
+        try {
+          this.services?.startOnboardingTour?.();
+        } catch (error) {
+          devLogger.warn("[profileModal] Failed to start tour:", error);
+        }
+      });
+    }
+
     if (this.channelLink instanceof HTMLElement) {
       this.channelLink.addEventListener("click", (event) => {
         event.preventDefault();