@hyperframes/studio 0.6.29 → 0.6.31

package/src/telemetry/config.ts

@@ -0,0 +1,78 @@
+// ---------------------------------------------------------------------------
+// LocalStorage-backed config for studio telemetry.
+// Anonymous ID + opt-out flag are stored per-browser-profile.
+// Users opt out via DevTools:
+//   localStorage.setItem('hyperframes-studio:telemetryDisabled','1')
+// ---------------------------------------------------------------------------
+
+const ANON_ID_KEY = "hyperframes-studio:anonymousId";
+const OPT_OUT_KEY = "hyperframes-studio:telemetryDisabled";
+const NOTICE_KEY = "hyperframes-studio:telemetryNoticeShown";
+
+function safeLocalStorage(): Storage | null {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function newAnonymousId(): string {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
+  return `anon-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function getAnonymousId(): string {
+  const ls = safeLocalStorage();
+  if (!ls) return "anonymous";
+  const existing = ls.getItem(ANON_ID_KEY);
+  if (existing) return existing;
+  const id = newAnonymousId();
+  try {
+    ls.setItem(ANON_ID_KEY, id);
+  } catch {
+    /* private browsing / quota — return the in-memory ID for this session */
+  }
+  return id;
+}
+
+export function isOptedOut(): boolean {
+  return safeLocalStorage()?.getItem(OPT_OUT_KEY) === "1";
+}
+
+export function hasShownNotice(): boolean {
+  return safeLocalStorage()?.getItem(NOTICE_KEY) === "1";
+}
+
+export function markNoticeShown(): void {
+  try {
+    safeLocalStorage()?.setItem(NOTICE_KEY, "1");
+  } catch {
+    /* 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 */
+  }
+}

package/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,
+    });
+  });
+});

package/src/telemetry/events.ts

@@ -0,0 +1,27 @@
+import { trackEvent } from "./client";
+
+// Studio frontend events. The corresponding `render_complete` / `render_error`
+// events are emitted server-side by `packages/cli/src/server/studioServer.ts`
+// with `source: "studio"` — keeping rich perf data on a single unified event.
+
+export function trackStudioSessionStart(props: { has_project: boolean }): void {
+  trackEvent("studio_session_start", {
+    has_project: props.has_project,
+  });
+}
+
+export function trackStudioRenderStart(props: {
+  fps: number;
+  quality: string;
+  format: string;
+  resolution?: string;
+  composition?: string;
+}): void {
+  trackEvent("studio_render_start", {
+    fps: props.fps,
+    quality: props.quality,
+    format: props.format,
+    resolution: props.resolution,
+    composition: props.composition,
+  });
+}

package/src/telemetry/system.ts

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// Browser metadata attached to every studio telemetry event.
+// Mirrors `packages/cli/src/telemetry/system.ts` but uses browser APIs.
+// No PII — only environment characteristics useful for product analytics.
+// ---------------------------------------------------------------------------
+
+export interface BrowserSystemMeta {
+  user_agent: string;
+  language: string;
+  screen_width: number;
+  screen_height: number;
+  device_pixel_ratio: number;
+  timezone_offset_minutes: number;
+  is_mobile: boolean;
+}
+
+const EMPTY_META: BrowserSystemMeta = {
+  user_agent: "",
+  language: "",
+  screen_width: 0,
+  screen_height: 0,
+  device_pixel_ratio: 0,
+  timezone_offset_minutes: 0,
+  is_mobile: false,
+};
+
+let cached: BrowserSystemMeta | null = null;
+
+export function getBrowserSystemMeta(): BrowserSystemMeta {
+  if (cached) return cached;
+  // SSR / no-DOM: return zeroed meta. Cheap to detect once at module load.
+  if (typeof navigator === "undefined" || typeof window === "undefined") {
+    cached = EMPTY_META;
+    return cached;
+  }
+  const ua = navigator.userAgent;
+  const screen = window.screen;
+  cached = {
+    user_agent: ua,
+    language: navigator.language,
+    screen_width: screen.width,
+    screen_height: screen.height,
+    device_pixel_ratio: window.devicePixelRatio,
+    timezone_offset_minutes: new Date().getTimezoneOffset(),
+    is_mobile: /Android|iPhone|iPad/i.test(ua),
+  };
+  return cached;
+}

package/src/utils/studioTelemetry.ts

@@ -0,0 +1,128 @@
+// PostHog public ingest key — write-only, safe to ship in the client bundle
+const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+const FLUSH_INTERVAL_MS = 30_000;
+const FLUSH_TIMEOUT_MS = 5_000;
+
+interface EventProperties {
+  [key: string]: string | number | boolean | null | undefined;
+}
+
+interface QueuedEvent {
+  event: string;
+  properties: EventProperties;
+  timestamp: string;
+}
+
+let queue: QueuedEvent[] = [];
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+let distinctId: string | null = null;
+
+function getDistinctId(): string {
+  if (distinctId) return distinctId;
+  try {
+    const stored = localStorage.getItem("hf-studio-anon-id");
+    if (stored) {
+      distinctId = stored;
+      return stored;
+    }
+  } catch {
+    // localStorage may be unavailable
+  }
+  distinctId = crypto.randomUUID();
+  try {
+    localStorage.setItem("hf-studio-anon-id", distinctId);
+  } catch {
+    // best-effort persistence
+  }
+  return distinctId;
+}
+
+function isEnabled(): boolean {
+  try {
+    return localStorage.getItem("hf-studio-telemetry-opt-out") !== "1";
+  } catch {
+    return true;
+  }
+}
+
+function getSessionProperties(): EventProperties {
+  return {
+    studio_version: typeof __STUDIO_VERSION__ !== "undefined" ? __STUDIO_VERSION__ : "dev",
+    screen_width: window.screen?.width,
+    screen_height: window.screen?.height,
+    viewport_width: window.innerWidth,
+    viewport_height: window.innerHeight,
+    user_agent: navigator.userAgent,
+    url_hash: location.hash.replace(/#project\//, ""),
+  };
+}
+
+declare const __STUDIO_VERSION__: string;
+
+export function trackStudioEvent(event: string, properties: EventProperties = {}): void {
+  if (!isEnabled()) return;
+
+  queue.push({
+    event: `studio:${event}`,
+    properties: { ...getSessionProperties(), ...properties },
+    timestamp: new Date().toISOString(),
+  });
+
+  if (!flushTimer) {
+    flushTimer = setInterval(flushEvents, FLUSH_INTERVAL_MS);
+  }
+}
+
+async function flushEvents(): Promise<void> {
+  if (queue.length === 0) return;
+
+  const batch = queue.map((e) => ({
+    event: e.event,
+    properties: { ...e.properties, $ip: null },
+    distinct_id: getDistinctId(),
+    timestamp: e.timestamp,
+  }));
+  queue = [];
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FLUSH_TIMEOUT_MS);
+
+  try {
+    await fetch(`${POSTHOG_HOST}/batch/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ api_key: POSTHOG_API_KEY, batch }),
+      signal: controller.signal,
+    });
+  } catch {
+    // Telemetry must never break the studio
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+if (typeof window !== "undefined") {
+  window.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") {
+      if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+      }
+      if (queue.length === 0) return;
+      const batch = queue.map((e) => ({
+        event: e.event,
+        properties: { ...e.properties, $ip: null },
+        distinct_id: getDistinctId(),
+        timestamp: e.timestamp,
+      }));
+      queue = [];
+      const body = JSON.stringify({ api_key: POSTHOG_API_KEY, batch });
+      try {
+        navigator.sendBeacon(`${POSTHOG_HOST}/batch/`, body);
+      } catch {
+        // best-effort
+      }
+    }
+  });
+}