feat(web): simpler, hand-drawn onboarding focused on Loom, recording and uploads

[richiemcilroy]

Replaces the five-step web onboarding (name, organization name and logo, custom domain upsell, seat pricing, desktop download) with a short flow built around what people came to do: move their videos from Loom, record a video, upload a video, or join a team they were invited to.

The new flow is: say your name, pick where to start, then do it. Each path page has a looping hand-drawn explainer in the same doodle style as #2312 (boiling ink outlines, strokes that draw themselves, sparks, and a demo cursor). The cursor acts out the task in three phases, and the three numbered steps beside it light up in sync, so it's clear what to do and what happens next.

New account

The name step is a single field. The card on the right shows how you'll appear when you share and updates as you type. Your organization is named after you automatically (you can rename it in settings), so the separate organization step is gone.

The start step offers three cards, Loom first, plus "I'll look around first". People who sign up with Google already have a name, so they skip straight here. Until now they skipped onboarding entirely.

Bring videos from Loom

• The link is checked as soon as you paste it: a drawn tick when it's valid, a plain-language error when it isn't. The hint under the field explains where to find the link on Loom.
• Pro accounts import right on the page and get a success state with "Go to my Caps" or "Import another".
• Loom import stays a Pro feature. Free accounts see an honest note with a link to record for free instead. Upgrading from this step returns to it with the link still filled in, and the page waits for the upgrade to confirm.
• Admins and owners get a link to bulk import from a CSV.
• Sign-ups that start from the "migrate from Loom" pages (/signup?next=/dashboard/import/loom?url=…) land on this step after the name step, with their link already filled in.

Record

"Record in your browser" is the fastest option and opens the browser recorder straight away (/dashboard/caps/record?recorder=browser). There's also the desktop app, with your platform detected and short install steps after you download, and the Chrome extension, shown only in Chrome. On phones the app card offers to copy the download link instead.

Upload

The dropzone has a hand-drawn border and works with drag and drop, click or tap. Progress uses the squiggle line from #2312, and the finished state links straight to the new video. Uploads stay Pro-only, with the same upgrade-and-return behavior as Loom.

Joining a team

The invite page now matches the rest of onboarding and has its own explainer. When you're signed out, Join goes to sign-up and brings you back to the invite. When you're signed in as the invited address, it's one click and you land in onboarding with your team's name. When you're signed in as someone else, the page says so up front and offers to switch accounts, instead of failing with a toast after you press Accept. The invited address is partly masked.

Phones and tablets

All steps were checked at 360, 390, 820, 1280, 1440 and 1920 px wide. On touch screens, hover effects are off and the dropzone says "Choose a video".

Reduced motion

With reduced motion turned on, every explainer shows one finished, readable frame instead of looping.

Before

How it works

• Who sees it. New accounts are created with onboardingSteps.getStarted = false. The dashboard sends them to onboarding until they pick a start or choose to look around. Existing accounts never have this flag, so nobody already using Cap is pulled back into onboarding. Accounts without a name still get the name step, as before. SSO-provisioned accounts are unchanged.
• New getStarted RPC step. It marks the old step flags and onboarding_completed_at, creates an organization if the user has none (for example an invitee who declined), and renames a default "My Organization" after the person. Opening any path step marks onboarding done, so leaving to the dashboard never bounces you back. skipToDashboard sets the new flag too.
• Old URLs. /onboarding/organization-setup, /custom-domain and /invite-team redirect to the start step, and /download redirects to the record step.
• Remembered destinations. A remembered sign-up destination (cap_onboarding_next) routes Loom, upload and record links to the matching step. Any other dashboard destination is where "I'll look around first" goes. Invite links are ignored, and the cookie is cleared when an invite is accepted.
• Checkout return. UpgradeModal and /api/settings/billing/subscribe accept an optional returnPath, validated as a same-origin path. Success and cancel both come back to it.
• Recorder. WebRecorderDialog gets a defaultOpen prop. This touches the component signature that feat: bring desktop Studio UI and local playback to web #2312 also changes, so expect a one-line conflict.
• Upload toast. importMediaFile gets showSuccessToast so onboarding can show its own success state.
• Database. No migration; the only schema change is the TypeScript type of the JSON column.
• Removed. The old organization setup, custom domain, seat pricing and download steps. Custom domains and seats are still available in settings and billing.

Testing

• Unit tests for step routing, intent mapping, name splitting, email masking and checkout return URLs; getStarted backend tests for renaming, team members, and missing or deleted organizations. The full web unit suite passes (242 files, 3,429 tests).
• Biome on the touched files, tsc -b apps/web, and tsc for web-backend, web-domain and database.
• End-to-end with Playwright against a local stack (MySQL and MinIO), including a real Loom import of a public video and a real upload that plays on the share page. All 22 behavior checks pass:

Behavior checks

PASS  /onboarding redirects to /onboarding/start
PASS  /onboarding/welcome redirects to /onboarding/start
PASS  /onboarding/organization-setup redirects to /onboarding/start
PASS  /onboarding/custom-domain redirects to /onboarding/start
PASS  /onboarding/invite-team redirects to /onboarding/start
PASS  /onboarding/download redirects to /onboarding/record
PASS  /onboarding/nope redirects to /onboarding/start
PASS  named account still choosing a start is sent to the start step
PASS  existing account without the new flag stays on the dashboard
PASS  existing account part-way through the old flow stays on the dashboard
PASS  account without a name is asked for one
PASS  path steps wait until there's a name
PASS  new account that already has a name (Google) skips the name step
PASS  looking around first completes onboarding
PASS  completed account is not sent back to onboarding
PASS  new account is created with the get started flag
PASS  new account starts with its own organization
PASS  signing up from a Loom import link lands on the Loom step with the link filled in
PASS  the organization is named after the person
PASS  opening a path step marks onboarding complete
PASS  a non-Loom link shows a friendly error
PASS  reduced motion renders static explainer frames

• A manual walkthrough in desktop Chrome: sign-up, name, start, upload, Loom validation and the upgrade dialog, then the recorder opening on the dashboard.