feat(fairy): add UI event tracking for fairy interactions (tldraw#7245)

Adds comprehensive event tracking for fairy-related UI interactions to
enable analytics and usage insights.

### Change type

- [x] `improvement`

### Test plan

1. Open a document with fairies enabled
2. Interact with fairies (select, drag, chat, etc.)
3. Verify events are tracked in analytics

### Release notes

- Added event tracking for fairy UI interactions including selection,
messaging, project management, navigation, and panel state changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds analytics tracking to key fairy interactions
(select/drag/chat/follow/sleep/project, etc.), extends app UI event
schema/sources, and updates a strict-mode test expectation.
> 
> - **Analytics instrumentation (fairy)**:
> - Add `useTldrawAppUiEvents` to `fairy` components to track
interactions: selection/multi-select (`fairy-select`,
`fairy-add-to-selection`, `fairy-deselect`, `fairy-select-all`),
drag/long-press (`fairy-drag-start`, `fairy-panic`), navigation
(`fairy-zoom-to`, `fairy-summon`, `fairy-summon-all`, `fairy-follow`,
`fairy-unfollow`), chat (`fairy-send-message`,
`fairy-cancel-generation`, `fairy-reset-chat`, `fairy-reset-all-chats`),
state (`fairy-sleep`, `fairy-sleep-all`, `fairy-wake`), UI/panel
(`fairy-switch-to-manual`, `fairy-close-manual`,
`fairy-switch-manual-tab`, `click-fairy-teaser`), and projects
(`fairy-start-project`, `fairy-disband-group`).
> - Updated files: `fairy/Fairy.tsx`, `fairy-ui/hud/FairyHUDHeader.tsx`,
`fairy-ui/FairyHUDTeaser.tsx`, `fairy-ui/hud/FairySingleChatInput.tsx`,
`fairy-ui/hud/useFairySelection.ts`,
`fairy-ui/menus/FairyMenuContent.tsx`,
`fairy-ui/project/FairyProjectView.tsx`.
> - **Event schema**:
> - Extend `TLAppUiEventSource` and `TLAppUiEventMap` in
`tla/utils/app-ui-events.tsx` with new fairy sources and events.
> - **Tests**:
> - Relax strict assertion in
`packages/tldraw/src/test/TldrawEditor.test.tsx` for `onMount` under
React StrictMode.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
c91ea34. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: steveruizok

apps/dotcom/client/src/fairy/Fairy.tsx

@@ -4,6 +4,7 @@ import { ContextMenu as _ContextMenu } from 'radix-ui'
 import React, { useEffect, useRef } from 'react'
 import { Atom, TLEventInfo, getPointerInfo, useEditor, useQuickReactor, useValue } from 'tldraw'
 import '../tla/styles/fairy.css'
+import { TLAppUiHandler, useTldrawAppUiEvents } from '../tla/utils/app-ui-events'
 import { FairyAgent } from './fairy-agent/FairyAgent'
 import { $fairyAgentsAtom } from './fairy-globals'
 import { getProjectColor } from './fairy-helpers/getProjectColor'
@@ -46,11 +47,13 @@ function updateFairySelection(
 	fairyAgents: FairyAgent[],
 	clickedAgent: FairyAgent,
 	wasSelected: boolean,
-	isMultiSelect: boolean
+	isMultiSelect: boolean,
+	trackEvent: TLAppUiHandler
 ) {
 	if (!isMultiSelect) {
 		// Regular click: select clicked fairy, deselect others
 		if (!wasSelected) {
+			trackEvent('fairy-select', { source: 'fairy-canvas', fairyId: clickedAgent.id })
 			fairyAgents.forEach((a) => {
 				if (a.id === clickedAgent.id) {
 					a.$fairyEntity.update((f) => (f ? { ...f, isSelected: true } : f))
@@ -63,6 +66,7 @@ function updateFairySelection(
 	} else {
 		// Multi-select: add to selection if not selected
 		if (!wasSelected) {
+			trackEvent('fairy-add-to-selection', { source: 'fairy-canvas', fairyId: clickedAgent.id })
 			clickedAgent.$fairyEntity.update((f) => (f ? { ...f, isSelected: true } : f))
 		}
 		// If already selected, do nothing (will handle deselection on pointer up)
@@ -88,7 +92,8 @@ function useFairyPointerInteraction(
 	ref: React.RefObject<HTMLDivElement>,
 	agent: FairyAgent,
 	editor: ReturnType<typeof useEditor>,
-	isFairyGrabbable: boolean
+	isFairyGrabbable: boolean,
+	trackEvent: TLAppUiHandler
 ) {
 	const interactionState = useRef<FairyInteractionState>({ status: 'idle' })
 	const longPressTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
@@ -128,6 +133,7 @@ function useFairyPointerInteraction(
 			cleanupPointerListeners()
 			cleanupEditorEventListener()
 
+			trackEvent('fairy-drag-start', { source: 'fairy-canvas', fairyId: agent.id })
 			setFairiesToThrowTool(editor, currentState.fairiesAtPointerDown)
 			editor.setCurrentTool('select.fairy-throw')
 			interactionState.current = { status: 'idle' }
@@ -228,7 +234,7 @@ function useFairyPointerInteraction(
 				const wasClickedFairySelected = clickedFairyEntity?.isSelected ?? false
 				const isMultiSelect = e.shiftKey || e.ctrlKey || e.metaKey
 
-				updateFairySelection(fairyAgents, agent, wasClickedFairySelected, isMultiSelect)
+				updateFairySelection(fairyAgents, agent, wasClickedFairySelected, isMultiSelect, trackEvent)
 
 				const fairiesToDrag: Atom<FairyEntity>[] = []
 				const selectedFairies = getSelectedFairyAtoms(fairyAgents)
@@ -256,6 +262,7 @@ function useFairyPointerInteraction(
 					const currentState = interactionState.current
 					// Only trigger panicking if still pressed and not dragging
 					if (currentState.status === 'pressed' && !editor.inputs.isDragging) {
+						trackEvent('fairy-panic', { source: 'fairy-canvas', fairyId: agent.id })
 						agent.gestureManager.push('panicking')
 					}
 					longPressTimerRef.current = null
@@ -275,11 +282,12 @@ function useFairyPointerInteraction(
 			document.removeEventListener('pointermove', handlePointerMove)
 			document.removeEventListener('pointerup', handlePointerUp)
 		}
-	}, [agent, editor, isFairyGrabbable, $fairyEntity, ref])
+	}, [agent, editor, isFairyGrabbable, $fairyEntity, ref, trackEvent])
 }
 
 export function Fairy({ agent }: { agent: FairyAgent }) {
 	const editor = useEditor()
+	const trackEvent = useTldrawAppUiEvents()
 	const fairyRef = useRef<HTMLDivElement>(null)
 	const $fairyEntity = agent.$fairyEntity
 	const $fairyConfig = agent.$fairyConfig
@@ -322,7 +330,7 @@ export function Fairy({ agent }: { agent: FairyAgent }) {
 	const isGenerating = useValue('is generating', () => agent.requestManager.isGenerating(), [agent])
 	const isFairyGrabbable = isInSelectTool
 
-	useFairyPointerInteraction(fairyRef, agent, editor, isFairyGrabbable)
+	useFairyPointerInteraction(fairyRef, agent, editor, isFairyGrabbable, trackEvent)
 
 	useQuickReactor(
 		'fairy position',

apps/dotcom/client/src/fairy/fairy-ui/FairyHUDTeaser.tsx

@@ -22,6 +22,7 @@ import {
 	TlaMenuTabsTabs,
 } from '../../tla/components/tla-menu/tla-menu'
 import '../../tla/styles/fairy.css'
+import { useTldrawAppUiEvents } from '../../tla/utils/app-ui-events'
 import { F, useMsg } from '../../tla/utils/i18n'
 import { getLocalSessionState, updateLocalSessionState } from '../../tla/utils/local-session-state'
 import { fairyMessages } from '../fairy-messages'
@@ -31,6 +32,7 @@ import { FairyManualPanel } from './manual/FairyManualPanel'
 export function FairyHUDTeaser() {
 	// should match fairy FairyHUD, but with one fairy sprite here
 	const editor = useEditor()
+	const trackEvent = useTldrawAppUiEvents()
 	const breakpoint = useBreakpoint()
 	const isDebugMode = useValue('debug', () => editor.getInstanceState().isDebugMode, [editor])
 	const [mobileMenuOffset, setMobileMenuOffset] = useState<number | null>(null)
@@ -53,13 +55,23 @@ export function FairyHUDTeaser() {
 		[]
 	)
 
-	const handleTabChange = useCallback((value: 'introduction' | 'usage' | 'about') => {
-		updateLocalSessionState(() => ({ fairyManualActiveTab: value }))
-	}, [])
+	const handleTabChange = useCallback(
+		(value: 'introduction' | 'usage' | 'about') => {
+			trackEvent('fairy-switch-manual-tab', { source: 'fairy-teaser', tab: value })
+			updateLocalSessionState(() => ({ fairyManualActiveTab: value }))
+		},
+		[trackEvent]
+	)
 
 	const handleToggleManual = useCallback(() => {
-		setIsManualOpen((prev) => !prev)
-	}, [])
+		const wasOpen = isManualOpen
+		if (wasOpen) {
+			trackEvent('fairy-close-manual', { source: 'fairy-teaser' })
+		} else {
+			trackEvent('fairy-switch-to-manual', { source: 'fairy-teaser' })
+		}
+		setIsManualOpen(!wasOpen)
+	}, [trackEvent, isManualOpen])
 
 	// Position HUD above mobile style menu button on mobile
 	useEffect(() => {
@@ -154,6 +166,7 @@ export function FairyHUDTeaser() {
 									aria-label="Fairies"
 									value="off"
 									onClick={() => {
+										trackEvent('click-fairy-teaser', { source: 'fairy-teaser' })
 										addDialog({
 											component: FairyComingSoonDialog,
 										})

apps/dotcom/client/src/fairy/fairy-ui/hud/FairyHUDHeader.tsx

@@ -14,6 +14,7 @@ import {
 	TlaMenuTabsTab,
 	TlaMenuTabsTabs,
 } from '../../../tla/components/tla-menu/tla-menu'
+import { useTldrawAppUiEvents } from '../../../tla/utils/app-ui-events'
 import { F } from '../../../tla/utils/i18n'
 import {
 	getLocalSessionState,
@@ -45,6 +46,7 @@ export function FairyHUDHeader({
 	isMobile,
 	onToggleManual,
 }: FairyHUDHeaderProps) {
+	const trackEvent = useTldrawAppUiEvents()
 	const fairyConfig = useValue('fairy config', () => shownFairy?.$fairyConfig.get(), [shownFairy])
 
 	// Get the project for the shown fairy
@@ -73,8 +75,9 @@ export function FairyHUDHeader({
 	const zoomToFairy = useCallback(() => {
 		if (!fairyClickable || !shownFairy) return
 
+		trackEvent('fairy-zoom-to', { source: 'fairy-panel', fairyId: shownFairy.id })
 		shownFairy.positionManager.zoomTo()
-	}, [shownFairy, fairyClickable])
+	}, [shownFairy, fairyClickable, trackEvent])
 
 	// const hasChatHistory = useValue(
 	// 	'has-chat-history',
@@ -115,15 +118,20 @@ export function FairyHUDHeader({
 		[]
 	)
 
-	const handleTabChange = useCallback((value: 'introduction' | 'usage' | 'about') => {
-		updateLocalSessionState(() => ({ fairyManualActiveTab: value }))
-	}, [])
+	const handleTabChange = useCallback(
+		(value: 'introduction' | 'usage' | 'about') => {
+			trackEvent('fairy-switch-manual-tab', { source: 'fairy-panel', tab: value })
+			updateLocalSessionState(() => ({ fairyManualActiveTab: value }))
+		},
+		[trackEvent]
+	)
 
 	const selectAllFairies = useCallback(() => {
+		trackEvent('fairy-select-all', { source: 'fairy-panel' })
 		allAgents.forEach((agent) => {
 			agent.$fairyEntity.update((f) => (f ? { ...f, isSelected: true } : f))
 		})
-	}, [allAgents])
+	}, [allAgents, trackEvent])
 
 	if (panelState === 'manual') {
 		return (
@@ -220,13 +228,15 @@ function FairyDropdownContent({ agents }: { agents: FairyAgent[] }) {
 }
 
 function ResetChatHistoryButton({ agent }: { agent: FairyAgent }) {
+	const trackEvent = useTldrawAppUiEvents()
 	return (
 		<TldrawUiButton
 			type="icon"
 			className="fairy-toolbar-button"
 			// Maybe needs to be reactive
 			disabled={agent.chatManager.getHistory().length === 0}
 			onClick={() => {
+				trackEvent('fairy-reset-chat', { source: 'fairy-panel', fairyId: agent.id })
 				agent.chatManager.reset()
 			}}
 		>

apps/dotcom/client/src/fairy/fairy-ui/hud/FairySingleChatInput.tsx

@@ -1,6 +1,7 @@
 import { CancelIcon, FAIRY_VISION_DIMENSIONS, LipsIcon } from '@tldraw/fairy-shared'
 import { KeyboardEvent, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { Box, useEditor, useValue } from 'tldraw'
+import { useTldrawAppUiEvents } from '../../../tla/utils/app-ui-events'
 import { getIsCoarsePointer } from '../../../tla/utils/getIsCoarsePointer'
 import { useMsg } from '../../../tla/utils/i18n'
 import { FairyAgent } from '../../fairy-agent/FairyAgent'
@@ -9,6 +10,7 @@ import { fairyMessages } from '../../fairy-messages'
 
 export function FairySingleChatInput({ agent, onCancel }: { agent: FairyAgent; onCancel(): void }) {
 	const editor = useEditor()
+	const trackEvent = useTldrawAppUiEvents()
 	const textareaRef = useRef<HTMLTextAreaElement>(null)
 	const [inputValue, setInputValue] = useState('')
 	const isGenerating = useValue('isGenerating', () => agent.requestManager.isGenerating(), [agent])
@@ -62,9 +64,10 @@ export function FairySingleChatInput({ agent, onCancel }: { agent: FairyAgent; o
 			// Clear the input
 			setInputValue('')
 
+			trackEvent('fairy-send-message', { source: 'fairy-chat', fairyId: agent.id })
 			handlePrompt(value)
 		},
-		[handlePrompt]
+		[handlePrompt, trackEvent, agent.id]
 	)
 
 	// Handle keyboard input for Enter and Shift+Enter
@@ -92,6 +95,7 @@ export function FairySingleChatInput({ agent, onCancel }: { agent: FairyAgent; o
 	const handleButtonClick = () => {
 		if (showCancel) {
 			// Hard stop - cancel only, don't send
+			trackEvent('fairy-cancel-generation', { source: 'fairy-chat', fairyId: agent.id })
 			agent.cancel()
 		} else {
 			// Send (will interrupt if generating)

apps/dotcom/client/src/fairy/fairy-ui/hud/useFairySelection.ts

@@ -1,12 +1,14 @@
 import { FairyProject } from '@tldraw/fairy-shared'
 import { MouseEvent, useCallback, useEffect, useState } from 'react'
 import { useValue } from 'tldraw'
+import { useTldrawAppUiEvents } from '../../../tla/utils/app-ui-events'
 import { FairyAgent } from '../../fairy-agent/FairyAgent'
 import { getProjectOrchestrator } from '../../fairy-projects'
 
 export type FairyHUDPanelState = 'fairy' | 'manual' | 'closed'
 
 export function useFairySelection(agents: FairyAgent[]) {
+	const trackEvent = useTldrawAppUiEvents()
 	const [manualOpen, setManualOpen] = useState(false)
 	const [shownFairy, setShownFairy] = useState<FairyAgent | null>(null)
 
@@ -162,6 +164,8 @@ export function useFairySelection(agents: FairyAgent[]) {
 
 	const handleDoubleClickFairy = useCallback(
 		(clickedAgent: FairyAgent) => {
+			trackEvent('fairy-double-click', { source: 'fairy-sidebar', fairyId: clickedAgent.id })
+			trackEvent('fairy-zoom-to', { source: 'fairy-sidebar', fairyId: clickedAgent.id })
 			clickedAgent.positionManager.zoomTo()
 
 			// If the clicked fairy is part of an active project, select the orchestrator instead
@@ -179,13 +183,19 @@ export function useFairySelection(agents: FairyAgent[]) {
 
 			selectFairy(clickedAgent)
 		},
-		[selectFairy, agents]
+		[selectFairy, agents, trackEvent]
 	)
 
 	const handleToggleManual = useCallback(() => {
 		// Close manual if open, otherwise deselect all fairies
-		setManualOpen((prev) => !prev)
-	}, [])
+		const wasOpen = manualOpen
+		if (wasOpen) {
+			trackEvent('fairy-close-manual', { source: 'fairy-panel' })
+		} else {
+			trackEvent('fairy-switch-to-manual', { source: 'fairy-panel' })
+		}
+		setManualOpen(!wasOpen)
+	}, [trackEvent, manualOpen])
 
 	return {
 		panelState,