feat(analytics): instrument plan mode & Excalidraw sketch flows (#4862) (#5243)

* feat(analytics): instrument plan mode and Excalidraw sketch flows

Adds PostHog tracking for the two features shipped in #4862.

Plan mode: wire the (previously defined-but-never-called)
`trackComposerSessionModeClick` at the composer/home session-mode toggle
so switching into `plan` (and finally ask/design too) emits
`session_mode_toggle` with mode_before/mode_after. Run-level plan usage is
already covered via `session_mode='plan'` on run_created/run_finished.

Sketch: add `sketch_save_result` (explicit Save button, not autosave) and
`sketch_export_result` (PNG export written into the project — the sketch's
real output) to complete the flow that starts at `new_sketch`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(analytics): track open_sketch re-engagement entry

Per acceptance-doc review: add open_sketch (opening an existing sketch
from the Design Files list) alongside new_sketch. Keeps sketch_save_result
and the sketch_editor area per the same review; run-source attribution on
sketch export is deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: free666799 <293857035+free666799@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

apps/web/src/analytics/events.ts

@@ -120,6 +120,8 @@ import type {
   ContextLinkResultProps,
   ArtifactExportResultProps,
   ArtifactDeployResultProps,
+  SketchSaveResultProps,
+  SketchExportResultProps,
   FeedbackSubmitResultProps,
   SettingsViewProps,
   SettingsCliTestResultProps,
@@ -612,6 +614,20 @@ export function trackDesignToolboxClick(
   send(track, 'ui_click', props);
 }
 
+export function trackSketchSaveResult(
+  track: Track,
+  props: SketchSaveResultProps,
+): void {
+  send(track, 'sketch_save_result', props);
+}
+
+export function trackSketchExportResult(
+  track: Track,
+  props: SketchExportResultProps,
+): void {
+  send(track, 'sketch_export_result', props);
+}
+
 export function trackComposerBarClick(
   track: Track,
   props: ComposerBarClickProps,

apps/web/src/components/ChatComposer.tsx

@@ -23,6 +23,7 @@ import { useAnalytics } from '../analytics/provider';
 import {
   trackChatPanelClick,
   trackComposerBarClick,
+  trackComposerSessionModeClick,
   trackContextLinkResult,
   trackDesignToolboxClick,
   trackFigmaHelpModalSurfaceView,
@@ -33,6 +34,7 @@ import type {
   ComposerBarClickProps,
   DesignToolboxClickProps,
 } from '@open-design/contracts/analytics';
+import { sessionModeToTracking } from '@open-design/contracts/analytics';
 import { deriveUploadCohort } from '../analytics/upload-tracking';
 import { projectRawUrl, uploadProjectFiles, openFolderDialog, fetchRecentLinkedDirs, pushRecentLinkedDir, dirExists, applyLibraryAsset, fetchLibraryAssetElementHtml } from "../providers/registry";
 import { WorkingDirPicker } from './WorkingDirPicker';
@@ -3002,7 +3004,19 @@ export const ChatComposer = forwardRef<ChatComposerHandle, Props>(
             {footerAccessory}
             <SessionModeToggle
               mode={sessionMode}
-              onChange={onSessionModeChange}
+              onChange={(next) => {
+                if (next !== sessionMode) {
+                  trackComposerSessionModeClick(analytics.track, {
+                    page_name: 'chat_panel',
+                    area: 'chat_composer',
+                    element: 'session_mode_toggle',
+                    mode_before: sessionModeToTracking(sessionMode),
+                    mode_after: sessionModeToTracking(next),
+                    project_id: projectId ?? undefined,
+                  });
+                }
+                onSessionModeChange?.(next);
+              }}
             />
             {showStopButton ? (
               <button

apps/web/src/components/FileWorkspace.tsx

@@ -16,6 +16,8 @@ import {
   trackFileUploadResult,
   trackPageView,
   trackTabLauncherClick,
+  trackSketchSaveResult,
+  trackSketchExportResult,
 } from '../analytics/events';
 import { deriveUploadCohort } from '../analytics/upload-tracking';
 import { useT } from '../i18n';
@@ -2796,7 +2798,18 @@ export function FileWorkspace({
             onCurrentDirChange={setUploadDir}
             navState={designFilesNavRef.current}
             onNavStateChange={onDesignFilesNavStateChange}
-            onOpenFile={openFile}
+            onOpenFile={(name) => {
+              // Re-engagement entry: opening an existing sketch from the file
+              // list (new_sketch already covers fresh creation).
+              if (isSketchName(name)) {
+                trackFileManagerClick(analytics.track, {
+                  page_name: 'file_manager',
+                  area: 'file_manager',
+                  element: 'open_sketch',
+                });
+              }
+              openFile(name);
+            }}
             onOpenLiveArtifact={(tabId) => openFile(tabId)}
             onRenameFile={handleRename}
             onDeleteFile={(name) => {
@@ -2890,8 +2903,28 @@ export function FileWorkspace({
               }
               onSceneChange={(scene, options) => setSketchScene(activeFile.name, scene, options)}
               onClear={() => clearSketch(activeFile.name)}
-              onSave={(scene) => saveSketch(activeFile.name, scene)}
-              onExportImage={(base64, fileName) => exportSketchImage(activeFile.name, base64, fileName)}
+              onSave={async (scene) => {
+                // Fires only on the explicit "Save" button — background
+                // autosave calls saveSketch() directly and is not tracked.
+                const result = await saveSketch(activeFile.name, scene);
+                trackSketchSaveResult(analytics.track, {
+                  page_name: 'file_manager',
+                  area: 'sketch_editor',
+                  result: result === false ? 'failed' : 'success',
+                  project_id: projectId,
+                });
+                return result;
+              }}
+              onExportImage={async (base64, fileName) => {
+                const result = await exportSketchImage(activeFile.name, base64, fileName);
+                trackSketchExportResult(analytics.track, {
+                  page_name: 'file_manager',
+                  area: 'sketch_editor',
+                  result: result === false ? 'failed' : 'success',
+                  project_id: projectId,
+                });
+                return result;
+              }}
               onOpenExportedImage={openFile}
               saving={activeSketch.saving}
               dirty={activeSketch.dirty || !activeSketch.persisted}

apps/web/src/components/HomeHero.tsx

@@ -36,11 +36,13 @@ import type { SkillSummary } from '../types';
 import { Icon, type IconName } from './Icon';
 import { useAnalytics } from '../analytics/provider';
 import {
+  trackComposerSessionModeClick,
   trackContextLinkResult,
   trackFigmaHelpModalSurfaceView,
   trackHomeChatComposerClick,
   trackProjectReferenceModalSurfaceView,
 } from '../analytics/events';
+import { sessionModeToTracking } from '@open-design/contracts/analytics';
 import {
   chipsForGroup,
   orderedCreateChips,
@@ -1936,7 +1938,18 @@ export const HomeHero = forwardRef<HomeHeroHandle, Props>(function HomeHero(
             <div className="home-hero__mode-switcher">
               <SessionModeToggle
                 mode={sessionMode}
-                onChange={onSessionModeChange}
+                onChange={(next) => {
+                  if (next !== sessionMode) {
+                    trackComposerSessionModeClick(analytics.track, {
+                      page_name: 'home',
+                      area: 'chat_composer',
+                      element: 'session_mode_toggle',
+                      mode_before: sessionModeToTracking(sessionMode),
+                      mode_after: sessionModeToTracking(next),
+                    });
+                  }
+                  onSessionModeChange?.(next);
+                }}
               />
             </div>
             {executionSwitcher ? (

packages/contracts/src/analytics/events/event-names.ts

@@ -63,7 +63,10 @@ export type AnalyticsEventName =
   | 'design_system_status_result'
   | 'design_system_apply_result'
   // AI optimize (deep enrichment) of a programmatically-extracted DS.
-  | 'design_system_enrich_result';
+  | 'design_system_enrich_result'
+  // Manual save / PNG export from the Excalidraw sketch editor.
+  | 'sketch_save_result'
+  | 'sketch_export_result';
 
 // ---- Pages ---------------------------------------------------------------
 

packages/contracts/src/analytics/events/event-payload.ts

@@ -5,7 +5,7 @@
 import type { DesignSystemApplyResultProps, DesignSystemCreateResultProps, DesignSystemEnrichResultProps, DesignSystemReviewResultProps, DesignSystemSourceIngestResultProps, DesignSystemStatusResultProps } from './design-systems.js';
 import type { OnboardingCompleteResultProps, OnboardingRuntimeScanResultProps } from './onboarding.js';
 import type { PageViewProps } from './page-view.js';
-import type { ArtifactDeployResultProps, ArtifactExportResultProps, AssistantFeedbackClickProps, AssistantFeedbackReasonClickProps, AssistantFeedbackReasonSubmitProps, AssistantFeedbackReasonViewProps, ContextLinkResultProps, FeedbackSubmitResultProps, FileUploadResultProps, FileVersionRestoreResultProps, LangfuseReportResultProps, PackagedRuntimeFailedProps, PluginImportResultProps, PluginReplacementResultProps, ProjectCreateResultProps, RunCreatedProps, RunFinishedProps, RunRetryAttemptedProps, RunRetryFinishedProps, SettingsByokModelsFetchResultProps, SettingsByokTestResultProps, SettingsCliTestResultProps, SettingsConnectorAuthResultProps, SettingsViewProps, UpdateApplyObservedProps, UpdateInstallResultProps } from './result-events.js';
+import type { ArtifactDeployResultProps, ArtifactExportResultProps, AssistantFeedbackClickProps, AssistantFeedbackReasonClickProps, AssistantFeedbackReasonSubmitProps, AssistantFeedbackReasonViewProps, ContextLinkResultProps, FeedbackSubmitResultProps, FileUploadResultProps, FileVersionRestoreResultProps, LangfuseReportResultProps, PackagedRuntimeFailedProps, PluginImportResultProps, PluginReplacementResultProps, ProjectCreateResultProps, RunCreatedProps, RunFinishedProps, RunRetryAttemptedProps, RunRetryFinishedProps, SettingsByokModelsFetchResultProps, SettingsByokTestResultProps, SettingsCliTestResultProps, SettingsConnectorAuthResultProps, SettingsViewProps, SketchExportResultProps, SketchSaveResultProps, UpdateApplyObservedProps, UpdateInstallResultProps } from './result-events.js';
 import type { SurfaceViewProps } from './surface-view.js';
 import type { AmrAuthResultProps, UiClickProps } from './ui-click.js';
 // ---- Discriminated union of all event payloads ---------------------------
@@ -29,6 +29,8 @@ export type AnalyticsEventPayload =
   | { event: 'context_link_result'; props: ContextLinkResultProps }
   | { event: 'artifact_export_result'; props: ArtifactExportResultProps }
   | { event: 'artifact_deploy_result'; props: ArtifactDeployResultProps }
+  | { event: 'sketch_save_result'; props: SketchSaveResultProps }
+  | { event: 'sketch_export_result'; props: SketchExportResultProps }
   | { event: 'file_version_restore_result'; props: FileVersionRestoreResultProps }
   | { event: 'feedback_submit_result'; props: FeedbackSubmitResultProps }
   | { event: 'assistant_feedback_click'; props: AssistantFeedbackClickProps }

packages/contracts/src/analytics/events/result-events.ts

@@ -448,6 +448,32 @@ export interface ArtifactExportResultProps {
   project_kind: TrackingProjectKind | null;
 }
 
+// Fired when the user explicitly clicks "Save" in the Excalidraw sketch editor
+// — NOT the background autosave (which carries no user intent and is not
+// tracked). `result` is 'success' once the sketch file is persisted, 'failed'
+// on a write error. Together with `sketch_export_result` this is the
+// completion signal for the sketch flow that starts at `new_sketch`.
+export interface SketchSaveResultProps {
+  page_name: 'file_manager';
+  area: 'sketch_editor';
+  result: TrackingExportResult;
+  error_code?: string;
+  project_id: string;
+}
+
+// Fired when the user exports a sketch to a PNG from the sketch editor, which
+// writes the image into the project's files — the sketch's real "output" (the
+// drawing becomes a project asset that can then be attached to a run). This is
+// the strongest completion signal for the sketch flow. `result` is 'success'
+// once the PNG is written, 'failed' on a write error.
+export interface SketchExportResultProps {
+  page_name: 'file_manager';
+  area: 'sketch_editor';
+  result: TrackingExportResult;
+  error_code?: string;
+  project_id: string;
+}
+
 export type TrackingDeployProvider = 'vercel' | 'cloudflare_pages';
 
 // Fired from the deploy modal when a real publish attempt resolves — NOT when

packages/contracts/src/analytics/events/ui-click.ts

@@ -931,6 +931,10 @@ export interface FileManagerClickProps {
   area: 'file_manager';
   element:
     | 'new_sketch'
+    // Opening an existing .sketch.json from the Design Files list — the
+    // "come back to an earlier sketch" re-engagement entry (distinct from
+    // `new_sketch` which creates a fresh one).
+    | 'open_sketch'
     | 'new_browser'
     | 'create_design_system'
     | 'create_design_system_from_project'