test+fix(telemetry): address PR review — dev-mode gate, session-storage dedupe, payload tests

Addresses review comments on #982:

- studio shouldTrack(): adds VITE_HYPERFRAMES_NO_TELEMETRY (mirrors CLI's
  HYPERFRAMES_NO_TELEMETRY) and import.meta.env.DEV gates so dev / CI
  studio builds don't pollute production telemetry. shouldTrack() is now
  exported for testability.
- App.tsx session dedupe: moves the once-per-session check from a useRef
  (which resets on HMR / remount) to sessionStorage via new
  hasFiredSessionStart / markSessionStartFired helpers in config.ts.
- studioRenderTelemetry.ts: documents why `workers` is intentionally
  omitted from emitStudioRenderError (studio renders don't accept a
  user-supplied worker count, so early failures genuinely don't know one).
- client.ts flush(): documents fire-and-forget no-retry design so future
  hands don't accidentally add retry logic that double-counts.

Tests:
- studioRenderTelemetry.test.ts (8 tests): perfPayload mapping for every
  RenderPerfSummary field, undefined-perf path, missing-extract path,
  zero-elapsed edge case, error event shape.
- studio/telemetry/events.test.ts (4 tests): pin event names
  (studio_session_start, studio_render_start) and payload shape.
- studio/telemetry/client.test.ts (9 tests): shouldTrack() returns false
  for non-phc_ key, opt-out, doNotTrack, build-time env, vite dev mode;
  memoization.

packages/studio/src/App.tsx

@@ -48,19 +48,20 @@ import {
   readStudioUrlStateFromWindow,
 } from "./utils/studioUrlState";
 import { trackStudioSessionStart } from "./telemetry/events";
+import { hasFiredSessionStart, markSessionStartFired } from "./telemetry/config";
 
 export function StudioApp() {
   const { projectId, resolving, waitingForServer } = useServerConnection();
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
 
-  // Fire once per browser session to mark a "studio open" event so we can
-  // separate studio sessions from CLI invocations in product analytics.
-  // `has_project` lets us tell scratch-open from project-context-open.
-  const sessionFiredRef = useRef(false);
+  // Fire once per browser tab session — sessionStorage-backed so HMR
+  // remounts, route changes, and any future StudioApp remount within the
+  // same tab don't refire `studio_session_start`. `has_project` lets us
+  // tell scratch-open from project-context-open.
   useEffect(() => {
-    if (sessionFiredRef.current) return;
     if (resolving || waitingForServer) return;
-    sessionFiredRef.current = true;
+    if (hasFiredSessionStart()) return;
+    markSessionStartFired();
     trackStudioSessionStart({ has_project: projectId != null });
   }, [projectId, resolving, waitingForServer]);
 

packages/studio/src/telemetry/client.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// `shouldTrack()` reads `POSTHOG_API_KEY` from module-level const that's
+// evaluated at module load time, so changing `import.meta.env` after import
+// has no effect on the key. Each test resets module cache and re-imports.
+
+const OPT_OUT_KEY = "hyperframes-studio:telemetryDisabled";
+
+function setKey(value: string | undefined): void {
+  if (value === undefined) {
+    delete (import.meta.env as Record<string, unknown>).VITE_HYPERFRAMES_POSTHOG_KEY;
+  } else {
+    (import.meta.env as Record<string, unknown>).VITE_HYPERFRAMES_POSTHOG_KEY = value;
+  }
+}
+
+function setNoTelemetry(value: string | undefined): void {
+  if (value === undefined) {
+    delete (import.meta.env as Record<string, unknown>).VITE_HYPERFRAMES_NO_TELEMETRY;
+  } else {
+    (import.meta.env as Record<string, unknown>).VITE_HYPERFRAMES_NO_TELEMETRY = value;
+  }
+}
+
+function setDev(value: boolean): void {
+  (import.meta.env as { DEV: boolean }).DEV = value;
+}
+
+async function loadShouldTrack(): Promise<() => boolean> {
+  vi.resetModules();
+  const mod = await import("./client");
+  return mod.shouldTrack;
+}
+
+describe("studio client shouldTrack", () => {
+  beforeEach(() => {
+    setDev(false);
+    setKey("phc_test_key");
+    setNoTelemetry(undefined);
+    localStorage.clear();
+    vi.unstubAllGlobals();
+  });
+
+  it("returns true when key is configured, not in dev mode, and no opt-outs", async () => {
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(true);
+  });
+
+  it("returns false when API key does not start with phc_", async () => {
+    setKey("not_a_real_key");
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("returns false when API key is empty string", async () => {
+    setKey("");
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("returns false when user has opted out via localStorage", async () => {
+    localStorage.setItem(OPT_OUT_KEY, "1");
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("returns false when navigator.doNotTrack is '1'", async () => {
+    vi.stubGlobal("navigator", { ...navigator, doNotTrack: "1" });
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("returns false when VITE_HYPERFRAMES_NO_TELEMETRY=1 at build time", async () => {
+    setNoTelemetry("1");
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("returns false when VITE_HYPERFRAMES_NO_TELEMETRY='true'", async () => {
+    setNoTelemetry("true");
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("returns false in vite dev mode", async () => {
+    setDev(true);
+    const shouldTrack = await loadShouldTrack();
+    expect(shouldTrack()).toBe(false);
+  });
+
+  it("memoizes its decision after the first call", async () => {
+    const shouldTrack = await loadShouldTrack();
+    const first = shouldTrack();
+    // Flip an underlying input — memoized return must not change.
+    localStorage.setItem(OPT_OUT_KEY, "1");
+    expect(shouldTrack()).toBe(first);
+  });
+});

packages/studio/src/telemetry/client.ts

@@ -38,9 +38,28 @@ function isApiKeyConfigured(): boolean {
   return POSTHOG_API_KEY.startsWith("phc_");
 }
 
-function shouldTrack(): boolean {
+// VITE_HYPERFRAMES_NO_TELEMETRY mirrors the CLI's HYPERFRAMES_NO_TELEMETRY=1
+// opt-out so HeyGen's own dev/CI builds can suppress telemetry from the studio
+// bundle the same way. Vite injects it at build time. Accepts "1" or "true".
+function isBuildTimeOptOut(): boolean {
+  const v = import.meta.env.VITE_HYPERFRAMES_NO_TELEMETRY as string | undefined;
+  return v === "1" || v === "true";
+}
+
+// `import.meta.env.DEV` is true under `vite dev` / `vite preview`. Auto-suppress
+// so developers running `hyperframes preview` don't pollute production telemetry.
+function isViteDevMode(): boolean {
+  return import.meta.env.DEV === true;
+}
+
+export function shouldTrack(): boolean {
   if (telemetryEnabled !== null) return telemetryEnabled;
-  telemetryEnabled = isApiKeyConfigured() && !isOptedOut() && !isDoNotTrackOn();
+  telemetryEnabled =
+    isApiKeyConfigured() &&
+    !isBuildTimeOptOut() &&
+    !isViteDevMode() &&
+    !isOptedOut() &&
+    !isDoNotTrackOn();
   return telemetryEnabled;
 }
 
@@ -63,6 +82,10 @@ export function trackEvent(event: string, properties: EventProperties = {}): voi
   showNoticeOnce();
 }
 
+// Fire-and-forget: the queue is cleared before `send()` resolves, so a network
+// failure drops the batch rather than retrying. Matches the CLI client's
+// design. Do NOT add retry logic here — a retry without cross-batch dedup
+// would risk double-counting events on transient PostHog 5xx responses.
 function flush(): void {
   if (eventQueue.length === 0) return;
   const distinctId = getAnonymousId();

packages/studio/src/telemetry/config.ts

@@ -51,3 +51,28 @@ export function markNoticeShown(): void {
     /* ignore */
   }
 }
+
+// Session-scoped (cleared when the tab closes) so HMR remounts and
+// route-level remounts within one tab don't refire `studio_session_start`.
+// Uses sessionStorage directly because the dedupe is per-tab, not per-browser.
+const SESSION_FIRED_KEY = "hyperframes-studio:sessionStartFired";
+
+function safeSessionStorage(): Storage | null {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function hasFiredSessionStart(): boolean {
+  return safeSessionStorage()?.getItem(SESSION_FIRED_KEY) === "1";
+}
+
+export function markSessionStartFired(): void {
+  try {
+    safeSessionStorage()?.setItem(SESSION_FIRED_KEY, "1");
+  } catch {
+    /* ignore */
+  }
+}

packages/studio/src/telemetry/events.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// Mock client.trackEvent so we can assert event names and payloads without
+// firing network requests or relying on memoized shouldTrack() state.
+const trackEvent = vi.fn();
+vi.mock("./client", () => ({
+  trackEvent: (...args: unknown[]) => trackEvent(...args),
+}));
+
+const { trackStudioSessionStart, trackStudioRenderStart } = await import("./events");
+
+describe("studio telemetry events", () => {
+  beforeEach(() => {
+    trackEvent.mockClear();
+  });
+
+  it("trackStudioSessionStart emits 'studio_session_start' with has_project", () => {
+    trackStudioSessionStart({ has_project: true });
+    expect(trackEvent).toHaveBeenCalledOnce();
+    expect(trackEvent).toHaveBeenCalledWith("studio_session_start", { has_project: true });
+  });
+
+  it("trackStudioSessionStart preserves false for has_project (scratch open)", () => {
+    trackStudioSessionStart({ has_project: false });
+    expect(trackEvent).toHaveBeenCalledWith("studio_session_start", { has_project: false });
+  });
+
+  it("trackStudioRenderStart emits 'studio_render_start' with all render opts", () => {
+    trackStudioRenderStart({
+      fps: 30,
+      quality: "standard",
+      format: "mp4",
+      resolution: "landscape",
+      composition: "intro.html",
+    });
+    expect(trackEvent).toHaveBeenCalledOnce();
+    expect(trackEvent).toHaveBeenCalledWith("studio_render_start", {
+      fps: 30,
+      quality: "standard",
+      format: "mp4",
+      resolution: "landscape",
+      composition: "intro.html",
+    });
+  });
+
+  it("trackStudioRenderStart leaves optional fields undefined when omitted", () => {
+    trackStudioRenderStart({ fps: 60, quality: "high", format: "webm" });
+    const payload = trackEvent.mock.calls[0][1];
+    expect(payload).toEqual({
+      fps: 60,
+      quality: "high",
+      format: "webm",
+      resolution: undefined,
+      composition: undefined,
+    });
+  });
+});