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(home): add dismissible Getting Started link (#6811)
Peter Chinman4a7fc4a02beb
diff --git a/apps/web/src/features/home/home-getting-started-link.tsx b/apps/web/src/features/home/home-getting-started-link.tsxnew file mode 100644index 0000000000..eab5fe50db--- /dev/null+++ b/apps/web/src/features/home/home-getting-started-link.tsx@@ -0,0 +1,44 @@+import XIcon from '@phosphor/x.svg';+import { A } from '@solidjs/router';+import { Tooltip } from '@ui';+import { Show } from 'solid-js';+import { useGettingStartedEnabled } from '../getting-started/account-gate';+import type { HomePreferences } from './home-prefs';++export function HomeGettingStartedLink(props: {+ preferences: HomePreferences;+}) {+ const enabled = useGettingStartedEnabled();++ return (+ <Show+ when={+ (import.meta.env.DEV || enabled()) &&+ !props.preferences.isDismissed('getting-started-link')+ }+ >+ <div class="mt-2 flex items-center justify-between gap-3 pl-[53.75px] pr-[7.5px] text-xs text-ink-extra-muted">+ <span>+ New to Macro? See the{' '}+ <A+ href="/component/getting-started"+ class="rounded-sm text-ink-muted underline-offset-4 transition-colors hover:text-ink hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent"+ >+ Getting Started+ </A>+ {' page.'}+ </span>+ <Tooltip label="Dismiss" class="shrink-0">+ <button+ type="button"+ class="flex size-[33.75px] shrink-0 items-center justify-center rounded-full transition-colors hover:bg-hover hover:text-ink focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent"+ aria-label="Dismiss Getting Started link"+ onClick={() => props.preferences.dismiss('getting-started-link')}+ >+ <XIcon class="size-3.5" aria-hidden="true" />+ </button>+ </Tooltip>+ </div>+ </Show>+ );+}diff --git a/apps/web/src/features/home/home-prefs-context.test.tsx b/apps/web/src/features/home/home-prefs-context.test.tsxnew file mode 100644index 0000000000..3c75f169a7--- /dev/null+++ b/apps/web/src/features/home/home-prefs-context.test.tsx@@ -0,0 +1,92 @@+import { cleanup, render, screen } from '@solidjs/testing-library';+import { batch, createSignal } from 'solid-js';+import { afterEach, describe, expect, it } from 'vitest';+import {+ type HomePreferences,+ HomePreferencesProvider,+ useHomePreferences,+} from './home-prefs';++function mountPreferences(initialUserId = 'user-1') {+ const [userId, setUserId] = createSignal<string | undefined>(initialUserId);+ const consumers: HomePreferences[] = [];+ function Consumer() {+ const preferences = useHomePreferences();+ consumers.push(preferences);+ return (+ <span>+ {preferences.isDismissed('getting-started-link') ? 'hidden' : 'visible'}+ </span>+ );+ }+ const view = render(() => (+ <HomePreferencesProvider userId={userId}>+ <Consumer />+ <Consumer />+ </HomePreferencesProvider>+ ));+ return { ...view, consumers, setUserId };+}++afterEach(() => {+ cleanup();+ localStorage.clear();+});++describe('shared Home preferences', () => {+ it('updates all mounted consumers immediately and preserves other dismissals', () => {+ const { consumers } = mountPreferences();+ const [home, homeChatStart] = consumers;+ expect(home).toBe(homeChatStart);+ expect(screen.getAllByText('visible')).toHaveLength(2);++ home.dismiss('setup');+ homeChatStart.dismiss('getting-started-link');+ expect(screen.getAllByText('hidden')).toHaveLength(2);+ expect(homeChatStart.isDismissed('setup')).toBe(true);+ expect(+ JSON.parse(localStorage.getItem('macro:home:dismissed:user-1') ?? '[]')+ ).toEqual(['setup', 'getting-started-link']);++ home.restore('getting-started-link');+ expect(screen.getAllByText('visible')).toHaveLength(2);+ expect(homeChatStart.isDismissed('setup')).toBe(true);+ });++ it('keeps dismissals isolated when users change, including same-turn writes', () => {+ localStorage.setItem('macro:home:dismissed:user-2', '["setup"]');+ const { consumers, setUserId } = mountPreferences();+ const [preferences] = consumers;+ preferences.dismiss('getting-started-link');++ batch(() => {+ setUserId('user-2');+ preferences.dismiss('examples');+ });+ expect(screen.getAllByText('visible')).toHaveLength(2);+ expect(preferences.isDismissed('setup')).toBe(true);+ expect(+ JSON.parse(localStorage.getItem('macro:home:dismissed:user-2') ?? '[]')+ ).toEqual(['setup', 'examples']);++ setUserId(undefined);+ expect(preferences.isDismissed('setup')).toBe(false);+ preferences.dismiss('examples');+ setUserId('user-1');+ expect(screen.getAllByText('hidden')).toHaveLength(2);+ expect(preferences.isDismissed('setup')).toBe(false);+ expect(preferences.isDismissed('examples')).toBe(false);+ expect(localStorage.getItem('macro:home:dismissed:user-1')).toBe(+ '["getting-started-link"]'+ );+ });++ it('restores persisted dismissals when the provider remounts', () => {+ const first = mountPreferences();+ first.consumers[0].dismiss('getting-started-link');+ first.unmount();++ mountPreferences();+ expect(screen.getAllByText('hidden')).toHaveLength(2);+ });+});diff --git a/apps/web/src/features/home/home-prefs.test.ts b/apps/web/src/features/home/home-prefs.test.tsindex 586933c8db..139a07be76 100644--- a/apps/web/src/features/home/home-prefs.test.ts+++ b/apps/web/src/features/home/home-prefs.test.ts@@ -3,10 +3,9 @@ import { parseDismissedCards } from './home-prefs';describe('parseDismissedCards', () => {it('accepts known home cards', () => {- expect(parseDismissedCards('["examples","setup"]')).toEqual([- 'examples',- 'setup',- ]);+ expect(+ parseDismissedCards('["examples","setup","getting-started-link"]')+ ).toEqual(['examples', 'setup', 'getting-started-link']);});it('drops unknown and non-string entries', () => {diff --git a/apps/web/src/features/home/home-prefs.ts b/apps/web/src/features/home/home-prefs.tsindex 3f38df2597..ec8e29b05b 100644--- a/apps/web/src/features/home/home-prefs.ts+++ b/apps/web/src/features/home/home-prefs.ts@@ -1,12 +1,17 @@-import { useUserId } from '@core/context/user';+import { createAssertedContextProvider } from '@core/context/createContext';import { createUserScopedStorage } from '@core/util/userScopedStorage';-import { createEffect, createSignal, on } from 'solid-js';+import type { ContextProviderProps } from '@solid-primitives/context';+import { type Accessor, createMemo, createSignal } from 'solid-js';/** Dismissible home surfaces. Dismissals persist in localStorage. */-export type HomeCard = 'examples' | 'setup';+export type HomeCard = 'examples' | 'setup' | 'getting-started-link';const storage = createUserScopedStorage('macro:home:dismissed');-const HOME_CARDS: readonly HomeCard[] = ['examples', 'setup'];+const HOME_CARDS: readonly HomeCard[] = [+ 'examples',+ 'setup',+ 'getting-started-link',+];export function parseDismissedCards(raw: string | null): HomeCard[] {if (raw === null) return [];@@ -35,30 +40,35 @@ function persist(userId: string | undefined, cards: Set<HomeCard>): void {export type HomePreferences = ReturnType<typeof createHomePreferences>;/** User-scoped, reactive dismissal preferences for the home surface. */-export function createHomePreferences() {- const userId = useUserId();- const [dismissed, setDismissed] = createSignal<Set<HomeCard>>(new Set());+export function createHomePreferences(userId: Accessor<string | undefined>) {+ const state = createMemo(() => {+ const id = userId();+ const [dismissed, setDismissed] = createSignal(new Set(load(id)));- createEffect(- on(userId, (id) => {- setDismissed(new Set(load(id)));- })- );+ const update = (card: HomeCard, shouldDismiss: boolean) => {+ setDismissed((previous) => {+ if (previous.has(card) === shouldDismiss) return previous;+ const next = new Set(previous);+ if (shouldDismiss) next.add(card);+ else next.delete(card);+ persist(id, next);+ return next;+ });+ };- const update = (card: HomeCard, shouldDismiss: boolean) => {- setDismissed((previous) => {- if (previous.has(card) === shouldDismiss) return previous;- const next = new Set(previous);- if (shouldDismiss) next.add(card);- else next.delete(card);- persist(userId(), next);- return next;- });- };+ return { dismissed, update };+ });return {- isDismissed: (card: HomeCard) => dismissed().has(card),- dismiss: (card: HomeCard) => update(card, true),- restore: (card: HomeCard) => update(card, false),+ isDismissed: (card: HomeCard) => state().dismissed().has(card),+ dismiss: (card: HomeCard) => state().update(card, true),+ restore: (card: HomeCard) => state().update(card, false),};}++/** One preference instance shared by every Home surface in the app. */+export const [HomePreferencesProvider, useHomePreferences] =+ createAssertedContextProvider<+ HomePreferences,+ ContextProviderProps & { userId: Accessor<string | undefined> }+ >('HomePreferences', (props) => createHomePreferences(props.userId));diff --git a/apps/web/src/features/home/home.tsx b/apps/web/src/features/home/home.tsxindex 6e67c9795f..39e1b3d5f8 100644--- a/apps/web/src/features/home/home.tsx+++ b/apps/web/src/features/home/home.tsx@@ -11,8 +11,9 @@ import { Navigate } from '@solidjs/router';import { HomeBackfillProgress } from './home-backfill-progress';import { HomeChatInput } from './home-chat-input';import { HomeExamples } from './home-examples';+import { HomeGettingStartedLink } from './home-getting-started-link';import { GettingStartedSection, RecommendedSection } from './home-hub';-import { createHomePreferences } from './home-prefs';+import { useHomePreferences } from './home-prefs';import { HomeSectionBoundary } from './home-section-boundary';const MACRO_LOGO_PATH =@@ -68,7 +69,7 @@ export function Home() {function HomeContent() {const user = useUserContext();- const preferences = createHomePreferences();+ const preferences = useHomePreferences();const firstName = () => {const name = user.author();@@ -133,6 +134,7 @@ function HomeContent() {<FloatRegionOrInline region="accessory"><div class="mx-auto w-full max-w-3xl shrink-0 px-4 pb-3 pointer-events-auto touch:px-(--mobile-chrome-gutter) touch:pb-0"><HomeChatInput />+ <HomeGettingStartedLink preferences={preferences} /></div></FloatRegionOrInline></main>diff --git a/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx b/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsxindex fa92401b32..071f318b15 100644--- a/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx+++ b/apps/web/src/features/inbox-view/components/HomeChatStart.test.tsx@@ -1,6 +1,7 @@import { cleanup, render, screen } from '@solidjs/testing-library';import type { JSX } from 'solid-js';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { HomePreferencesProvider } from '../../home/home-prefs';import { HomeChatStart } from './HomeChatStart';type ChildrenProps = { children?: JSX.Element };@@ -44,6 +45,9 @@ vi.mock('@core/component/AI/context', () => ({vi.mock('../../home/home-chat-input', () => ({HomeChatInput: () => <div data-testid="home-chat-input" />,}));+vi.mock('../../home/home-getting-started-link', () => ({+ HomeGettingStartedLink: () => <div data-testid="getting-started-link" />,+}));vi.mock('../../home/components/home-recommended-actions', () => ({HomeRecommendedActions: () => <div data-testid="home-suggestions" />,}));@@ -55,9 +59,17 @@ beforeEach(() => {});afterEach(cleanup);+function renderHome() {+ return render(() => (+ <HomePreferencesProvider userId={() => 'user-1'}>+ <HomeChatStart />+ </HomePreferencesProvider>+ ));+}+describe('Home agent composer alignment', () => {it('matches the Agents new-conversation topbar and padding when the list is open', () => {- render(() => <HomeChatStart />);+ renderHome();const grid = document.querySelector('[data-home-composer-align="agents"]');expect(grid).toBeTruthy();expect(grid?.className).toContain('pt-6');@@ -70,7 +82,7 @@ describe('Home agent composer alignment', () => {it('uses the real Home topbar instead of a spacer when the list is collapsed', () => {mocks.asideCollapsed = true;- render(() => <HomeChatStart />);+ renderHome();expect(document.querySelector('[data-testid="home-topbar"]')).toBeTruthy();expect(document.querySelector('[data-home-composer-topbar-align]')@@ -82,7 +94,7 @@ describe('Home agent composer alignment', () => {it('keeps the legacy 32px-above-center composer when agents are disabled', () => {mocks.agentsEnabled = false;- render(() => <HomeChatStart />);+ renderHome();const grid = document.querySelector('[data-home-composer-align="legacy"]');expect(grid).toBeTruthy();expect(grid?.className).toContain('pb-16');diff --git a/apps/web/src/features/inbox-view/components/HomeChatStart.tsx b/apps/web/src/features/inbox-view/components/HomeChatStart.tsxindex 2f73b8ffa0..75f7685f0c 100644--- a/apps/web/src/features/inbox-view/components/HomeChatStart.tsx+++ b/apps/web/src/features/inbox-view/components/HomeChatStart.tsx@@ -10,11 +10,14 @@ import { enableChatV3Agents } from '@core/constant/featureFlags';import { Show } from 'solid-js';import { HomeRecommendedActions } from '../../home/components/home-recommended-actions';import { HomeChatInput } from '../../home/home-chat-input';+import { HomeGettingStartedLink } from '../../home/home-getting-started-link';+import { useHomePreferences } from '../../home/home-prefs';/** Desktop Home's idle pane uses the single-line chat composer and send flow. */export function HomeChatStart() {const shell = useViewShell();const agents = useFeatureFlag(enableChatV3Agents);+ const preferences = useHomePreferences();const showHomeTopBar = () =>shell.aside.isCollapsed() || shell.aside.isOverlay();return (@@ -65,6 +68,7 @@ export function HomeChatStart() {autoFocusOnMount={false}/><div class="min-h-0 min-w-0 pb-8">+ <HomeGettingStartedLink preferences={preferences} /><HomeRecommendedActions /></div></div>diff --git a/apps/web/src/routes/Root.tsx b/apps/web/src/routes/Root.tsxindex 4bdd7a0d28..8fd61c6ef0 100644--- a/apps/web/src/routes/Root.tsx+++ b/apps/web/src/routes/Root.tsx@@ -9,6 +9,7 @@ import { ChannelInviteAcceptance } from '@app/features/channel-invitations/Channimport { InviteLinksPortal } from '@app/features/gtm-invite/InviteLinksPortal';import { InviteWelcome } from '@app/features/gtm-invite/InviteWelcome';import { usePendingInviteRedemption } from '@app/features/gtm-invite/usePendingInviteRedemption';+import { HomePreferencesProvider } from '@app/features/home/home-prefs';import { GlobalShareInboxConflictDialog } from '@app/features/inbox/ShareInboxConflictDialog';import { usePendingNotificationNavigationEffect } from '@app/features/notifications/PendingNotificationNavigationEffect';import { InteractiveOnboardingModal } from '@app/features/onboarding/InteractiveOnboardingModal';@@ -384,6 +385,7 @@ const ROUTES: RouteDefinition[] = [];function ConfiguredGlobalAppStateProvider(props: ParentProps) {+ const userId = useUserId();// Initialize global notification helpersconst notifInterface = usePlatformNotificationState();useChatRenameWebsocketSync();@@ -417,7 +419,9 @@ function ConfiguredGlobalAppStateProvider(props: ParentProps) {notificationSource={notificationSource}blockOrchestrator={blockOrchestrator}>- {props.children}+ <HomePreferencesProvider userId={userId}>+ {props.children}+ </HomePreferencesProvider></GlobalAppStateProvider>);}diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.mdindex 5460cb94bd..c64ce976d9 100644--- a/docs/AGENT_GUIDE/surfaces.md+++ b/docs/AGENT_GUIDE/surfaces.md@@ -150,7 +150,13 @@ are restored, including before a chat-limit paywall opens. With agents disabled,the input stays 32px above the vertical center as suggestions load. With agentsenabled, the composer uses the same topbar offset and 24/64 padding as theAgents new-conversation page so the two inputs share a baseline; suggestions-still load below it without moving the input. Up to three cached AI+still load below it without moving the input. Eligible newer accounts (all+accounts in development) see “New to Macro? See the **Getting Started** page.” directly+below the composer, above suggestions. The link opens+`/app/component/getting-started`; **Dismiss Getting Started link** hides it and+remembers the dismissal per user in this browser across reloads. Dismissals update+all open Home panes immediately and stay isolated when switching accounts. This+dismissal is independent of the Getting Started sidebar link. Up to three cached AIsuggestions appear below thecomposer, using the existing fast/smart recommendation projections. Compact rowsuse one line: reason — Phosphor icon and item name, followed by Open, all at the same font size. Clicking a@@ -787,6 +793,9 @@ creation can be retried.Greeting, getting-started checklist, example prompt buttons (`Draft a document`,`Draft an email`, `Search & research`), and the ubiquitous `Ask AI` composer.+Eligible newer accounts (all accounts in development) also see the same+dismissible **Getting Started** link below+the composer, with its dismissal shared with the desktop Home starting pane.On phones, shared confirmations (including Remove Member and Cancel Invitation)use a glass sheet with a title, description, Close confirmation button, and