[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]>

scripts/check-design-tokens.mjs

@@ -20,6 +20,9 @@ const IGNORED_DIRECTORIES = new Set([
 const IGNORED_EXTENSIONS = new Set([".min.js", ".map"]);
 const ALLOWED_FILES = new Set([
   "js/ui/components/RevertModal.js",
+  // Guided-tour injected stylesheet (colors are all theme tokens; the raw
+  // lengths are spotlight/popover geometry, same precedent as RevertModal).
+  "js/ui/onboarding/tourEngine.js",
   "css/tokens.css",
 ]);
 const LENGTH_PATTERN = /\d+(?:\.\d+)?(?:px|rem)\b/gim;

scripts/check-inline-styles.mjs

@@ -53,6 +53,13 @@ const VIOLATION_ALLOWLIST = new Map([
     "js/ui/components/VideoCard.js",
     new Set(["Direct .style usage"]),
   ],
+  [
+    // Guided-tour spotlight/popover positioning via CSS custom properties
+    // (style.setProperty("--bv-tour-*") — the same sanctioned dynamic-var
+    // pattern as VideoCard). All visual styling lives in its stylesheet.
+    "js/ui/onboarding/tourEngine.js",
+    new Set(["Direct .style usage"]),
+  ],
   [
     "torrent/app.js",
     new Set(["Direct .style usage"]),