@hyperframes/studio 0.6.29 → 0.6.30

package/src/styles/studio.css

@@ -152,6 +152,15 @@ body {
   background: rgba(255, 255, 255, 0.1);
 }
 
+@keyframes hf-thumb-fade {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
 .hf-loader-progress__fill {
   width: 100%;
   height: 100%;

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

package/src/telemetry/client.ts

@@ -0,0 +1,145 @@
+// ---------------------------------------------------------------------------
+// Lightweight PostHog client for the studio browser bundle.
+// Mirrors `packages/cli/src/telemetry/client.ts` but uses fetch/sendBeacon.
+// All calls are fire-and-forget; telemetry must never break the studio UI.
+// ---------------------------------------------------------------------------
+
+import { getAnonymousId, hasShownNotice, isOptedOut, markNoticeShown } from "./config";
+import { getBrowserSystemMeta } from "./system";
+
+// HeyGen's PostHog project key — write-only, safe to embed in client code.
+// OSS builds can override via `VITE_HYPERFRAMES_POSTHOG_KEY` at build time,
+// or set it to an empty string to disable telemetry entirely.
+const POSTHOG_API_KEY =
+  (import.meta.env.VITE_HYPERFRAMES_POSTHOG_KEY as string | undefined) ??
+  "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
+const POSTHOG_HOST =
+  (import.meta.env.VITE_HYPERFRAMES_POSTHOG_HOST as string | undefined) ??
+  "https://us.i.posthog.com";
+const FLUSH_INTERVAL_MS = 1_000;
+
+type EventProperties = Record<string, string | number | boolean | undefined>;
+
+interface QueuedEvent {
+  event: string;
+  properties: EventProperties;
+  timestamp: string;
+}
+
+let eventQueue: QueuedEvent[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+let telemetryEnabled: boolean | null = null;
+
+function isDoNotTrackOn(): boolean {
+  return typeof navigator !== "undefined" && navigator.doNotTrack === "1";
+}
+
+function isApiKeyConfigured(): boolean {
+  return POSTHOG_API_KEY.startsWith("phc_");
+}
+
+// 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() &&
+    !isBuildTimeOptOut() &&
+    !isViteDevMode() &&
+    !isOptedOut() &&
+    !isDoNotTrackOn();
+  return telemetryEnabled;
+}
+
+export function trackEvent(event: string, properties: EventProperties = {}): void {
+  if (!shouldTrack()) return;
+
+  const sys = getBrowserSystemMeta();
+  eventQueue.push({
+    event,
+    properties: { ...properties, ...sys },
+    timestamp: new Date().toISOString(),
+  });
+
+  if (flushTimer === null) {
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+  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();
+  const batch = eventQueue.map((e) => ({
+    event: e.event,
+    // $ip: null tells PostHog to not record the request IP.
+    properties: { ...e.properties, $ip: null },
+    distinct_id: distinctId,
+    timestamp: e.timestamp,
+  }));
+  eventQueue = [];
+  send(`${POSTHOG_HOST}/batch/`, JSON.stringify({ api_key: POSTHOG_API_KEY, batch }));
+}
+
+function send(url: string, payload: string): void {
+  // Prefer fetch with keepalive (survives page navigation). sendBeacon is a
+  // fallback for older runtimes where fetch isn't available.
+  try {
+    void fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload,
+      keepalive: true,
+    }).catch(() => {
+      /* silent */
+    });
+    return;
+  } catch {
+    /* fall through */
+  }
+  try {
+    navigator.sendBeacon(url, new Blob([payload], { type: "application/json" }));
+  } catch {
+    /* silent */
+  }
+}
+
+function showNoticeOnce(): void {
+  if (hasShownNotice()) return;
+  markNoticeShown();
+  // eslint-disable-next-line no-console
+  console.info(
+    "%c[HyperFrames]%c Anonymous studio usage analytics enabled. " +
+      "Disable: localStorage.setItem('hyperframes-studio:telemetryDisabled','1') (then reload).",
+    "color:#7c3aed;font-weight:bold",
+    "color:inherit",
+  );
+}
+
+// Flush queued events when the tab is being hidden or closed so tail events
+// (e.g. a render_start fired moments before the user navigates away) aren't lost.
+if (typeof window !== "undefined") {
+  window.addEventListener("pagehide", () => flush(), { capture: true });
+  window.addEventListener("visibilitychange", () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") flush();
+  });
+}

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