From 1acd5bb02bbae0b32416a3ac45d4f00373453e33 Mon Sep 17 00:00:00 2001 From: brooklyn! Date: Thu, 27 Aug 2026 22:17:00 -0500 Subject: [PATCH] feat(desktop): make tips and guided tours both opt-out (#96835) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tours had no switch at all, and the tips switch only covered the app's own rotation — so "I don't want these" was answerable for half of one feature and none of the other. Both are now a row in Settings → Appearance, on by default, and off means off for Hermes as well: an agent tip is dropped at the bridge and a tour request is refused in words, so the agent hears that the walkthrough didn't run instead of narrating a spotlight nobody can see. Renames $tipRotationEnabled to $tipsEnabled to match what it now governs. The storage key keeps the old name on purpose — renaming it would read as unset for anyone who had already turned tips off, and silently turning them back on is the one outcome worth avoiding. The switches stop at the app's edge for now: the tools are still in the model's schema and the calls simply don't land. Withdrawing them entirely needs the setting to reach the backend, which is the next PR. --- .../gateway-event/desktop-bridge.ts | 19 ++++++++----- .../src/app/settings/appearance-settings.tsx | 28 ++++++++++++++++--- .../src/components/tips/use-tip-rotation.ts | 8 +++--- apps/desktop/src/i18n/ar.ts | 5 +++- apps/desktop/src/i18n/en.ts | 4 ++- apps/desktop/src/i18n/ja.ts | 4 ++- apps/desktop/src/i18n/types.ts | 2 ++ apps/desktop/src/i18n/zh-hant.ts | 4 ++- apps/desktop/src/i18n/zh.ts | 4 ++- apps/desktop/src/store/tips.ts | 25 +++++++++-------- apps/desktop/src/store/tours.ts | 20 +++++++++++++ 11 files changed, 92 insertions(+), 31 deletions(-) create mode 100644 apps/desktop/src/store/tours.ts diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts index 23f14fbdd8..1372a1f36e 100644 --- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts +++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/desktop-bridge.ts @@ -8,7 +8,8 @@ import { $gateway } from '@/store/gateway' import { applyDesktopLayoutPreset, revealDesktopPane } from '@/store/pane-focus' import { recordAgentReaction } from '@/store/reactions-local' import { setMessages } from '@/store/session' -import { type ActiveTip, showTip } from '@/store/tips' +import { $tipsEnabled, type ActiveTip, showTip } from '@/store/tips' +import { $toursEnabled } from '@/store/tours' import type { GatewayEventContext } from './types' @@ -184,7 +185,12 @@ export function handleDesktopBridgeEvent(ctx: GatewayEventContext): boolean { text: result ? JSON.stringify(result) : '' }) - if (isActiveEvent) { + if (!$toursEnabled.get()) { + // Refused in words, not silently dropped: the agent asked for a + // walkthrough it isn't getting, and a no-op would leave it narrating + // a spotlight the user can't see. + void answer({ error: 'The user has turned guided tours off.', success: false }) + } else if (isActiveEvent) { void import('@/lib/tour') .then(({ runTour }) => runTour( @@ -217,10 +223,9 @@ export function handleDesktopBridgeEvent(ctx: GatewayEventContext): boolean { if (event.type === 'tip.show') { // tip tool: point the accent bubble at something and say one line about // it. Fire-and-forget — a tip is not a question, and blocking the turn on - // one would stall the sentence the agent is in the middle of. Not behind - // the Appearance switch: that governs the app's own idle rotation, and - // this is Hermes answering the user mid-conversation, like a tour. Active - // session only, though: a background turn must never paint on the user's + // one would stall the sentence the agent is in the middle of, so there is + // nothing to answer and a refusal is simply a bubble that never appears. + // Active session only: a background turn must never paint on the user's // screen (desktop AGENTS.md: offer, don't hijack). const selector = typeof payload?.selector === 'string' ? payload.selector : '' const text = typeof payload?.text === 'string' ? payload.text : '' @@ -229,7 +234,7 @@ export function handleDesktopBridgeEvent(ctx: GatewayEventContext): boolean { // already has those. Dropping it here also stops a malformed event from // replacing a rotation tip with a bubble that dismisses itself a frame // later. - if (isActiveEvent && selector && text) { + if ($tipsEnabled.get() && isActiveEvent && selector && text) { showTip({ side: (payload?.side as ActiveTip['side']) ?? 'top', targets: [selector], diff --git a/apps/desktop/src/app/settings/appearance-settings.tsx b/apps/desktop/src/app/settings/appearance-settings.tsx index d1b22380f4..c007ea937b 100644 --- a/apps/desktop/src/app/settings/appearance-settings.tsx +++ b/apps/desktop/src/app/settings/appearance-settings.tsx @@ -22,8 +22,9 @@ import { $reactionsEnabled, setReactionsEnabled } from '@/store/reactions-enable import { $reasoningCollapsedByDefault, setReasoningCollapsedByDefault } from '@/store/reasoning-disclosure' import { $sessionListDensity, type SessionListDensity, setSessionListDensity } from '@/store/session-list-density' import { $tabStripDefault, setTabStripDefault, type TabStripDefault } from '@/store/tabstrip-prefs' -import { $retiredTips, $tipRotationEnabled, resetTips, setTipRotationEnabled } from '@/store/tips' +import { $retiredTips, $tipsEnabled, resetTips, setTipsEnabled } from '@/store/tips' import { $toolViewMode, setToolViewMode } from '@/store/tool-view' +import { $toursEnabled, setToursEnabled } from '@/store/tours' import { $translucency, beginTranslucencyPeek, @@ -356,7 +357,8 @@ export function AppearanceSettings() { const translucency = useStore($translucency) const glassMode = translucency.mode === 'glass' && GLASS_SUPPORTED const reactionsEnabled = useStore($reactionsEnabled) - const tipRotation = useStore($tipRotationEnabled) + const tipsEnabled = useStore($tipsEnabled) + const toursEnabled = useStore($toursEnabled) const retiredTips = useStore($retiredTips) const vibeHeartsEnabled = useStore($vibeHeartsEnabled) const backdrop = useStore($backdrop) @@ -764,13 +766,13 @@ export function AppearanceSettings() { { triggerHaptic('selection') - setTipRotationEnabled(id === 'on') + setTipsEnabled(id === 'on') }} options={[ { id: 'off', label: t.common.off }, { id: 'on', label: t.common.on } ]} - value={tipRotation ? 'on' : 'off'} + value={tipsEnabled ? 'on' : 'off'} /> {/* The ✕ on a tip is permanent, so this is the only way back. It appears once there is something to bring back. */} @@ -792,6 +794,24 @@ export function AppearanceSettings() { title={a.tipsTitle} /> + { + triggerHaptic('selection') + setToursEnabled(id === 'on') + }} + options={[ + { id: 'off', label: t.common.off }, + { id: 'on', label: t.common.on } + ]} + value={toursEnabled ? 'on' : 'off'} + /> + } + description={a.toursDesc} + title={a.toursTitle} + /> + { - if (!$tipRotationEnabled.get() || $activeTip.get()) { + if (!$tipsEnabled.get() || $activeTip.get()) { return } @@ -109,10 +109,10 @@ export function useTipRotation(copy: Translations['tips']) { }) } - // Turning the rotation on is its own kind of settled: the delay guards a + // Turning tips on is its own kind of settled: the delay guards a // launch you came into with a purpose, and has nothing to say about someone // who just asked for tips and is owed the sight of one working. - const unbindSwitch = $tipRotationEnabled.listen(enabled => { + const unbindSwitch = $tipsEnabled.listen(enabled => { if (enabled) { settledAt = Date.now() offer() diff --git a/apps/desktop/src/i18n/ar.ts b/apps/desktop/src/i18n/ar.ts index 173c290dd5..6202019c70 100644 --- a/apps/desktop/src/i18n/ar.ts +++ b/apps/desktop/src/i18n/ar.ts @@ -470,8 +470,11 @@ export const ar = defineLocale({ reactionsTitle: 'تفاعلات الرسائل', reactionsDesc: 'تفاعلات إيموجي بأسلوب iMessage — تفاعل مع الرسائل، ويمكن لـ Hermes التفاعل مع رسائلك.', tipsTitle: 'نصائح داخل التطبيق', - tipsDesc: 'أثناء خمول التطبيق، يشير أحيانًا إلى أجزاء منه ربما لم تكتشفها بعد. إغلاق نصيحة يزيلها نهائيًا.', + tipsDesc: + 'فقاعة صغيرة تشير إلى جزء من التطبيق، تظهر أحيانًا أثناء الخمول ومن Hermes عند الحاجة. إغلاق نصيحة يزيلها نهائيًا.', tipsReset: count => `استعادة ${count} نصيحة مغلقة`, + toursTitle: 'جولات إرشادية', + toursDesc: 'دع Hermes يرشدك في التطبيق، مع تعتيم الشاشة وإبراز كل خطوة.', composerPopoutTitle: 'محرر عائم', composerPopoutDesc: 'السماح بسحب محرر الرسائل خارج موضعه. عطّل هذا الخيار لإبقائه مثبتًا في الأسفل.', vibeHeartsTitle: 'قلوب المزاج', diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts index 846db78f88..2a9aed67e5 100644 --- a/apps/desktop/src/i18n/en.ts +++ b/apps/desktop/src/i18n/en.ts @@ -590,8 +590,10 @@ export const en: Translations = { reactionsDesc: 'iMessage-style emoji tapbacks — react to messages, and Hermes can react to yours.', tipsTitle: 'In-App Tips', tipsDesc: - 'While the app is idle, occasionally point out a part of it you may not have found yet. Closing a tip retires it for good.', + 'A small bubble pointing at one part of the app, shown occasionally while idle and by Hermes when it helps. Closing one retires it for good.', tipsReset: (count: number) => `Bring back ${count} closed ${count === 1 ? 'tip' : 'tips'}`, + toursTitle: 'Guided Tours', + toursDesc: 'Let Hermes walk you through the app, dimming the screen and spotlighting each step.', composerPopoutTitle: 'Floating Composer', composerPopoutDesc: 'Allow dragging the composer out of its dock. Turn this off to keep it locked at the bottom.', vibeHeartsTitle: 'Vibe Hearts', diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts index 28c7a631a2..e2d47a6588 100644 --- a/apps/desktop/src/i18n/ja.ts +++ b/apps/desktop/src/i18n/ja.ts @@ -413,8 +413,10 @@ export const ja = defineLocale({ 'iMessage風の絵文字タップバック — メッセージにリアクションでき、Hermesもあなたのメッセージにリアクションします。', tipsTitle: 'アプリ内ヒント', tipsDesc: - 'アプリが待機中のとき、まだ見つけていない機能をときどき案内します。閉じたヒントは二度と表示されません。', + 'アプリの一部を指す小さな吹き出し。待機中にときどき、また役に立つときは Hermes からも表示します。閉じたヒントは二度と表示されません。', tipsReset: (count: number) => `閉じた${count}件のヒントを元に戻す`, + toursTitle: 'ガイドツアー', + toursDesc: '画面を暗くして各ステップを強調しながら、Hermes がアプリを案内します。', composerPopoutTitle: 'フローティング入力欄', composerPopoutDesc: '入力欄をドックからドラッグして外せるようにします。オフにすると画面下部に固定されます。', vibeHeartsTitle: 'バイブハート', diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts index bf21644512..3b4415cb7f 100644 --- a/apps/desktop/src/i18n/types.ts +++ b/apps/desktop/src/i18n/types.ts @@ -483,6 +483,8 @@ export interface Translations { tipsTitle: string tipsDesc: string tipsReset: (count: number) => string + toursTitle: string + toursDesc: string composerPopoutTitle: string composerPopoutDesc: string vibeHeartsTitle: string diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts index 2f2198c5bc..23fbcf7590 100644 --- a/apps/desktop/src/i18n/zh-hant.ts +++ b/apps/desktop/src/i18n/zh-hant.ts @@ -401,8 +401,10 @@ export const zhHant = defineLocale({ reactionsTitle: '訊息回應', reactionsDesc: 'iMessage 風格的表情回應 — 你可以對訊息做出回應,Hermes 也能回應你的訊息。', tipsTitle: '應用程式內提示', - tipsDesc: '應用程式閒置時,偶爾指出你可能還沒發現的功能。關掉一則就不再出現。', + tipsDesc: '指向應用程式某處的小氣泡:閒置時偶爾出現,需要時 Hermes 也會給你一則。關掉一則就不再出現。', tipsReset: (count: number) => `復原 ${count} 則已關閉的提示`, + toursTitle: '導覽', + toursDesc: '讓 Hermes 帶你認識應用程式:調暗畫面並逐步標示每個位置。', composerPopoutTitle: '懸浮輸入框', composerPopoutDesc: '允許將輸入框拖出底部停靠區。關閉後,輸入框會鎖定在底部。', vibeHeartsTitle: '心情愛心', diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts index 6dd0481c37..2f90f09868 100644 --- a/apps/desktop/src/i18n/zh.ts +++ b/apps/desktop/src/i18n/zh.ts @@ -575,8 +575,10 @@ export const zh: Translations = { reactionsTitle: '消息回应', reactionsDesc: 'iMessage 风格的表情回应 — 你可以给消息添加回应,Hermes 也能回应你的消息。', tipsTitle: '应用内提示', - tipsDesc: '应用空闲时,偶尔指出你可能还没发现的功能。关掉一条就不再出现。', + tipsDesc: '指向应用某处的小气泡:空闲时偶尔出现,需要时 Hermes 也会给你一条。关掉一条就不再出现。', tipsReset: (count: number) => `恢复 ${count} 条已关闭的提示`, + toursTitle: '引导导览', + toursDesc: '让 Hermes 带你熟悉应用:调暗界面并逐步高亮每个位置。', composerPopoutTitle: '悬浮输入框', composerPopoutDesc: '允许将输入框拖出底部停靠区。关闭后,输入框会锁定在底部。', vibeHeartsTitle: '心情爱心', diff --git a/apps/desktop/src/store/tips.ts b/apps/desktop/src/store/tips.ts index 99f6dae166..e09d605b2a 100644 --- a/apps/desktop/src/store/tips.ts +++ b/apps/desktop/src/store/tips.ts @@ -1,15 +1,15 @@ /** * In-app tips — the app pointing at itself, plus the agent doing the same. * - * Two sources, one bubble, and only one of them is behind a switch: + * Two sources, one bubble, one switch over both of them: * - * - `$tipRotationEnabled` is the ambient rotation, ON with a switch to stop it. - * A feature nobody meets is a feature nobody has, and the pacing is what - * earns the default: minutes into a launch at the earliest, then six hours, - * which is a nicety rather than the nag that would owe you an opt-in. - * - An agent tip is not ambient. Hermes raises one mid-sentence, in a - * conversation the user is having, exactly as it raises a `tour` — so it - * answers to the same nothing a tour answers to. + * - `$tipsEnabled` is the whole feature, ON with a switch to stop it. A feature + * nobody meets is a feature nobody has, and the pacing is what earns the + * default: minutes into a launch at the earliest, then six hours, which is a + * nicety rather than the nag that would owe you an opt-in. + * - It covers Hermes too. "Off" from someone who has just closed a bubble means + * no bubbles, not "no bubbles unless the agent sends one", so an agent tip is + * dropped at the bridge like a rotation tip is skipped here. * - `$retiredTips` is the hard-close ledger for the rotation. A tip the user ✕'d * never comes back on its own; Settings → Reset is the only way, and that is * the whole contract behind the ✕ being a heavier gesture than letting the @@ -44,7 +44,10 @@ export interface ActiveTip { title?: string } -export const $tipRotationEnabled = persistentAtom('hermes.desktop.tips.rotation.v1', true, Codecs.bool) +// Key still says `rotation` from when the switch only covered that half. +// Renaming it would read as unset for anyone who had already turned tips off, +// and silently turning them back on is the one outcome worth avoiding here. +export const $tipsEnabled = persistentAtom('hermes.desktop.tips.rotation.v1', true, Codecs.bool) export const $retiredTips = persistentAtom('hermes.desktop.tips.retired.v1', [], Codecs.stringArray) export const $lastTipId = persistentAtom('hermes.desktop.tips.last.v1', null, Codecs.nullableText) export const $nextTipAt = persistentAtom( @@ -54,14 +57,14 @@ export const $nextTipAt = persistentAtom( ) export const $activeTip = atom(null) -export function setTipRotationEnabled(enabled: boolean): void { +export function setTipsEnabled(enabled: boolean): void { if (!enabled) { // Including whichever one is up: the switch is answering a bubble on // screen as often as it is answering the idea of them. $activeTip.set(null) } - $tipRotationEnabled.set(enabled) + $tipsEnabled.set(enabled) } /** Un-retire everything, and let the rotation start over from a full deck diff --git a/apps/desktop/src/store/tours.ts b/apps/desktop/src/store/tours.ts new file mode 100644 index 0000000000..44d82c101a --- /dev/null +++ b/apps/desktop/src/store/tours.ts @@ -0,0 +1,20 @@ +/** + * Guided tours (the `tour` tool) — on, with a switch to stop them. + * + * A tour takes the screen: it dims the app, spotlights an element, and pages + * with Next/Prev. That is worth having and worth being able to refuse, and + * unlike tips there is no ambient half to separate out — every tour is Hermes + * running one, so the switch governs the whole feature. + * + * Renderer-owned because the renderer is what a tour happens to. Turning it off + * makes the app decline a tour request outright rather than quietly no-op it, + * so the agent learns the tour didn't run and can say so in words instead. + */ + +import { Codecs, persistentAtom } from '@/lib/persisted' + +export const $toursEnabled = persistentAtom('hermes.desktop.tours.v1', true, Codecs.bool) + +export function setToursEnabled(enabled: boolean): void { + $toursEnabled.set(enabled) +}