From 995e79afe47e54ec0975caad27403adad0d4a8d5 Mon Sep 17 00:00:00 2001 From: brooklyn! Date: Fri, 11 Sep 2026 23:32:19 -0700 Subject: [PATCH] feat(desktop): retire tutorials after the first month --- .../tips/tutorial-lifetime.test.tsx | 130 ++++++++++++++++++ .../src/components/tips/use-tip-rotation.ts | 5 + apps/desktop/src/store/tutorial-lifetime.ts | 45 ++++++ 3 files changed, 180 insertions(+) create mode 100644 apps/desktop/src/components/tips/tutorial-lifetime.test.tsx create mode 100644 apps/desktop/src/store/tutorial-lifetime.ts diff --git a/apps/desktop/src/components/tips/tutorial-lifetime.test.tsx b/apps/desktop/src/components/tips/tutorial-lifetime.test.tsx new file mode 100644 index 0000000000..3a2180a1ab --- /dev/null +++ b/apps/desktop/src/components/tips/tutorial-lifetime.test.tsx @@ -0,0 +1,130 @@ +import { act, cleanup, renderHook } from '@testing-library/react' +import { afterEach, beforeEach, expect, it, vi } from 'vitest' + +const { request } = vi.hoisted(() => ({ request: vi.fn(async () => undefined) })) + +vi.mock('@/store/gateway', async () => { + const { atom } = await import('nanostores') + + return { $gateway: atom(null), activeGateway: () => ({ request }) } +}) +vi.mock('@/store/session', async () => { + const { atom } = await import('nanostores') + + return { $awaitingResponse: atom(false), $busy: atom(false) } +}) +vi.mock('react-router', () => ({ useNavigate: () => vi.fn() })) +vi.mock('./local-setup-offer', () => ({ offerLocalSetupTip: () => false })) + +import { en } from '@/i18n/en' + +const DAY_MS = 24 * 60 * 60_000 +const START = new Date('2026-01-01T12:00:00Z').getTime() + +beforeEach(() => { + vi.resetModules() + localStorage.clear() + request.mockClear() + vi.useFakeTimers() + vi.setSystemTime(START) +}) + +afterEach(() => { + cleanup() + vi.useRealTimers() +}) + +it('retires both tutorial features after 30 days across launches, then keeps a manual re-enable', async () => { + const { useTipRotation } = await import('./use-tip-rotation') + let tips = await import('@/store/tips') + let tours = await import('@/store/tours') + const firstLaunch = renderHook(() => useTipRotation(en.tips)) + + expect(tips.$tipsEnabled.get()).toBe(true) + expect(tours.$toursEnabled.get()).toBe(true) + expect(request).not.toHaveBeenCalled() + firstLaunch.unmount() + + // Reload updated modules against the same persistent storage, just as an + // app update does. The deadline must remain anchored to the first launch. + vi.setSystemTime(START + 30 * DAY_MS - 30_000) + vi.resetModules() + const returning = await import('./use-tip-rotation') + tips = await import('@/store/tips') + tours = await import('@/store/tours') + const secondLaunch = renderHook(() => returning.useTipRotation(en.tips)) + + expect(tips.$tipsEnabled.get()).toBe(true) + expect(tours.$toursEnabled.get()).toBe(true) + tips.resetTips() // Replaying the catalog must not restart the month either. + tips.showTip({ side: 'bottom', targets: ['body'], text: 'A pending tip' }) + + act(() => vi.advanceTimersByTime(30_000)) + + expect(tips.$tipsEnabled.get()).toBe(false) + expect(tours.$toursEnabled.get()).toBe(false) + expect(tips.$activeTip.get()).toBeNull() + expect(request).toHaveBeenCalledWith('config.set', { key: 'display.in_app_tips', value: 'false' }) + expect(request).toHaveBeenCalledWith('config.set', { key: 'display.in_app_tours', value: 'false' }) + + act(() => { + tips.setTipsEnabled(true) + tours.setToursEnabled(true) + tips.resetTips() + }) + secondLaunch.unmount() + + vi.setSystemTime(START + 60 * DAY_MS) + vi.resetModules() + const later = await import('./use-tip-rotation') + tips = await import('@/store/tips') + tours = await import('@/store/tours') + renderHook(() => later.useTipRotation(en.tips)) + act(() => vi.advanceTimersByTime(30_000)) + + expect(tips.$tipsEnabled.get()).toBe(true) + expect(tours.$toursEnabled.get()).toBe(true) +}) + +it('uses existing tip history on upgrade without treating invalid dates as experience', async () => { + localStorage.setItem( + 'hermes.desktop.tips.shownAt.v1', + JSON.stringify({ + old: START - 31 * DAY_MS, + recent: START - DAY_MS, + invalid: 'not a timestamp', + future: START + DAY_MS, + zero: 0, + negative: -1 + }) + ) + const { useTipRotation } = await import('./use-tip-rotation') + let tips = await import('@/store/tips') + let tours = await import('@/store/tours') + const upgraded = renderHook(() => useTipRotation(en.tips)) + + expect(tips.$tipsEnabled.get()).toBe(false) + expect(tours.$toursEnabled.get()).toBe(false) + upgraded.unmount() + + localStorage.clear() + localStorage.setItem( + 'hermes.desktop.tips.shownAt.v1', + JSON.stringify({ invalid: 'not a timestamp', future: START + DAY_MS, zero: 0, negative: -1 }) + ) + localStorage.setItem('hermes.desktop.tips.rotation.v1', 'false') + vi.resetModules() + const fresh = await import('./use-tip-rotation') + tips = await import('@/store/tips') + tours = await import('@/store/tours') + renderHook(() => fresh.useTipRotation(en.tips)) + + // No usable history: begin the month now, never turn an existing Off on. + expect(tips.$tipsEnabled.get()).toBe(false) + expect(tours.$toursEnabled.get()).toBe(true) + act(() => { + vi.setSystemTime(START + 30 * DAY_MS) + vi.advanceTimersByTime(30_000) + }) + expect(tours.$toursEnabled.get()).toBe(false) +}) diff --git a/apps/desktop/src/components/tips/use-tip-rotation.ts b/apps/desktop/src/components/tips/use-tip-rotation.ts index cb4791181d..ce2c69d6a7 100644 --- a/apps/desktop/src/components/tips/use-tip-rotation.ts +++ b/apps/desktop/src/components/tips/use-tip-rotation.ts @@ -30,6 +30,7 @@ import { TIP_CATALOG } from '@/lib/tips/catalog' import { nextTip } from '@/lib/tips/rotation' import { $awaitingResponse, $busy } from '@/store/session' import { $activeTip, $lastTipId, $nextTipAt, $retiredTips, $tipsEnabled, $tipShownAt, showTip } from '@/store/tips' +import { checkTutorialLifetime } from '@/store/tutorial-lifetime' import { offerLocalSetupTip } from './local-setup-offer' @@ -68,6 +69,8 @@ export function useTipRotation(copy: Translations['tips']) { const navigate = useNavigate() useEffect(() => { + checkTutorialLifetime() + let lastTypedAt = 0 let settledAt = Date.now() + SETTLE_MIN_MS + Math.random() * SETTLE_SPREAD_MS @@ -82,6 +85,8 @@ export function useTipRotation(copy: Translations['tips']) { } const offer = () => { + checkTutorialLifetime() + if (!$tipsEnabled.get() || $activeTip.get()) { return } diff --git a/apps/desktop/src/store/tutorial-lifetime.ts b/apps/desktop/src/store/tutorial-lifetime.ts new file mode 100644 index 0000000000..d0c3fc8b8f --- /dev/null +++ b/apps/desktop/src/store/tutorial-lifetime.ts @@ -0,0 +1,45 @@ +import { readJson, writeJson } from '@/lib/storage' +import { $tipShownAt, setTipsEnabled } from '@/store/tips' +import { setToursEnabled } from '@/store/tours' + +// Desktop-global, like the two Appearance switches: changing profiles is not +// learning the app again. Read through storage so another window's completed +// retirement cannot be replayed over a later manual re-enable. +const KEY = 'hermes.desktop.tutorials.lifetime.v1' +const INTRO_PERIOD_MS = 30 * 24 * 60 * 60_000 + +interface TutorialLifetime { + autoDisabled: boolean + startedAt: number +} + +/** Retire tutorials once, after a month since first desktop use, not a month + * of accumulated foreground time. Settings can turn either feature back on. */ +export function checkTutorialLifetime(): void { + const now = Date.now() + const stored = readJson(KEY) + + if (stored?.autoDisabled === true) { + return + } + + let startedAt = stored?.startedAt + + if (typeof startedAt !== 'number' || !Number.isFinite(startedAt) || startedAt <= 0) { + // Older installs already have a tip ledger. Use its earliest valid date + // instead of giving experienced users another month after this update. + startedAt = Object.values($tipShownAt.get()).reduce( + (earliest, shownAt) => (Number.isFinite(shownAt) && shownAt > 0 && shownAt < earliest ? shownAt : earliest), + now + ) + writeJson(KEY, { autoDisabled: false, startedAt }) + } + + if (now - startedAt < INTRO_PERIOD_MS) { + return + } + + writeJson(KEY, { autoDisabled: true, startedAt }) + setTipsEnabled(false) + setToursEnabled(false) +}