mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 07:52:24 +00:00
thePR0M3TH3ANandClaude Opus 4.8
8e7c6bc325
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]>
2.7 KiB
2.7 KiB
bitvid First-Run Experience (Onboarding) — Plan
Goal: escort fresh logins through the tool with a guided, skippable tour — spotlight + accent-glow highlights, popover explanations — and route them into the two setup flows that unlock the product (storage for uploading, NWC for zapping). All state is local (static client, no backend).
Locked decisions (2026-07-02, maintainer approved)
- Hand-rolled tour engine, no dependency (
js/ui/onboarding/tourEngine.js). Spotlight = one scrim element whose hugebox-shadowdims everything except a cutout over the anchor; an::afterring pulses with--color-accent/--color-accent-strong(theme-aware glow). Positioning via CSS custom properties set from JS (style.setProperty— the codebase's sanctioned pattern); all visuals in an injected stylesheet using design tokens only. - Anchors reuse existing stable selectors (
data-testidadded for e2e + sidebar ids). Steps whose anchor is missing in the current layout are skipped automatically, so one script serves desktop + mobile. - Once per pubkey per device (
bitvid:onboarding:v1map in localStorage — same shape assettingsRestorePrompt's offered-flags). Fully skippable (Skip button, Esc), keyboard navigable (arrows), and re-launchable from the profile modal footer ("Take the tour",force: true). - Trigger: 3.5s after login (feed rendered thanks to the warm cold-boot work; the settings-restore prompt's 2s window — which only fires for accounts with synced settings, i.e. NOT first-run users — has passed). Never blocks login.
- Final card = setup CTAs: "Set up storage" / "Connect wallet" deep-link
into the profile modal panes (
profileController.show("storage"|"wallet")).
Phases
- Phase 1 (BUILT): tour engine + spotlight/glow CSS, bitvid step script (welcome → feeds → subscriptions → upload → profile → setup CTAs), first-login trigger, per-pubkey flag, "Take the tour" relaunch button.
- Phase 2: "Getting started" checklist card (verify relays ✓, follow 3 channels ✓, set up storage ✓, connect wallet ✓, first upload ✓) — persistent and dismissible; catches users who skip the tour.
- Phase 3: empty-state upgrades — every empty feed/pane teaches + CTA (suggested channels from trust seeds in an empty For You / Subscriptions).
- Phase 4: fresh-npub bootstrap — hook the existing
generateauth provider into a "Create account" flow with a REQUIRED key-backup step, then inline kind-0 profile setup (name + avatar), then the tour.
Non-goals
- No server-side anything (static client rule).
- No tour analytics/telemetry.
- The tour never performs actions for the user — it points and deep-links only.