From 4708e462d26cb3bbf0596d5b9e7961ccfdb22645 Mon Sep 17 00:00:00 2001
From: RainbowBird <git@luoling.moe>
Date: Sat, 6 Jun 2026 01:37:59 +0800
Subject: [PATCH] feat(stage): track conversation product events

Add PostHog product events for manual TTS stop clicks and conversation controls across Web, mobile, and Electron chat surfaces. Document the events in metrics ownership and cover the analytics API with Vitest.

Signed-off-by: RainbowBird <git@luoling.moe>

Commit-Message-Assisted-by: Codex
---
 .../docs/ai-context/metrics-ownership.md      |   3 +
 .../renderer/components/InteractiveArea.vue   |  30 ++++-
 .../components/Layouts/InteractiveArea.vue    |   8 ++
 .../Layouts/MobileInteractiveArea.vue         |  23 +++-
 .../components/Widgets/ChatActionButtons.vue  |  17 ++-
 .../src/components/Widgets/ChatArea.vue       |   2 +-
 .../composables/useStopSpeakingButton.test.ts |  16 ++-
 .../src/composables/useStopSpeakingButton.ts  |   7 +-
 .../chat/components/sessions-drawer.vue       |  11 +-
 .../src/composables/use-analytics.test.ts     | 127 ++++++++++++++++++
 .../stage-ui/src/composables/use-analytics.ts |  47 +++++++
 11 files changed, 280 insertions(+), 11 deletions(-)
 create mode 100644 packages/stage-ui/src/composables/use-analytics.test.ts

diff --git a/apps/server/docs/ai-context/metrics-ownership.md b/apps/server/docs/ai-context/metrics-ownership.md
index 8b3f82c4b..c12a0c03e 100644
--- a/apps/server/docs/ai-context/metrics-ownership.md
+++ b/apps/server/docs/ai-context/metrics-ownership.md
@@ -125,6 +125,9 @@
 | Activation / Retention | `first_model_selected` / `model_switched` | 前端（consciousness store watcher） | `packages/stage-ui/src/stores/analytics/index.ts` | PostHog |
 | Retention | `character_created` | 前端 | `apps/stage-web/src/pages/settings/characters/components/CharacterDialog.vue` | PostHog |
 | Retention | `chat_session_started` | 前端 | `packages/stage-ui/src/components/scenarios/chat/components/sessions-drawer.vue` | PostHog |
+| Conversation controls | `chat_session_selected` | 前端 | `packages/stage-ui/src/components/scenarios/chat/components/sessions-drawer.vue` | PostHog |
+| Conversation controls | `chat_message_deleted` / `chat_messages_cleared` / `chat_message_retried` | 前端 | `packages/stage-layouts/src/components/Layouts/*InteractiveArea.vue` / `packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue` / `apps/stage-tamagotchi/src/renderer/components/InteractiveArea.vue` | PostHog |
+| Conversation controls | `tts_stop_clicked` | 前端 | `packages/stage-layouts/src/composables/useStopSpeakingButton.ts` | PostHog |
 | Churn | `subscription_cancelled`（带 cancellation_reason） | 外部 Stripe 数据源 | PostHog Stripe source connector | Stripe/Postgres |
 | 老事件 | `provider_card_clicked` / `first_message_sent` | 前端 | `packages/stage-ui/src/composables/use-analytics.ts` | PostHog |
 
diff --git a/apps/stage-tamagotchi/src/renderer/components/InteractiveArea.vue b/apps/stage-tamagotchi/src/renderer/components/InteractiveArea.vue
index 620e4d9d6..1b3b350b5 100644
--- a/apps/stage-tamagotchi/src/renderer/components/InteractiveArea.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/InteractiveArea.vue
@@ -5,6 +5,7 @@ import type { ChatHistoryItem } from '@proj-airi/stage-ui/types/chat'
 import { errorMessageFrom } from '@moeru/std'
 import { useStopSpeakingButton } from '@proj-airi/stage-layouts/composables/useStopSpeakingButton'
 import { ChatHistory, JournalPreviewModal } from '@proj-airi/stage-ui/components'
+import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { useBackgroundStore } from '@proj-airi/stage-ui/stores/background'
 import { useChatOrchestratorStore } from '@proj-airi/stage-ui/stores/chat'
 import { useChatSessionStore } from '@proj-airi/stage-ui/stores/chat/session-store'
@@ -57,7 +58,12 @@ const sendModeLabels = computed<Record<SendMode, string>>(() => ({
   'ctrl-enter': t('stage.send-mode.ctrl-enter'),
   'double-enter': t('stage.send-mode.double-enter'),
 }))
-const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton()
+const {
+  trackChatMessageDeleted,
+  trackChatMessageRetried,
+  trackChatMessagesCleared,
+} = useAnalytics()
+const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton('electron')
 
 const latestImageEntries = computed(() => {
   if (!activeCardId.value)
@@ -198,7 +204,13 @@ watch(sendMode, () => {
 const historyMessages = computed(() => messages.value as unknown as ChatHistoryItem[])
 
 async function handleDeleteMessage(index: number) {
+  const message = messages.value[index]
   await chatSyncStore.requestDeleteMessage({ index })
+  trackChatMessageDeleted({
+    surface: 'electron',
+    source: 'history',
+    message_role: message?.role ?? 'unknown',
+  })
 }
 
 onMounted(() => {
@@ -210,6 +222,20 @@ async function handleRetryMessage(index: number) {
     sessionId: chatSession.activeSessionId,
     index,
   })
+  trackChatMessageRetried({
+    surface: 'electron',
+    source: 'history',
+  })
+}
+
+async function handleCleanupMessages() {
+  const messageCount = messages.value.filter(message => message.role !== 'system').length
+  await chatSyncStore.requestCleanup()
+  trackChatMessagesCleared({
+    surface: 'electron',
+    source: 'chat_controls',
+    message_count: messageCount,
+  })
 }
 </script>
 
@@ -351,7 +377,7 @@ async function handleRetryMessage(index: number) {
         hover:text="red-500 dark:red-400"
         flex items-center justify-center rounded-md p-2 outline-none
         transition-colors transition-transform active:scale-95
-        @click="() => chatSyncStore.requestCleanup()"
+        @click="handleCleanupMessages"
       >
         <div class="i-solar:trash-bin-2-bold-duotone" />
       </button>
diff --git a/packages/stage-layouts/src/components/Layouts/InteractiveArea.vue b/packages/stage-layouts/src/components/Layouts/InteractiveArea.vue
index f33465c2e..e515ed2cb 100644
--- a/packages/stage-layouts/src/components/Layouts/InteractiveArea.vue
+++ b/packages/stage-layouts/src/components/Layouts/InteractiveArea.vue
@@ -2,6 +2,7 @@
 import type { ChatHistoryItem } from '@proj-airi/stage-ui/types/chat'
 
 import { ChatHistory } from '@proj-airi/stage-ui/components'
+import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { useChatOrchestratorStore } from '@proj-airi/stage-ui/stores/chat'
 import { useChatSessionStore } from '@proj-airi/stage-ui/stores/chat/session-store'
 import { useChatStreamStore } from '@proj-airi/stage-ui/stores/chat/stream-store'
@@ -20,9 +21,16 @@ const { streamingMessage } = storeToRefs(useChatStreamStore())
 
 const isLoading = ref(true)
 const historyMessages = computed(() => messages.value as unknown as ChatHistoryItem[])
+const { trackChatMessageDeleted } = useAnalytics()
 
 function handleDeleteMessage(index: number) {
+  const message = messages.value[index]
   messages.value = messages.value.filter((_, messageIndex) => messageIndex !== index)
+  trackChatMessageDeleted({
+    surface: 'web',
+    source: 'history',
+    message_role: message?.role ?? 'unknown',
+  })
 }
 </script>
 
diff --git a/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue b/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue
index 09ced3276..81b6323f5 100644
--- a/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue
+++ b/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue
@@ -6,7 +6,7 @@ import { isStageTamagotchi } from '@proj-airi/stage-shared'
 import { useThreeViewControl } from '@proj-airi/stage-ui-three'
 import { ChatHistory, HearingConfigDialog } from '@proj-airi/stage-ui/components'
 import { ChatSessionsDrawer } from '@proj-airi/stage-ui/components/scenarios/chat'
-import { useAudioAnalyzer } from '@proj-airi/stage-ui/composables'
+import { useAnalytics, useAudioAnalyzer } from '@proj-airi/stage-ui/composables'
 import { useAudioContext } from '@proj-airi/stage-ui/stores/audio'
 import { useChatOrchestratorStore } from '@proj-airi/stage-ui/stores/chat'
 import { useChatMaintenanceStore } from '@proj-airi/stage-ui/stores/chat/maintenance'
@@ -40,9 +40,26 @@ const { messages } = storeToRefs(chatSession)
 const { streamingMessage } = storeToRefs(chatStream)
 const { sending } = storeToRefs(chatOrchestrator)
 const historyMessages = computed(() => messages.value as unknown as ChatHistoryItem[])
+const { trackChatMessageDeleted, trackChatMessagesCleared } = useAnalytics()
 
 function handleDeleteMessage(index: number) {
+  const message = messages.value[index]
   messages.value = messages.value.filter((_, messageIndex) => messageIndex !== index)
+  trackChatMessageDeleted({
+    surface: 'mobile',
+    source: 'history',
+    message_role: message?.role ?? 'unknown',
+  })
+}
+
+function handleCleanupMessages() {
+  const messageCount = messages.value.filter(message => message.role !== 'system').length
+  cleanupMessages()
+  trackChatMessagesCleared({
+    surface: 'mobile',
+    source: 'chat_controls',
+    message_count: messageCount,
+  })
 }
 
 const messageInput = ref('')
@@ -77,7 +94,7 @@ const { isListening, startStreamingTranscription, stopStreamingTranscription } =
     isStageTamagotchi,
   },
 )
-const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton()
+const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton('mobile')
 const toggleTranscription = () => isListening.value ? stopStreamingTranscription() : startStreamingTranscription()
 
 async function handleSubmit() {
@@ -232,7 +249,7 @@ onMounted(() => {
             bg="neutral-50/70 dark:neutral-800/70"
             w-fit flex items-center self-end justify-center rounded-xl p-2 backdrop-blur-md
             title="Cleanup Messages"
-            @click="cleanupMessages()"
+            @click="handleCleanupMessages"
           >
             <div class="i-solar:trash-bin-2-bold-duotone" />
           </button>
diff --git a/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue b/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue
index d0133d488..1871be0c4 100644
--- a/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue
+++ b/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue
@@ -1,6 +1,9 @@
 <script setup lang="ts">
+import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { useChatMaintenanceStore } from '@proj-airi/stage-ui/stores/chat/maintenance'
+import { useChatSessionStore } from '@proj-airi/stage-ui/stores/chat/session-store'
 import { useTheme } from '@proj-airi/ui'
+import { storeToRefs } from 'pinia'
 import { ref } from 'vue'
 
 import ViewControls from '../Layouts/InteractiveArea/Actions/ViewControls.vue'
@@ -8,9 +11,21 @@ import ViewControls from '../Layouts/InteractiveArea/Actions/ViewControls.vue'
 import { BackgroundDialogPicker } from '../Backgrounds'
 
 const { cleanupMessages } = useChatMaintenanceStore()
+const { messages } = storeToRefs(useChatSessionStore())
+const { trackChatMessagesCleared } = useAnalytics()
 const { isDark, toggleDark } = useTheme()
 
 const backgroundDialogOpen = ref(false)
+
+function handleCleanupMessages() {
+  const messageCount = messages.value.filter(message => message.role !== 'system').length
+  cleanupMessages()
+  trackChatMessagesCleared({
+    surface: 'web',
+    source: 'chat_controls',
+    message_count: messageCount,
+  })
+}
 </script>
 
 <template>
@@ -24,7 +39,7 @@ const backgroundDialogOpen = ref(false)
       hover:text="red-500 dark:red-400"
       flex items-center justify-center rounded-md p-2 outline-none
       transition-colors transition-transform active:scale-95
-      @click="cleanupMessages()"
+      @click="handleCleanupMessages"
     >
       <div class="i-solar:trash-bin-2-bold-duotone" />
     </button>
diff --git a/packages/stage-layouts/src/components/Widgets/ChatArea.vue b/packages/stage-layouts/src/components/Widgets/ChatArea.vue
index 4d88feb60..bd0300d18 100644
--- a/packages/stage-layouts/src/components/Widgets/ChatArea.vue
+++ b/packages/stage-layouts/src/components/Widgets/ChatArea.vue
@@ -60,7 +60,7 @@ const { isListening, startStreamingTranscription, stopStreamingTranscription, au
     isStageTamagotchi,
   },
 )
-const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton()
+const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton('web')
 
 async function handleSend() {
   if (!messageInput.value.trim() || isComposing.value) {
diff --git a/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts b/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts
index 921d121fe..631e1902a 100644
--- a/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts
+++ b/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts
@@ -5,6 +5,7 @@ import { useStopSpeakingButton } from './useStopSpeakingButton'
 
 const nowSpeaking = ref(false)
 const requestStopSpeakingMock = vi.fn()
+const trackTtsStopClickedMock = vi.fn()
 
 vi.mock('@proj-airi/stage-ui/stores/audio', () => ({
   useSpeakingStore: () => ({
@@ -18,6 +19,12 @@ vi.mock('@proj-airi/stage-ui/stores/speech-output-control', () => ({
   }),
 }))
 
+vi.mock('@proj-airi/stage-ui/composables/use-analytics', () => ({
+  useAnalytics: () => ({
+    trackTtsStopClicked: trackTtsStopClickedMock,
+  }),
+}))
+
 vi.mock('pinia', () => ({
   storeToRefs: (store: object) => store,
 }))
@@ -26,7 +33,7 @@ describe('useStopSpeakingButton', () => {
   it('shows the manual stop button only while the assistant is speaking', () => {
     nowSpeaking.value = false
 
-    const { showStopSpeakingButton } = useStopSpeakingButton()
+    const { showStopSpeakingButton } = useStopSpeakingButton('web')
 
     expect(showStopSpeakingButton.value).toBe(false)
 
@@ -37,11 +44,16 @@ describe('useStopSpeakingButton', () => {
 
   it('requests a manual chat stop without touching chat input state', () => {
     requestStopSpeakingMock.mockClear()
+    trackTtsStopClickedMock.mockClear()
 
-    const { stopSpeakingFromChat } = useStopSpeakingButton()
+    const { stopSpeakingFromChat } = useStopSpeakingButton('mobile')
 
     stopSpeakingFromChat()
 
     expect(requestStopSpeakingMock).toHaveBeenCalledWith('manual-chat')
+    expect(trackTtsStopClickedMock).toHaveBeenCalledWith({
+      surface: 'mobile',
+      reason: 'manual-chat',
+    })
   })
 })
diff --git a/packages/stage-layouts/src/composables/useStopSpeakingButton.ts b/packages/stage-layouts/src/composables/useStopSpeakingButton.ts
index f34f15318..ea35562dc 100644
--- a/packages/stage-layouts/src/composables/useStopSpeakingButton.ts
+++ b/packages/stage-layouts/src/composables/useStopSpeakingButton.ts
@@ -1,3 +1,6 @@
+import type { ConversationAnalyticsSurface } from '@proj-airi/stage-ui/composables/use-analytics'
+
+import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { useSpeakingStore } from '@proj-airi/stage-ui/stores/audio'
 import { useSpeechOutputControlStore } from '@proj-airi/stage-ui/stores/speech-output-control'
 import { storeToRefs } from 'pinia'
@@ -15,13 +18,15 @@ import { computed } from 'vue'
  * Returns:
  * - Visibility state for the button and a click handler for manual chat stops.
  */
-export function useStopSpeakingButton() {
+export function useStopSpeakingButton(surface: ConversationAnalyticsSurface) {
   const { nowSpeaking } = storeToRefs(useSpeakingStore())
   const speechOutputControlStore = useSpeechOutputControlStore()
+  const { trackTtsStopClicked } = useAnalytics()
 
   const showStopSpeakingButton = computed(() => nowSpeaking.value)
 
   function stopSpeakingFromChat() {
+    trackTtsStopClicked({ surface, reason: 'manual-chat' })
     speechOutputControlStore.requestStopSpeaking('manual-chat')
   }
 
diff --git a/packages/stage-ui/src/components/scenarios/chat/components/sessions-drawer.vue b/packages/stage-ui/src/components/scenarios/chat/components/sessions-drawer.vue
index fda508a65..2967ade77 100644
--- a/packages/stage-ui/src/components/scenarios/chat/components/sessions-drawer.vue
+++ b/packages/stage-ui/src/components/scenarios/chat/components/sessions-drawer.vue
@@ -47,7 +47,7 @@ const { sessionMetas, sessionMessages, activeSessionId } = storeToRefs(chatSessi
 const { activeCardId } = storeToRefs(useAiriCardStore())
 const { userId } = storeToRefs(useAuthStore())
 const { activeModel } = storeToRefs(useConsciousnessStore())
-const { trackChatSessionStarted } = useAnalytics()
+const { trackChatSessionSelected, trackChatSessionStarted } = useAnalytics()
 
 // Re-entry guard for the "new session" button. Without this, a rapid
 // double-click would call `createSession` twice (creating two orphan
@@ -154,6 +154,15 @@ const rows = computed<SessionRow[]>(() => {
 })
 
 async function selectSession(sessionId: string) {
+  const selectedRow = rows.value.find(row => row.meta.sessionId === sessionId)
+  if (sessionId !== activeSessionId.value && selectedRow) {
+    trackChatSessionSelected({
+      surface: isDesktop.value ? 'web' : 'mobile',
+      source: 'sessions_drawer',
+      message_count: (sessionMessages.value[sessionId] ?? []).filter(message => message.role !== 'system').length,
+      cloud_synced: !!selectedRow.meta.cloudChatId,
+    })
+  }
   chatSession.setActiveSession(sessionId)
   showDialog.value = false
 }
diff --git a/packages/stage-ui/src/composables/use-analytics.test.ts b/packages/stage-ui/src/composables/use-analytics.test.ts
new file mode 100644
index 000000000..d0ca05763
--- /dev/null
+++ b/packages/stage-ui/src/composables/use-analytics.test.ts
@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ref } from 'vue'
+
+import { useAnalytics } from './use-analytics'
+
+const analyticsMocks = vi.hoisted(() => ({
+  ensurePosthogInitializedMock: vi.fn(() => true),
+  isPosthogAvailableInBuildMock: vi.fn(() => true),
+  markFirstMessageTrackedMock: vi.fn(),
+  posthogCaptureMock: vi.fn(),
+}))
+
+vi.mock('posthog-js', () => ({
+  default: {
+    capture: analyticsMocks.posthogCaptureMock,
+  },
+}))
+
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({
+    locale: ref('en'),
+  }),
+}))
+
+vi.mock('../stores/analytics', () => ({
+  useSharedAnalyticsStore: () => ({
+    appStartTime: null,
+    firstMessageTracked: false,
+    markFirstMessageTracked: analyticsMocks.markFirstMessageTrackedMock,
+  }),
+}))
+
+vi.mock('../stores/analytics/posthog', () => ({
+  ensurePosthogInitialized: analyticsMocks.ensurePosthogInitializedMock,
+  isPosthogAvailableInBuild: analyticsMocks.isPosthogAvailableInBuildMock,
+}))
+
+vi.mock('../stores/analytics/privacy-policy', () => ({
+  getAnalyticsPrivacyPolicyUrl: () => 'https://example.com/privacy',
+}))
+
+vi.mock('../stores/settings/analytics', () => ({
+  useSettingsAnalytics: () => ({
+    analyticsEnabled: true,
+  }),
+}))
+
+vi.mock('../stores/settings/general', () => ({
+  useSettingsGeneral: () => ({
+    language: 'en',
+  }),
+}))
+
+describe('useAnalytics conversation product events', () => {
+  beforeEach(() => {
+    analyticsMocks.posthogCaptureMock.mockClear()
+    analyticsMocks.markFirstMessageTrackedMock.mockClear()
+    analyticsMocks.ensurePosthogInitializedMock.mockClear()
+    analyticsMocks.isPosthogAvailableInBuildMock.mockClear()
+  })
+
+  it('tracks manual TTS stop clicks with the UI surface and reason', () => {
+    const analytics = useAnalytics()
+
+    analytics.trackTtsStopClicked({
+      surface: 'mobile',
+      reason: 'manual-chat',
+    })
+
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenCalledWith('tts_stop_clicked', {
+      surface: 'mobile',
+      reason: 'manual-chat',
+    })
+  })
+
+  it('tracks chat session selection from the sessions drawer', () => {
+    const analytics = useAnalytics()
+
+    analytics.trackChatSessionSelected({
+      surface: 'web',
+      source: 'sessions_drawer',
+      message_count: 4,
+      cloud_synced: true,
+    })
+
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenCalledWith('chat_session_selected', {
+      surface: 'web',
+      source: 'sessions_drawer',
+      message_count: 4,
+      cloud_synced: true,
+    })
+  })
+
+  it('tracks destructive and recovery chat message actions', () => {
+    const analytics = useAnalytics()
+
+    analytics.trackChatMessageDeleted({
+      surface: 'electron',
+      source: 'history',
+      message_role: 'assistant',
+    })
+    analytics.trackChatMessagesCleared({
+      surface: 'electron',
+      source: 'chat_controls',
+      message_count: 3,
+    })
+    analytics.trackChatMessageRetried({
+      surface: 'electron',
+      source: 'history',
+    })
+
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenNthCalledWith(1, 'chat_message_deleted', {
+      surface: 'electron',
+      source: 'history',
+      message_role: 'assistant',
+    })
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenNthCalledWith(2, 'chat_messages_cleared', {
+      surface: 'electron',
+      source: 'chat_controls',
+      message_count: 3,
+    })
+    expect(analyticsMocks.posthogCaptureMock).toHaveBeenNthCalledWith(3, 'chat_message_retried', {
+      surface: 'electron',
+      source: 'history',
+    })
+  })
+})
diff --git a/packages/stage-ui/src/composables/use-analytics.ts b/packages/stage-ui/src/composables/use-analytics.ts
index 52ab87d48..ac4e99128 100644
--- a/packages/stage-ui/src/composables/use-analytics.ts
+++ b/packages/stage-ui/src/composables/use-analytics.ts
@@ -9,6 +9,16 @@ import { getAnalyticsPrivacyPolicyUrl } from '../stores/analytics/privacy-policy
 import { useSettingsAnalytics } from '../stores/settings/analytics'
 import { useSettingsGeneral } from '../stores/settings/general'
 
+/**
+ * User-facing chat surfaces that can emit product analytics.
+ */
+export type ConversationAnalyticsSurface = 'web' | 'mobile' | 'electron'
+
+/**
+ * Low-cardinality source names for conversation action events.
+ */
+export type ConversationAnalyticsSource = 'chat_controls' | 'history' | 'sessions_drawer'
+
 export function useAnalytics() {
   const analyticsStore = useSharedAnalyticsStore()
   const settingsAnalytics = useSettingsAnalytics()
@@ -207,6 +217,38 @@ export function useAnalytics() {
     posthog.capture('message_round', properties)
   }
 
+  // ─── Conversation action events ─────────────────────────────────────
+
+  function trackTtsStopClicked(properties: { surface: ConversationAnalyticsSurface, reason: 'manual-chat' }) {
+    if (!canCapture())
+      return
+    posthog.capture('tts_stop_clicked', properties)
+  }
+
+  function trackChatSessionSelected(properties: { surface: ConversationAnalyticsSurface, source: 'sessions_drawer', message_count: number, cloud_synced: boolean }) {
+    if (!canCapture())
+      return
+    posthog.capture('chat_session_selected', properties)
+  }
+
+  function trackChatMessageDeleted(properties: { surface: ConversationAnalyticsSurface, source: 'history', message_role: string }) {
+    if (!canCapture())
+      return
+    posthog.capture('chat_message_deleted', properties)
+  }
+
+  function trackChatMessagesCleared(properties: { surface: ConversationAnalyticsSurface, source: 'chat_controls', message_count: number }) {
+    if (!canCapture())
+      return
+    posthog.capture('chat_messages_cleared', properties)
+  }
+
+  function trackChatMessageRetried(properties: { surface: ConversationAnalyticsSurface, source: 'history' }) {
+    if (!canCapture())
+      return
+    posthog.capture('chat_message_retried', properties)
+  }
+
   // ─── STT events ──────────────────────────────────────────────────────
 
   function trackSttStarted(provider: string) {
@@ -362,6 +404,11 @@ export function useAnalytics() {
     trackLlmFirstToken,
     trackAssistantResponseRendered,
     trackMessageRound,
+    trackTtsStopClicked,
+    trackChatSessionSelected,
+    trackChatMessageDeleted,
+    trackChatMessagesCleared,
+    trackChatMessageRetried,
 
     trackSttStarted,
     trackSttSucceeded,