Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(onboarding): resume a dropped step from an email link (#8699)
juliawest26940aca9d3d
diff --git a/apps/marketing/src/features/marketing/core/navigation.ts b/apps/marketing/src/features/marketing/core/navigation.tsindex 3a7e46b0ca..ab5736f324 100644--- a/apps/marketing/src/features/marketing/core/navigation.ts+++ b/apps/marketing/src/features/marketing/core/navigation.ts@@ -44,14 +44,27 @@ export function routePhoneToMobileSignup(event: MouseEvent) {window.location.href = MOBILE_SIGNUP_HREF;}+function readOnboardingFlowStep(): string | null {+ // Resolve each store inside the try: reading `window.localStorage` itself+ // throws when the browser blocks it.+ for (const storage of [() => localStorage, () => sessionStorage]) {+ try {+ const value = storage().getItem('onboarding-flow-step');+ if (value !== null) return value;+ } catch {+ // This store can be blocked; the other may still hold the step.+ }+ }+ return null;+}+/** Full document navigation keeps the app and marketing CSS independent. */export function journeyHref() {if (typeof window === 'undefined') return '/app/signup';if (isPhoneBrowser()) return MOBILE_SIGNUP_HREF;+ const raw = readOnboardingFlowStep();try {- const active = JSON.parse(- sessionStorage.getItem('onboarding-flow-step') ?? 'null'- );+ const active = JSON.parse(raw ?? 'null');if (active?.user && active?.step) return '/app/onboarding';} catch {// An old or unavailable storage record must not prevent navigation.diff --git a/apps/marketing/src/features/setup/flow/shared.tsx b/apps/marketing/src/features/setup/flow/shared.tsxindex 5acebab56f..3e38dec02c 100644--- a/apps/marketing/src/features/setup/flow/shared.tsx+++ b/apps/marketing/src/features/setup/flow/shared.tsx@@ -3,8 +3,8 @@ import CheckIcon from '@phosphor/check.svg';import { Layer } from '@ui/components/Layer';import { For, onCleanup, onMount } from 'solid-js';-/** Where the flow persists its current step, so full-page OAuth round-trips- * (adding a Gmail inbox, Stripe checkout aborts) resume where they left. */+/** Where the app persists its current step (localStorage), so a later visit+ * and full-page OAuth round-trips resume where they left. */export { ONBOARDING_FLOW_STEP_STORAGE_KEY as FLOW_STEP_STORAGE_KEY } from '../core/onboardingHandoff';/** Where the flow persists its `?next` deep link — the inbox-link OAuthdiff --git a/apps/web/src/components/app/Layout.tsx b/apps/web/src/components/app/Layout.tsxindex 36fd6daa1a..3f24231fe6 100644--- a/apps/web/src/components/app/Layout.tsx+++ b/apps/web/src/components/app/Layout.tsx@@ -1,4 +1,3 @@-import { DEFAULT_ROUTE } from '@app/constants/defaultRoute';import { ROUTER_BASE_CONCAT } from '@app/constants/routerBase';import Banner from '@app/features/auth/banner/Banner';import { CalendarPermissionPrompt } from '@app/features/auth/CalendarPermissionPrompt';@@ -23,6 +22,7 @@ import {isAddInboxDialogOpen,} from '@app/features/inbox/AddInboxDialog';import { MacroMcpSetupModal } from '@app/features/integrations/mcp-setup/MacroMcpSetupModal';+import { onboardingRedirectPath } from '@app/features/onboarding/core/next-target';import { AiUsageLimitDialog } from '@app/features/paywall/AiUsageLimitDialog';import { observeAiUsageLimitMutations } from '@app/features/paywall/ai-usage-limit-handling';import { MobileSettingsProvider } from '@app/features/settings/context/mobile-settings';@@ -218,19 +218,12 @@ function useNewOnboardingRedirect() {if (data?.authenticated !== true || data.tutorialComplete !== false) {return;}- // Preserve the deep link the user arrived on (a shared doc, an invite):- // onboarding carries it as ?next and its finish() returns there instead of- // the post-setup landing. Base-relative so navigate() can resolve it- // against the router.+ // Preserve the deep link the user arrived on (a shared doc, an invite)+ // as ?next, and a lifecycle-email ?step, so finish() and the flow can+ // resume. Base-relative so navigate() can resolve it against the router.const target =location.pathname.slice(ROUTER_BASE_CONCAT.length - 1) + location.search;- const isGenericEntry = target === '/' || target.startsWith(DEFAULT_ROUTE);- navigate(- isGenericEntry- ? '/onboarding'- : `/onboarding?next=${encodeURIComponent(target)}`,- { replace: true }- );+ navigate(onboardingRedirectPath(target), { replace: true });});}diff --git a/apps/web/src/features/auth/EmailAuth.test.tsx b/apps/web/src/features/auth/EmailAuth.test.tsxindex 09e389437b..0717dc9deb 100644--- a/apps/web/src/features/auth/EmailAuth.test.tsx+++ b/apps/web/src/features/auth/EmailAuth.test.tsx@@ -16,7 +16,8 @@ const mocks = vi.hoisted(() => ({failure: vi.fn(),success: vi.fn(),linkId: 'oauth-link',- searchParams: {} as Record<string, string>,+ searchParams: {} as Record<string, string | string[]>,+ tutorialComplete: true as boolean,restore: vi.fn(),track: vi.fn(),openAddInbox: vi.fn(),@@ -59,7 +60,9 @@ vi.mock('@core/mobile/isNativeMobilePlatform', () => ({}));vi.mock('@queries/auth/user-info', () => ({invalidateAllAfterLogin: vi.fn(),- useUserInfoQuery: () => ({ data: { tutorialComplete: true } }),+ useUserInfoQuery: () => ({+ data: { tutorialComplete: mocks.tutorialComplete },+ }),}));vi.mock('@ui', () => ({Button: (props: JSX.ButtonHTMLAttributes<HTMLButtonElement>) => (@@ -105,6 +108,7 @@ const { EmailLinkCallback } = makeEmailAuthComponents({beforeEach(() => {vi.clearAllMocks();mocks.linkId = 'oauth-link';+ mocks.tutorialComplete = true;mocks.searchParams = { link_id: mocks.linkId };mocks.fetchProviders.mockResolvedValue({gmail: true,@@ -303,4 +307,26 @@ describe('consent that ended without a grant', () => {expect(mocks.restore).not.toHaveBeenCalled();expect(mocks.navigate).toHaveBeenCalledOnce();});++ it('returns a first-run user to the deep-linked onboarding step', async () => {+ mocks.tutorialComplete = false;+ mocks.searchParams = { link_id: 'oauth-link', step: 'plan' };+ render(() => <EmailLinkCallback />);+ await waitFor(() =>+ expect(mocks.navigate).toHaveBeenCalledWith('/onboarding?step=plan', {+ replace: true,+ })+ );+ });++ it('drops an unknown step when returning a first-run user to onboarding', async () => {+ mocks.tutorialComplete = false;+ mocks.searchParams = { link_id: 'oauth-link', step: 'nope' };+ render(() => <EmailLinkCallback />);+ await waitFor(() =>+ expect(mocks.navigate).toHaveBeenCalledWith('/onboarding', {+ replace: true,+ })+ );+ });});diff --git a/apps/web/src/features/auth/EmailAuth.tsx b/apps/web/src/features/auth/EmailAuth.tsxindex f25ff215cf..a9f54e97b8 100644--- a/apps/web/src/features/auth/EmailAuth.tsx+++ b/apps/web/src/features/auth/EmailAuth.tsx@@ -2,6 +2,7 @@ import { DEFAULT_ROUTE } from '@app/constants/defaultRoute';import { openAddInboxDialog } from '@app/features/inbox/AddInboxDialog';import { AdminConsentRequiredDialog } from '@app/features/inbox/AdminConsentRequiredDialog';import { ShareInboxConflictDialog } from '@app/features/inbox/ShareInboxConflictDialog';+import { onboardingPathWithStep } from '@app/features/onboarding/core/next-target';import { useAnalytics } from '@app/lib/analytics/analytics-context';import type { AppEvents } from '@app/lib/analytics/app-events';import { updateUserAuth } from '@core/auth';@@ -208,7 +209,7 @@ function EmailLinkCallback(props: Pick<EmailAuthParams, 'successPath'>) {!isNativeMobilePlatform() &&userInfoQuery.data?.tutorialComplete === false) {- navigate('/onboarding', { replace: true });+ navigate(onboardingPathWithStep(searchParams.step), { replace: true });return;}if (linkId && restoreLayoutBeforeConsent(linkId)) return;diff --git a/apps/web/src/features/onboarding/browser-test/README.md b/apps/web/src/features/onboarding/browser-test/README.mdindex 917f26749e..bbc1117f00 100644--- a/apps/web/src/features/onboarding/browser-test/README.md+++ b/apps/web/src/features/onboarding/browser-test/README.md@@ -28,6 +28,9 @@ bunx vite --config src/features/onboarding/browser-test/vite.config.tsthe fixture follows the system color scheme. Overrides survive simulated redirects.- `/?view=signup` shows the signed-out slides; Google sign-up continues into the flow.- `/?view=flow&next=/channel/x` shows the signed-in flow with a deep link.+- `/?view=flow&step=plan` opens that step. `step` must be a current step name.+ Progress is stored in localStorage, so a later load without the query stays+ on the saved step. Saved progress wins over `step`.Tests seed the world through `openFixture` in `fixture-page.ts`. They read theworld and the recorded analytics through `window.onboardingFixture`.diff --git a/apps/web/src/features/onboarding/browser-test/fixture.tsx b/apps/web/src/features/onboarding/browser-test/fixture.tsxindex 12a8429339..bcf3d2bd41 100644--- a/apps/web/src/features/onboarding/browser-test/fixture.tsx+++ b/apps/web/src/features/onboarding/browser-test/fixture.tsx@@ -132,6 +132,7 @@ function Fixture() {<Match when={true}><OnboardingFlowViewnext={params.next}+ step={params.step}checkoutReturn={parseCheckoutReturn(params)}onNavigate={(target) => land({ t: 'app', target })}onRedirect={(url) => location.assign(url)}diff --git a/apps/web/src/features/onboarding/browser-test/onboarding.browser.e2e.ts b/apps/web/src/features/onboarding/browser-test/onboarding.browser.e2e.tsindex 6c90d4ca32..0e8bd7422e 100644--- a/apps/web/src/features/onboarding/browser-test/onboarding.browser.e2e.ts+++ b/apps/web/src/features/onboarding/browser-test/onboarding.browser.e2e.ts@@ -90,12 +90,62 @@ test('a deep link survives the inbox OAuth round-trip', async ({ page }) => {await expectLanded(page, 'Entered Macro at /channel/launch');});+test('an email link opens the dropped step and a new session keeps later progress', async ({+ page,+}) => {+ await openFixture(page, '/?view=flow&step=plan', {+ emailAccounts: [+ {+ address: '[email protected]',+ isPrimary: true,+ ownerId: 'macro|[email protected]',+ },+ ],+ });+ await expect(heading(page, 'Free Claude & GPT for 30 days.')).toBeVisible();+ await expect(+ page.getByRole('button', { name: 'Start 30 day trial' })+ ).toBeVisible();+ expect(await fakeEvents(page)).toContainEqual({+ event: 'onboarding_v4_started',+ data: { signup_method: 'google', entry_step: 'plan' },+ });++ await page.getByRole('button', { name: 'Back to previous step' }).click();+ await expect(heading(page, 'Built for teams.')).toBeVisible();+ await page.evaluate(() => sessionStorage.clear());+ await page.goto('/?view=flow');+ await expect(heading(page, 'Built for teams.')).toBeVisible();+});++test('a work-email link shows the inbox that is already connected', async ({+ page,+}) => {+ await openFixture(page, '/?view=flow&step=work', {+ emailAccounts: [+ {+ address: '[email protected]',+ isPrimary: true,+ ownerId: 'macro|[email protected]',+ },+ ],+ });+ await expect(heading(page, /Connect your work/)).toBeVisible();+ await expect(page.getByText('Work email connected')).toBeVisible();+ await expect(page.getByText('[email protected]')).toBeVisible();+});++test('an unknown step link starts at welcome', async ({ page }) => {+ await openFixture(page, '/?view=flow&step=not-a-step');+ await expect(heading(page, 'Create your workspace')).toBeVisible();+});+test('Free, Pro, and Max appear below the unchanged trial offer', async ({page,}) => {await openFixture(page, '/?view=flow&next=/md/notes');await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }));@@ -144,7 +194,7 @@ test('Max checkout returns with a licensed account and no trial', async ({}) => {await openFixture(page, '/?view=flow');await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }));@@ -167,7 +217,7 @@ test('cancelling checkout returns to a retryable trial offer', async ({}) => {await openFixture(page, '/?view=flow', { checkoutOutcome: 'cancel' });await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }));@@ -189,7 +239,7 @@ test('an ineligible trial explains itself instead of charging', async ({'The 30-day trial is only available for your first Premium subscription';await openFixture(page, '/?view=flow', { failures: { checkout: message } });await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }));@@ -219,7 +269,7 @@ test('an invite’s free months replace the trial and keep its promotion', async},});await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }));@@ -236,7 +286,7 @@ test('an invite’s free months replace the trial and keep its promotion', asynctest('an existing team member just confirms and moves on', async ({ page }) => {await openFixture(page, '/?view=flow', { teams: [{ name: 'Acme' }] });await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'team' }));@@ -357,7 +407,7 @@ for (const width of [1440, 390]) {'plan',]) {await page.evaluate((step) => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step }));@@ -380,7 +430,7 @@ for (const width of [1440, 390]) {}// The explicit palette also survives a simulated Google redirect that drops query params.await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'work' }))@@ -468,7 +518,7 @@ test('tools keep Drive and Sheets, hide excluded Google apps and preserve native],});await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'tools' }))@@ -602,7 +652,7 @@ for (const githubLinkStatus of [],});await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'tools' }))@@ -635,7 +685,7 @@ test('connection status failure leaves native GitHub available', async ({}) => {await openFixture(page, '/?view=flow', { connectionFailures: ['pipedream'] });await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'tools' }))@@ -666,7 +716,7 @@ test('enables an existing native tool without reconnecting', async ({],});await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'tools' }))@@ -689,7 +739,7 @@ for (const width of [1280, 390]) {await page.setViewportSize({ width, height: 900 });await openFixture(page, '/?view=flow', { trialEligible: false });await page.evaluate(() => {- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }));@@ -723,7 +773,7 @@ test.describe('subscription recovery', () => {failures: width === 390 ? { trialEligibility: 'offline' } : {},});await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'plan' }))diff --git a/apps/web/src/features/onboarding/browser-test/tools-layout.browser.e2e.ts b/apps/web/src/features/onboarding/browser-test/tools-layout.browser.e2e.tsindex c542d6e01b..e67b79a293 100644--- a/apps/web/src/features/onboarding/browser-test/tools-layout.browser.e2e.ts+++ b/apps/web/src/features/onboarding/browser-test/tools-layout.browser.e2e.ts@@ -21,7 +21,7 @@ for (const viewport of [})),});await page.evaluate(() =>- sessionStorage.setItem(+ localStorage.setItem('onboarding-flow-step',JSON.stringify({ user: 'macro|[email protected]', step: 'tools' }))diff --git a/apps/web/src/features/onboarding/core/next-target.test.ts b/apps/web/src/features/onboarding/core/next-target.test.tsindex 212c011116..2e1eb20742 100644--- a/apps/web/src/features/onboarding/core/next-target.test.ts+++ b/apps/web/src/features/onboarding/core/next-target.test.ts@@ -1,5 +1,10 @@import { describe, expect, it } from 'vitest';-import { afterOnboardingTarget, sanitizeNext } from './next-target';+import {+ afterOnboardingTarget,+ onboardingPathWithStep,+ onboardingRedirectPath,+ sanitizeNext,+} from './next-target';describe('sanitizeNext', () => {it.each([@@ -28,3 +33,29 @@ describe('afterOnboardingTarget', () => {expect(afterOnboardingTarget(undefined, '//evil.com')).toBe('/home');});});++describe('onboarding entry links', () => {+ it('keeps a validated step on the onboarding path', () => {+ expect(onboardingPathWithStep('plan')).toBe('/onboarding?step=plan');+ expect(onboardingPathWithStep(['work'])).toBe('/onboarding?step=work');+ expect(onboardingPathWithStep('email')).toBe('/onboarding');+ expect(onboardingPathWithStep(undefined)).toBe('/onboarding');+ });++ it('carries step beside next, and drops it from a generic entry', () => {+ expect(onboardingRedirectPath('/channel/launch?step=team')).toBe(+ '/onboarding?next=%2Fchannel%2Flaunch&step=team'+ );+ expect(onboardingRedirectPath('/channel/launch?ref=1&step=nope')).toBe(+ '/onboarding?next=%2Fchannel%2Flaunch%3Fref%3D1'+ );+ expect(onboardingRedirectPath('/?step=plan')).toBe('/onboarding?step=plan');+ expect(onboardingRedirectPath('/home?step=work')).toBe(+ '/onboarding?step=work'+ );+ expect(onboardingRedirectPath('/home')).toBe('/onboarding');+ expect(onboardingRedirectPath('/channel/abc')).toBe(+ '/onboarding?next=%2Fchannel%2Fabc'+ );+ });+});diff --git a/apps/web/src/features/onboarding/core/next-target.ts b/apps/web/src/features/onboarding/core/next-target.tsindex e835c5c429..a92ed07923 100644--- a/apps/web/src/features/onboarding/core/next-target.ts+++ b/apps/web/src/features/onboarding/core/next-target.ts@@ -1,4 +1,5 @@import { DEFAULT_ROUTE } from '@app/constants/defaultRoute';+import { parseOnboardingStepParam } from './steps';/*** Same-app relative paths only. A `next` at the default route is not a real@@ -14,6 +15,34 @@ export function sanitizeNext(value: unknown): string | undefined {: undefined;}+/** `/onboarding`, keeping a validated `step` from an entry link. */+export function onboardingPathWithStep(step: unknown): string {+ const parsed = parseOnboardingStepParam(step);+ return parsed ? `/onboarding?step=${parsed}` : '/onboarding';+}++/**+ * First-run redirect into onboarding. A validated `step` stays on the link.+ * Any other arrival that is not Home becomes `next`.+ */+export function onboardingRedirectPath(target: string): string {+ const queryIndex = target.indexOf('?');+ const path = queryIndex === -1 ? target : target.slice(0, queryIndex);+ const params = new URLSearchParams(+ queryIndex === -1 ? '' : target.slice(queryIndex + 1)+ );+ const step = parseOnboardingStepParam(params.get('step'));+ params.delete('step');+ const rest = params.toString();+ const withoutStep = rest ? `${path}?${rest}` : path;+ const generic = withoutStep === '/' || withoutStep.startsWith(DEFAULT_ROUTE);+ const query = new URLSearchParams();+ if (!generic) query.set('next', withoutStep);+ if (step) query.set('step', step);+ const search = query.toString();+ return search ? `/onboarding?${search}` : '/onboarding';+}+/** Where leaving onboarding lands: the first valid deep link, else Home. */export function afterOnboardingTarget(...candidates: readonly unknown[]diff --git a/apps/web/src/features/onboarding/core/steps.test.ts b/apps/web/src/features/onboarding/core/steps.test.tsindex d3c4890905..8cde248876 100644--- a/apps/web/src/features/onboarding/core/steps.test.ts+++ b/apps/web/src/features/onboarding/core/steps.test.ts@@ -22,4 +22,25 @@ describe('onboarding resume', () => {expect(restoreOnboardingStep(undefined, true)).toBe('plan');expect(restoreOnboardingStep('work', true)).toBe('plan');});++ it('opens a valid step link when nothing is saved', () => {+ expect(restoreOnboardingStep(undefined, false, 'plan')).toBe('plan');+ expect(restoreOnboardingStep(undefined, false, 'work')).toBe('work');+ });++ it('ignores an unknown step link', () => {+ expect(restoreOnboardingStep(undefined, false, 'nope')).toBe('welcome');+ expect(restoreOnboardingStep(undefined, false, 'email')).toBe('welcome');+ expect(restoreOnboardingStep(undefined, false, 'building')).toBe('welcome');+ });++ it('prefers saved progress over the step link', () => {+ expect(restoreOnboardingStep('team', false, 'plan')).toBe('team');+ expect(restoreOnboardingStep('email', false, 'plan')).toBe('work');+ });++ it('lets a checkout return beat saved progress and the step link', () => {+ expect(restoreOnboardingStep('work', true, 'team')).toBe('plan');+ expect(restoreOnboardingStep(undefined, true, 'welcome')).toBe('plan');+ });});diff --git a/apps/web/src/features/onboarding/core/steps.ts b/apps/web/src/features/onboarding/core/steps.tsindex 7be05b6e5f..420eccf335 100644--- a/apps/web/src/features/onboarding/core/steps.ts+++ b/apps/web/src/features/onboarding/core/steps.ts@@ -42,15 +42,36 @@ export function previousOnboardingStep(return index > 0 ? ONBOARDING_STEPS[index - 1] : undefined;}-/** Migrate in-progress sessions from the previous flow without losing OAuth returns. */+/** A `?step` value that names a current onboarding step. */+export function parseOnboardingStepParam(+ value: unknown+): OnboardingStep | undefined {+ const raw = Array.isArray(value) ? value[0] : value;+ if (typeof raw !== 'string') return undefined;+ return ONBOARDING_STEPS.find((step) => step === raw);+}++/**+ * Where to open the flow.+ * Checkout return, then saved progress (including legacy names), then a+ * `?step` link, then welcome. A Google sign-up return is passed in as `work`.+ */export function restoreOnboardingStep(saved: unknown,- checkoutReturn = false+ checkoutReturn = false,+ requestedStep?: unknown): OnboardingStep {if (checkoutReturn) return 'plan';- if (typeof saved !== 'string') return 'welcome';+ const resumed = resumeSavedStep(saved);+ if (resumed) return resumed;+ return parseOnboardingStepParam(requestedStep) ?? 'welcome';+}++/** Migrate in-progress sessions from the previous flow without losing OAuth returns. */+function resumeSavedStep(saved: unknown): OnboardingStep | undefined {+ if (typeof saved !== 'string') return undefined;if (saved === 'email') return 'work';if (saved.startsWith('connect-')) return 'tools';if (saved === 'building' || saved === 'summary') return 'plan';- return ONBOARDING_STEPS.find((step) => step === saved) ?? 'welcome';+ return ONBOARDING_STEPS.find((step) => step === saved);}diff --git a/apps/web/src/features/onboarding/onboarding.tsx b/apps/web/src/features/onboarding/onboarding.tsxindex d02f63c23e..ba02687754 100644--- a/apps/web/src/features/onboarding/onboarding.tsx+++ b/apps/web/src/features/onboarding/onboarding.tsx@@ -1,8 +1,10 @@import { InviteOfferPanel } from '@app/features/gtm-invite/InviteOfferPanel';import { useNavigate, useSearchParams } from '@solidjs/router';import type { JSX } from 'solid-js';+import { onMount } from 'solid-js';import { OnboardingProvider } from './context/onboarding-context';import { parseCheckoutReturn } from './core/checkout';+import { parseOnboardingStepParam } from './core/steps';import { createAppOnboardingContext } from './create-app-onboarding-context';import { OnboardingFlowView } from './views/onboarding-flow-view';import { SignupJourneyView } from './views/signup-journey-view';@@ -11,11 +13,19 @@ import { SignupJourneyView } from './views/signup-journey-view';export function Onboarding() {const context = createAppOnboardingContext();const navigate = useNavigate();- const [params] = useSearchParams();+ const [params, setParams] = useSearchParams();+ // Captured once. The link is removed below, and later progress must win+ // on reload instead of the original step.+ const requestedStep = parseOnboardingStepParam(params.step);+ onMount(() => {+ if (params.step === undefined) return;+ setParams({ step: undefined }, { replace: true });+ });return (<OnboardingProvider value={context}><OnboardingFlowViewnext={typeof params.next === 'string' ? params.next : undefined}+ step={requestedStep}checkoutReturn={parseCheckoutReturn(params)}onNavigate={(target) => navigate(target, { replace: true })}onRedirect={(url) => {diff --git a/apps/web/src/features/onboarding/primitives/flow-finish.test.ts b/apps/web/src/features/onboarding/primitives/flow-finish.test.tsindex e162a2eb93..eb6385bbdb 100644--- a/apps/web/src/features/onboarding/primitives/flow-finish.test.ts+++ b/apps/web/src/features/onboarding/primitives/flow-finish.test.ts@@ -16,7 +16,10 @@ const VIEWER = 'macro|[email protected]';let dispose: (() => void) | undefined;afterEach(() => dispose?.());-beforeEach(() => sessionStorage.clear());+beforeEach(() => {+ sessionStorage.clear();+ localStorage.clear();+});function setup(world: Partial<FakeOnboardingWorld> = {}, next?: string) {const fake = createFakeOnboarding(world);diff --git a/apps/web/src/features/onboarding/primitives/flow-storage.test.ts b/apps/web/src/features/onboarding/primitives/flow-storage.test.tsnew file mode 100644index 0000000000..ad0cde306e--- /dev/null+++ b/apps/web/src/features/onboarding/primitives/flow-storage.test.ts@@ -0,0 +1,51 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { clearFlowProgress, readSavedStep, saveStep } from './flow-storage';++const VIEWER = 'macro|[email protected]';+const realLocalStorage = window.localStorage;++function blockLocalStorage() {+ Object.defineProperty(window, 'localStorage', {+ configurable: true,+ get() {+ throw new DOMException('Blocked', 'SecurityError');+ },+ });+}++beforeEach(() => {+ sessionStorage.clear();+ localStorage.clear();+});+afterEach(() => {+ Object.defineProperty(window, 'localStorage', {+ configurable: true,+ value: realLocalStorage,+ });+ vi.restoreAllMocks();+});++describe('onboarding step storage', () => {+ it('keeps progress in the tab when localStorage access is blocked', () => {+ blockLocalStorage();+ saveStep(VIEWER, 'team');+ expect(readSavedStep(VIEWER)).toBe('team');+ clearFlowProgress();+ expect(readSavedStep(VIEWER)).toBeUndefined();+ });++ it('keeps the tab copy when a localStorage write fails', () => {+ const setItem = Storage.prototype.setItem;+ vi.spyOn(Storage.prototype, 'setItem').mockImplementation(function (+ this: Storage,+ key: string,+ value: string+ ) {+ if (this === realLocalStorage) throw new DOMException('Full');+ setItem.call(this, key, value);+ });+ saveStep(VIEWER, 'plan');+ expect(sessionStorage.getItem('onboarding-flow-step')).toContain('plan');+ expect(readSavedStep(VIEWER)).toBe('plan');+ });+});diff --git a/apps/web/src/features/onboarding/primitives/flow-storage.ts b/apps/web/src/features/onboarding/primitives/flow-storage.tsindex 2759d5dafb..7ff61a8502 100644--- a/apps/web/src/features/onboarding/primitives/flow-storage.ts+++ b/apps/web/src/features/onboarding/primitives/flow-storage.ts@@ -6,8 +6,10 @@ import {import type { OnboardingStep } from '../core/steps';/**- * Session state that must survive full-page round-trips: Google sign-up,- * inbox OAuth, and Stripe checkout all reload the app mid-flow.+ * State that must survive full-page round-trips: Google sign-up, inbox OAuth,+ * and Stripe checkout all reload the app mid-flow. The step lives in+ * localStorage so a later visit on this browser can resume it; the rest is+ * only needed for the round-trip in this tab.*/const KEYS = {/** `{ user, step }`: the step to resume, scoped to who saved it. */@@ -22,26 +24,64 @@ const KEYS = {signupDraft: 'onboarding-signup-draft',} as const;-function read(key: string): string | null {+// Storage is resolved inside the try: reading `window.localStorage` itself+// throws when the browser blocks it.+type StorageArea = () => Storage;+const local: StorageArea = () => localStorage;+const session: StorageArea = () => sessionStorage;++function read(storage: StorageArea, key: string): string | null {try {- return sessionStorage.getItem(key);+ return storage().getItem(key);} catch {return null;}}-function write(key: string, value: string | undefined) {+/** Reports whether the write landed. */+function write(+ storage: StorageArea,+ key: string,+ value: string | undefined+): boolean {try {- if (value === undefined) sessionStorage.removeItem(key);- else sessionStorage.setItem(key, value);+ if (value === undefined) storage().removeItem(key);+ else storage().setItem(key, value);+ return true;} catch {// Storage blocked: the flow still works, it just can't resume.+ return false;}}-/** The saved step for `userId`; another user's progress is discarded. */-export function readSavedStep(userId: string): string | undefined {- const raw = read(KEYS.step);+function readSession(key: string) {+ return read(session, key);+}++function writeSession(key: string, value: string | undefined) {+ write(session, key, value);+}++/**+ * localStorage, falling back to the per-tab record, which older builds wrote+ * and which still holds progress while localStorage is unavailable.+ */+function readStepRaw(): string | null {+ const saved = read(local, KEYS.step);+ if (saved !== null) return saved;+ const legacy = read(session, KEYS.step);+ if (legacy !== null && write(local, KEYS.step, legacy))+ write(session, KEYS.step, undefined);+ return legacy;+}++function writeStep(value: string | undefined) {+ if (write(local, KEYS.step, value) || value === undefined)+ write(session, KEYS.step, undefined);+ else write(session, KEYS.step, value);+}++function savedStepFor(raw: string | null, userId: string): string | undefined {if (raw === null) return undefined;try {const saved: unknown = JSON.parse(raw);@@ -57,36 +97,44 @@ export function readSavedStep(userId: string): string | undefined {} catch {// Fall through: malformed progress is discarded like a stranger's.}- write(KEYS.step, undefined);- write(KEYS.next, undefined);+ writeStep(undefined);+ writeSession(KEYS.next, undefined);return undefined;}+/** The saved step for `userId`; another user's progress is discarded. */+export function readSavedStep(userId: string): string | undefined {+ return savedStepFor(readStepRaw(), userId);+}+export const saveStep = (userId: string, step: OnboardingStep) =>- write(KEYS.step, JSON.stringify({ user: userId, step }));+ writeStep(JSON.stringify({ user: userId, step }));-export const readSavedNext = () => read(KEYS.next) ?? undefined;-export const saveNext = (next: string) => write(KEYS.next, next);+export const readSavedNext = () => readSession(KEYS.next) ?? undefined;+export const saveNext = (next: string) => writeSession(KEYS.next, next);/** Forget resumable progress once the user leaves onboarding for good. */export function clearFlowProgress() {- write(KEYS.step, undefined);- write(KEYS.next, undefined);- write(KEYS.pendingConnectors, undefined);+ writeStep(undefined);+ writeSession(KEYS.next, undefined);+ writeSession(KEYS.pendingConnectors, undefined);}export function readConnectBaseline(): number | undefined {- const raw = read(KEYS.connectBaseline);+ const raw = readSession(KEYS.connectBaseline);if (raw === null) return undefined;const value = Number(raw);return Number.isFinite(value) ? value : undefined;}export const saveConnectBaseline = (count: number | undefined) =>- write(KEYS.connectBaseline, count === undefined ? undefined : String(count));+ writeSession(+ KEYS.connectBaseline,+ count === undefined ? undefined : String(count)+ );export function readPendingConnectors(): ReadonlySet<string> {- const raw = read(KEYS.pendingConnectors);+ const raw = readSession(KEYS.pendingConnectors);if (raw === null) return new Set();try {const slugs: unknown = JSON.parse(raw);@@ -101,14 +149,15 @@ export function readPendingConnectors(): ReadonlySet<string> {}export const savePendingConnectors = (slugs: ReadonlySet<string>) =>- write(+ writeSession(KEYS.pendingConnectors,slugs.size === 0 ? undefined : JSON.stringify([...slugs]));-export const readSignupDraft = () => parseSignupDraft(read(KEYS.signupDraft));+export const readSignupDraft = () =>+ parseSignupDraft(readSession(KEYS.signupDraft));export const saveSignupDraft = (draft: SignupDraft) =>- write(KEYS.signupDraft, serializeSignupDraft(draft));+ writeSession(KEYS.signupDraft, serializeSignupDraft(draft));-export const clearSignupDraft = () => write(KEYS.signupDraft, undefined);+export const clearSignupDraft = () => writeSession(KEYS.signupDraft, undefined);diff --git a/apps/web/src/features/onboarding/primitives/onboarding-flow.ts b/apps/web/src/features/onboarding/primitives/onboarding-flow.tsindex 0cdfae5a52..89380d8afd 100644--- a/apps/web/src/features/onboarding/primitives/onboarding-flow.ts+++ b/apps/web/src/features/onboarding/primitives/onboarding-flow.ts@@ -48,6 +48,8 @@ export function createOnboardingFlow(context: FlowCapabilities,options: {checkoutReturn: Accessor<CheckoutReturn | undefined>;+ /** Raw `?step` from the entry link. Unknown values are ignored. */+ requestedStep: Accessor<string | undefined>;record: Accessor<Loadable<OnboardingRecord>>;/** Whether the viewer signed up with Google (has an inbox) or an email code. */signupMethod: Accessor<'google' | 'email_code' | undefined>;@@ -67,14 +69,15 @@ export function createOnboardingFlow(};const needsOnboarding = () => viewer()?.tutorialComplete === false;- // Restore once per viewer: the signed-out draft's OAuth return wins, then- // saved progress; a checkout return always lands on the plan step.+ // Restore once per viewer. Checkout, then a Google sign-up return, then+ // saved progress, then a ?step link, then welcome.const restore = (userId: string | undefined) => {if (!userId || step()) return;const draft = readSignupDraft();const initial = restoreOnboardingStep(draft?.authenticating ? 'work' : readSavedStep(userId),- options.checkoutReturn() !== undefined+ options.checkoutReturn() !== undefined,+ options.requestedStep());saveStep(userId, initial);if (draft?.authenticating && draft.accent)diff --git a/apps/web/src/features/onboarding/views/onboarding-flow-view.test.tsx b/apps/web/src/features/onboarding/views/onboarding-flow-view.test.tsxindex d412380d0d..3b143e5732 100644--- a/apps/web/src/features/onboarding/views/onboarding-flow-view.test.tsx+++ b/apps/web/src/features/onboarding/views/onboarding-flow-view.test.tsx@@ -32,6 +32,8 @@ function setup(options: {world?: Partial<FakeOnboardingWorld>;resume?: OnboardingStep;+ /** Raw `?step` value, including unknown names. */+ step?: string;next?: string;checkoutReturn?: CheckoutReturn;} = {}@@ -44,6 +46,7 @@ function setup(() => (<OnboardingFlowViewnext={options.next}+ step={options.step}checkoutReturn={options.checkoutReturn}onNavigate={navigate}onRedirect={redirect}@@ -134,6 +137,96 @@ describe('onboarding flow', () => {await heading('Connect your tools.');});+ it('opens a step link on that step and records it as the entry', async () => {+ const { fake } = setup({+ step: 'plan',+ world: {+ emailAccounts: [+ {+ address: '[email protected]',+ isPrimary: true,+ ownerId: FAKE_VIEWER_ID,+ },+ ],+ },+ });+ await heading('Free Claude & GPT for 30 days.');+ expect(+ screen.getByRole('button', { name: 'Start 30 day trial' })+ ).toBeTruthy();+ expect(fake.events()).toContainEqual({+ event: 'onboarding_v4_started',+ data: { signup_method: 'google', entry_step: 'plan' },+ });+ });++ it('shows a connected work inbox when the link opens that step', async () => {+ setup({+ step: 'work',+ world: {+ emailAccounts: [+ {+ address: '[email protected]',+ isPrimary: true,+ ownerId: FAKE_VIEWER_ID,+ },+ ],+ },+ });+ await heading(/Connect your work/);+ expect(screen.getByText('Work email connected')).toBeTruthy();+ expect(screen.getByText('[email protected]')).toBeTruthy();+ });++ it('ignores an unknown step link and starts at welcome', async () => {+ setup({ step: 'not-a-step' });+ await heading('Create your workspace');+ expect(readSavedStep(FAKE_VIEWER_ID)).toBe('welcome');+ });++ it('prefers saved progress over the step link', async () => {+ setup({ resume: 'team', step: 'plan' });+ await heading('Built for teams.');+ });++ it('lets a checkout return beat saved progress and the step link', async () => {+ const { navigate } = setup({+ resume: 'work',+ step: 'team',+ checkoutReturn: { t: 'success', tier: 'premium' },+ world: { webhookPollsRemaining: 1 },+ });+ await heading('Your workspace is ready.');+ await waitFor(() => expect(navigate).toHaveBeenCalledWith('/home'), {+ timeout: 3_000,+ });+ });++ it('keeps a deep-linked step after the link is gone and the session is new', async () => {+ setup({ step: 'tools' });+ await heading('Connect your tools.');+ expect(readSavedStep(FAKE_VIEWER_ID)).toBe('tools');+ cleanup();+ sessionStorage.clear();+ setup();+ await heading('Connect your tools.');+ expect(localStorage.getItem('onboarding-flow-step')).toContain(+ '"step":"tools"'+ );+ expect(sessionStorage.getItem('onboarding-flow-step')).toBeNull();+ });++ it('resumes a step that was saved in sessionStorage before the move', async () => {+ sessionStorage.setItem(+ 'onboarding-flow-step',+ JSON.stringify({ user: FAKE_VIEWER_ID, step: 'personal' })+ );+ setup();+ await heading(/Add your personal/);+ expect(localStorage.getItem('onboarding-flow-step')).toContain('personal');+ expect(sessionStorage.getItem('onboarding-flow-step')).toBeNull();+ });+it('resumes the saved step, and Back returns to the previous one', async () => {setup({ resume: 'team' });await heading('Built for teams.');@@ -142,6 +235,12 @@ describe('onboarding flow', () => {expect(readSavedStep(FAKE_VIEWER_ID)).toBe('tools');});+ it('resumes Google sign-up at work ahead of saved progress and a step link', async () => {+ saveSignupDraft({ step: 'work', accent: '#f77d67', authenticating: true });+ setup({ resume: 'team', step: 'plan' });+ await heading(/Connect your work/);+ });+it('resumes at the work step after Google sign-up and applies the chosen accent', async () => {saveSignupDraft({ step: 'work', accent: '#f77d67', authenticating: true });const { fake } = setup();diff --git a/apps/web/src/features/onboarding/views/onboarding-flow-view.tsx b/apps/web/src/features/onboarding/views/onboarding-flow-view.tsxindex 3dce6e75c6..e0b94a9e1a 100644--- a/apps/web/src/features/onboarding/views/onboarding-flow-view.tsx+++ b/apps/web/src/features/onboarding/views/onboarding-flow-view.tsx@@ -30,6 +30,8 @@ import { ToolsStep } from './tools-step';export function OnboardingFlowView(props: {/** A deep link to land on after onboarding. */next: string | undefined;+ /** Raw `?step` from the entry link. Unknown values are ignored. */+ step?: string;checkoutReturn: CheckoutReturn | undefined;onNavigate: (target: string) => void;/** Leaves the app for hosted checkout. */@@ -58,6 +60,7 @@ export function OnboardingFlowView(props: {});const flow = createOnboardingFlow(context, {checkoutReturn: () => props.checkoutReturn,+ requestedStep: () => props.step,record,signupMethod: () => {const accounts = emailAccounts.accounts();diff --git a/apps/web/src/lib/analytics/app-events.ts b/apps/web/src/lib/analytics/app-events.tsindex 201d4999df..38ede7bb2f 100644--- a/apps/web/src/lib/analytics/app-events.ts+++ b/apps/web/src/lib/analytics/app-events.ts@@ -62,12 +62,6 @@ export type AppEvents = {tutorial_skipped: Record<string, unknown>;// --- Onboarding v4 (the full-screen /onboarding stepper) ------------------ /**- * Flow entered. `signup_method` is inferred from the inbox state at- * entry: a Google SSO signup arrives with its Gmail inbox already- * linked, an email-code signup with none. `entry_step` is where the- * user landed ('email' unless a persisted step was restored).- *//** A GTM invite welcome page resolved its link (`/invite?token=`). */gtm_invite_opened: { status: string };/** The recipient pressed Continue on the welcome page. */@@ -78,6 +72,12 @@ export type AppEvents = {gtm_invite_offer_viewed: { link_id: string; promo_code: string };/** Staff created an invite link in the internal portal. */gtm_invite_link_created: { link_id: string };+ /**+ * Flow entered. `signup_method` is inferred from the inbox state at+ * entry: a Google signup arrives with its inbox already linked, an+ * email-code signup with none. `entry_step` is the step shown first:+ * a checkout return, saved progress, a `?step` link, or welcome.+ */onboarding_v4_started: {signup_method: 'google' | 'email_code';entry_step: string;diff --git a/docs/agent-guide/README.md b/docs/agent-guide/README.mdindex 074ce501d7..ca06c1e37c 100644--- a/docs/agent-guide/README.md+++ b/docs/agent-guide/README.md@@ -27,7 +27,7 @@ verified live against a local stack (`just run_local`).| [activity.md](activity.md) | Activity || [notifications.md](notifications.md) | Notifications || [settings.md](settings.md) | Settings sections, including Slack import and team membership |-| [onboarding.md](onboarding.md) | Onboarding bypass and setup plan |+| [onboarding.md](onboarding.md) | Onboarding resume links, bypass, and setup plan || [setup-cards.md](setup-cards.md) | Sidebar import and setup cards, the connector import dialog, and permanent dismissal || [canvas.md](canvas.md) | Canvas colors and link paste || [soup-live-updates.md](soup-live-updates.md) | Live updates in flat Soup lists |diff --git a/docs/agent-guide/login.md b/docs/agent-guide/login.mdindex 7f31c42780..63ee82b8c2 100644--- a/docs/agent-guide/login.md+++ b/docs/agent-guide/login.md@@ -265,7 +265,11 @@ click. A pending webhook shows a retryable confirmation state. If the catalogcannot load, Free remains available, Pro still returns to its offer, andMax checkout stays disabled until prices can be loaded with the retry action.Both completion paths preserve an original `next` destination and otherwise land on Home (`/app/home`). Old saved email,-connector, building, and summary step names are migrated on resume.+connector, building, and summary step names are migrated on resume. A lifecycle+email can open a specific step with `/app/onboarding?step=<step>` (see+[onboarding](onboarding.md#resume-link)). The step is kept in+localStorage for that user. A checkout return or an in-progress Google sign-up+still wins, then saved progress, then the link.## Public onboarding previewdiff --git a/docs/agent-guide/onboarding.md b/docs/agent-guide/onboarding.mdindex 906aecd3d3..8c1973b9c7 100644--- a/docs/agent-guide/onboarding.md+++ b/docs/agent-guide/onboarding.md@@ -1,5 +1,18 @@# Onboarding+## Resume link++Lifecycle emails return someone to the step they left with+`https://macro.com/app/onboarding?step={lastOnboardingStep}`. `step` is one+of `welcome`, `vision`, `security`, `work`, `personal`, `tools`, `team`, or+`plan`. Any other value is ignored. A Stripe checkout return still opens the+plan step, and a Google sign-up return still opens work email. Saved progress+for this user wins over the link; a first visit with nothing saved opens the+link, otherwise the flow starts at welcome. The step is stored in+localStorage for that user and removed from the URL after it is applied, so a+reload keeps later progress. The app shell and the inbox connection callback+keep `step` when they send a first-run user into onboarding.+## Onboarding bypass — `/app/onboarding`All `@macro.com` accounts see a **Bypass** button on every onboarding step. It