feat(desktop): retire tutorials after the first month

This commit is contained in:
brooklyn!
2026-09-11 23:32:19 -07:00
parent 526ce1b64c
commit 995e79afe4
3 changed files with 180 additions and 0 deletions
@@ -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<unknown>(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)
})
@@ -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
}
@@ -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<TutorialLifetime>(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)
}