@hyperframes/studio 0.7.89 → 0.7.92

package/src/telemetry/canary.ts

@@ -0,0 +1,268 @@
+// ---------------------------------------------------------------------------
+// Studio (browser) binding for the shared canary registry.
+//
+// `@hyperframes/core` owns the decision and is deliberately pure — the caller
+// supplies the unit id, the override and the exclusion. This file supplies
+// those three from the browser, mirroring `packages/cli/src/telemetry/canary.ts`
+// for the CLI. The public API is deliberately identical on both surfaces:
+//
+//   import { isCanaryEnabled } from "../telemetry/canary";
+//   if (isCanaryEnabled("my-feature")) { ... }
+//
+// so a call site reads the same whether it runs in Node or the browser, and a
+// canary can span both.
+//
+// Three things differ from the CLI, each for a reason:
+//
+// 1. UNIT ID — the CLI's bucket seed (`window.__HF_CLI_BUCKET_SEED`) when the
+//    CLI launched Studio, so both surfaces bucket on the SAME unit and a
+//    rollout spanning render and editor is coherent for that user. Standalone
+//    Studio falls back to `resolveStudioDistinctId()` — the browser has no
+//    second storage location, so its localStorage id doubles as the seed.
+//
+// 2. OVERRIDE — there is no `process.env` in a page, so the override is a URL
+//    query param mirrored into sessionStorage (see `readOverride`).
+//
+// 3. EXCLUSION — `navigator.webdriver` stands in for the CLI's `is_ci`.
+//    Automated browsers mint a fresh localStorage id per run, so their ids are
+//    ephemeral and they would hop cohorts between runs — noise in the rollout
+//    signal, and nothing learned about real users.
+// ---------------------------------------------------------------------------
+
+// Deep subpath imports, NOT the "@hyperframes/core" barrel. Studio is a
+// browser bundle, and the barrel re-exports the whole core surface (parsers,
+// lint, studio-server); pulling that in here drags a Node-oriented dependency
+// graph into the bundle. These two modules are pure and leaf.
+import {
+  canaryFeatureProperties,
+  evaluateCanary,
+  parseCanaryOverride,
+  type CanaryDecision,
+} from "@hyperframes/core/canary";
+import { CANARIES, findCanary } from "@hyperframes/core/canary-registry";
+import { resolveStudioDistinctId } from "./distinctId";
+import { browserTelemetryAllowed } from "./policy";
+import { safeSessionStorage } from "../utils/safeStorage";
+
+/** `my-feature` → `hf_canary_my_feature`, the query param and storage key. */
+export function canaryParamName(name: string): string {
+  return `hf_canary_${name.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
+}
+
+// Injected by the CLI's studio server alongside __HF_CLI_DISTINCT_ID.
+declare global {
+  interface Window {
+    __HF_CLI_BUCKET_SEED?: string;
+    /**
+     * Resolved per-canary outcome from the launching CLI. `forced` marks an
+     * explicit `HF_CANARY_*` override as opposed to a percentage roll — the
+     * two get different precedence against Studio's own opt-out.
+     */
+    __HF_CLI_CANARY_DECISIONS?: Record<string, { enabled?: boolean; forced?: boolean }>;
+  }
+}
+
+/**
+ * The launching CLI's decision for this canary, if it published one.
+ *
+ * When present this WINS over everything Studio could work out locally —
+ * seed, URL override, registry percentage. Studio re-deriving cannot agree
+ * with the CLI in the cases that matter most:
+ *
+ *   - telemetry off: the CLI resolves `telemetry_opt_out`, but Studio's
+ *     opt-out is a separate localStorage flag it cannot see from here;
+ *   - `HF_CANARY_*` override: env vars never cross into the browser;
+ *   - no seed injected: Studio falls back to a different unit, i.e. a
+ *     different bucket.
+ *
+ * In all three the CLI has already decided, and one render spanning both
+ * surfaces must not run half-enrolled.
+ */
+function cliDecision(name: string): { enabled: boolean; forced: boolean } | undefined {
+  try {
+    if (typeof window === "undefined") return undefined;
+    const decision = window.__HF_CLI_CANARY_DECISIONS?.[name];
+    if (typeof decision?.enabled !== "boolean") return undefined;
+    return { enabled: decision.enabled, forced: decision.forced === true };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The bucketing unit. A CLI-launched Studio buckets on the CLI's SEED (which
+ * survives config wipes via the install-state file), not its distinct id —
+ * the CLI itself buckets on the seed, and the two surfaces must agree per
+ * machine. Standalone Studio falls back to its own distinct id: the browser
+ * has no second storage location, so localStorage IS both id and seed there.
+ */
+function resolveBucketUnit(): string {
+  try {
+    const seed = typeof window === "undefined" ? undefined : window.__HF_CLI_BUCKET_SEED;
+    if (typeof seed === "string" && seed.length > 0) return seed;
+  } catch {
+    /* fall through */
+  }
+  return resolveStudioDistinctId();
+}
+
+const STORAGE_PREFIX = "hyperframes-studio:canary:";
+
+/**
+ * Resolve a manual override for one canary.
+ *
+ * `?hf_canary_my_feature=on` (also off/true/false/1/0/yes/no), mirrored into
+ * sessionStorage so it survives in-app navigation and reloads within the tab.
+ *
+ * SESSION scope, not local, is the deliberate part. A URL is the right carrier
+ * — it is shareable, which is what "support: open this link" and "QA: repro
+ * with this on" actually need. But persisting a URL-borne override to
+ * localStorage would mean one click silently pins that browser into a cohort
+ * forever, long after anyone remembers why. Session scope keeps the link
+ * useful and lets closing the tab be the reset.
+ *
+ * `?hf_canary_my_feature=reset` clears it explicitly.
+ */
+function readOverride(name: string): boolean | undefined {
+  if (typeof window === "undefined") return undefined;
+  const key = canaryParamName(name);
+  const storageKey = `${STORAGE_PREFIX}${name}`;
+  const store = safeSessionStorage();
+
+  let raw: string | null = null;
+  try {
+    raw = new URLSearchParams(window.location.search).get(key);
+  } catch {
+    raw = null;
+  }
+
+  if (raw !== null) {
+    if (raw.trim().toLowerCase() === "reset") {
+      store?.removeItem(storageKey);
+      return undefined;
+    }
+    // Persist for the tab session so the override outlives the query string.
+    try {
+      store?.setItem(storageKey, raw);
+    } catch {
+      /* storage full / blocked — the param still applies to this page load */
+    }
+    return parseCanaryOverride(raw);
+  }
+
+  return parseCanaryOverride(store?.getItem(storageKey) ?? undefined);
+}
+
+/**
+ * Automated browser? The browser analog of the CLI's CI exclusion.
+ * `navigator.webdriver` is set by Playwright, Puppeteer and Selenium.
+ */
+function isAutomatedBrowser(): boolean {
+  if (typeof navigator === "undefined") return false;
+  return navigator.webdriver === true;
+}
+
+/**
+ * Memoized per page load, for the same reason the CLI memoizes per process: a
+ * canary must not change its mind mid-session. A component that mounted
+ * enrolled has to stay enrolled, and the telemetry has to agree with what the
+ * user actually saw.
+ */
+const decisions = new Map<string, CanaryDecision>();
+
+/** Test-only: drop memoized decisions so cases don't leak into each other. */
+export function __resetStudioCanaryCacheForTests(): void {
+  decisions.clear();
+}
+
+/** The uncached decision. Split out so `resolveCanary` is purely the memo. */
+const forcedOutcome = (enabled: boolean): CanaryDecision => ({
+  enabled,
+  reason: enabled ? "forced_on" : "forced_off",
+});
+
+const cohortOutcome = (enabled: boolean): CanaryDecision => ({
+  enabled,
+  reason: enabled ? "in_cohort" : "out_of_cohort",
+});
+
+/**
+ * Precedence, highest first:
+ *
+ *   1. An explicit `HF_CANARY_*` from the launching CLI. A deliberate operator
+ *      choice — the documented escalation channel (dogfooding, bisect,
+ *      panic-off) — so it wins outright, including over this profile's
+ *      opt-out, exactly as a local URL override does.
+ *   2. A local URL / sessionStorage override, same reasoning.
+ *   3. This profile's telemetry opt-out. Checked BEFORE any percentage-derived
+ *      CLI decision: the two surfaces have independent opt-outs, and CLI
+ *      telemetry being on says nothing about whether THIS browser profile
+ *      agreed to be measured. A cohort roll must never enrol an opted-out
+ *      profile.
+ *   4. The CLI's percentage decision — authoritative, since it already applied
+ *      the shared seed and re-deriving is what let the surfaces disagree.
+ *   5. Local evaluation (standalone Studio, or a canary the CLI didn't publish).
+ */
+function decideStudioCanary(name: string): CanaryDecision {
+  const definition = findCanary(name);
+  if (!definition) return { enabled: false, reason: "out_of_cohort" };
+
+  const fromCli = cliDecision(definition.name);
+  if (fromCli?.forced) return forcedOutcome(fromCli.enabled);
+
+  const override = readOverride(definition.name);
+  if (override === undefined) {
+    if (!browserTelemetryAllowed()) return { enabled: false, reason: "telemetry_opt_out" };
+    // Studio's exclusion is its own to apply: the CLI cannot see
+    // navigator.webdriver, so adopting its cohort decision verbatim enrolled
+    // Playwright/Puppeteer sessions driving a local `hyperframes preview` —
+    // each minting a fresh localStorage id, precisely the ephemeral-id noise
+    // the exclusion exists to keep out of the rollout signal.
+    if (isAutomatedBrowser()) return { enabled: false, reason: "excluded" };
+    if (fromCli !== undefined) return cohortOutcome(fromCli.enabled);
+  }
+
+  // An explicit override decides on evaluateCanary's first line without ever
+  // reading unitId, so resolving the unit here would mint and PERSIST an
+  // anonymous id purely as an unused argument — for a profile that may have
+  // opted out. One click on a support link created a durable tracking id.
+  if (override !== undefined) return forcedOutcome(override);
+
+  return evaluateCanary({
+    feature: definition.name,
+    unitId: resolveBucketUnit(),
+    percentage: definition.percentage,
+    exclude: isAutomatedBrowser(),
+  });
+}
+
+/**
+ * Full decision including the reason. An unregistered name resolves to off
+ * rather than throwing — a typo in a rollout control must never break the
+ * editor.
+ */
+export function resolveCanary(name: string): CanaryDecision {
+  const cached = decisions.get(name);
+  if (cached) return cached;
+
+  const decision = decideStudioCanary(name);
+
+  decisions.set(name, decision);
+  return decision;
+}
+
+/** Is this canary on for this Studio install? The everyday call. */
+export function isCanaryEnabled(name: string): boolean {
+  return resolveCanary(name).enabled;
+}
+
+/**
+ * Canary assignments as PostHog flag properties (`$feature/canary-<name>`),
+ * attached to every Studio event so any metric can be split by cohort —
+ * identical shape to the CLI, so a rollout spanning both reads as one flag.
+ */
+export function canaryEventProperties(): Record<string, string> {
+  return canaryFeatureProperties(
+    CANARIES.map((c) => ({ name: c.name, enabled: resolveCanary(c.name).enabled })),
+  );
+}

package/src/telemetry/client.test.ts

@@ -77,10 +77,15 @@ describe("studio client shouldTrack", () => {
     expect(shouldTrack()).toBe(false);
   });
 
-  it("memoizes its decision after the first call", async () => {
+  // Previously asserted the opposite. That memoization WAS the bug: policy.ts
+  // is explicit that transports re-ask, and policy.test.ts asserts a
+  // mid-session opt-out takes effect at once — but this transport cached on
+  // first call, so a user who opted out in DevTools after one event kept
+  // sending `studio_*` and render events while `studio:*` correctly stopped.
+  it("re-reads the policy, so a mid-session opt-out takes effect immediately", async () => {
     const shouldTrack = await loadShouldTrack();
-    const first = shouldTrack();
+    expect(shouldTrack()).toBe(true);
     localStorage.setItem(OPT_OUT_KEY, "1");
-    expect(shouldTrack()).toBe(first);
+    expect(shouldTrack()).toBe(false);
   });
 });

package/src/telemetry/client.ts

@@ -4,8 +4,10 @@
 // All calls are fire-and-forget; telemetry must never break the studio UI.
 // ---------------------------------------------------------------------------
 
-import { getAnonymousId, hasShownNotice, isOptedOut, markNoticeShown } from "./config";
+import { getAnonymousId, hasShownNotice, markNoticeShown } from "./config";
+import { browserTelemetryAllowed } from "./policy";
 import { getBrowserSystemMeta } from "./system";
+import { canaryEventProperties } from "./canary";
 
 // Write-only PostHog project key, safe to embed in client code.
 const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
@@ -22,49 +24,14 @@ interface QueuedEvent {
 
 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. Match the CLI's
-// affirmative privacy-control spellings.
-// `import.meta.env` may be undefined in non-Vite bundlers (Next.js Turbopack).
-function isBuildTimeOptOut(): boolean {
-  try {
-    const v = import.meta.env.VITE_HYPERFRAMES_NO_TELEMETRY as string | undefined;
-    return v !== undefined && ["1", "true", "yes", "on"].includes(v.trim().toLowerCase());
-  } catch {
-    return false;
-  }
-}
-
-// `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 {
-  try {
-    return import.meta.env.DEV === true;
-  } catch {
-    return false;
-  }
-}
 
 export function shouldTrack(): boolean {
-  if (telemetryEnabled !== null) return telemetryEnabled;
-  telemetryEnabled =
-    isApiKeyConfigured() &&
-    !isBuildTimeOptOut() &&
-    !isViteDevMode() &&
-    !isOptedOut() &&
-    !isDoNotTrackOn();
-  return telemetryEnabled;
+  // NOT memoized. policy.ts is explicit that the transports re-ask, and
+  // policy.test.ts asserts a mid-session opt-out takes effect at once — but
+  // this cached on first call, so a user who opted out in DevTools after one
+  // event kept sending `studio_*` and render events for the rest of the tab
+  // while `studio:*` correctly stopped. The check is two property reads.
+  return browserTelemetryAllowed();
 }
 
 export function trackEvent(event: string, properties: EventProperties = {}): void {
@@ -73,7 +40,10 @@ export function trackEvent(event: string, properties: EventProperties = {}): voi
   const sys = getBrowserSystemMeta();
   eventQueue.push({
     event,
-    properties: { ...properties, ...sys },
+    // Canary assignments as `$feature/canary-<name>`, mirroring the CLI so a
+    // rollout spanning both surfaces reads as one flag in PostHog. Resolved
+    // after the shouldTrack guard, so opted-out users never pay for it.
+    properties: { ...properties, ...sys, ...canaryEventProperties() },
     timestamp: new Date().toISOString(),
   });
 

package/src/telemetry/config.ts

@@ -22,12 +22,26 @@ export function getAnonymousId(): string {
   return resolveStudioDistinctId();
 }
 
+// safeLocalStorage() guards the REFERENCE, not the access: in a partitioned
+// or sandboxed context the object resolves and `getItem` still throws (the
+// case distinctId.ts already documents). These are read from the telemetry
+// policy, which is called from event tracking that must never throw into a
+// caller — `trackStudioEvent` sits in a post-commit catch block, so a throw
+// there reported an already-committed edit as failed.
+function readStoredFlag(key: string): boolean {
+  try {
+    return safeLocalStorage()?.getItem(key) === "1";
+  } catch {
+    return false;
+  }
+}
+
 export function isOptedOut(): boolean {
-  return safeLocalStorage()?.getItem(OPT_OUT_KEY) === "1";
+  return readStoredFlag(OPT_OUT_KEY);
 }
 
 export function hasShownNotice(): boolean {
-  return safeLocalStorage()?.getItem(NOTICE_KEY) === "1";
+  return readStoredFlag(NOTICE_KEY);
 }
 
 export function markNoticeShown(): void {

package/src/telemetry/distinctId.test.ts

@@ -101,3 +101,38 @@ describe("getCliDistinctId", () => {
     expect(getCliDistinctId()).toBeNull();
   });
 });
+
+describe("no-storage fallback must not collapse the population", () => {
+  const realLocalStorage = Object.getOwnPropertyDescriptor(globalThis, "localStorage");
+
+  beforeEach(() => {
+    __resetStudioDistinctIdForTests();
+    // Simulate a hardened / partitioned context where safeLocalStorage()
+    // returns null.
+    Object.defineProperty(globalThis, "localStorage", { value: undefined, configurable: true });
+  });
+
+  afterEach(() => {
+    if (realLocalStorage) Object.defineProperty(globalThis, "localStorage", realLocalStorage);
+    __resetStudioDistinctIdForTests();
+  });
+
+  it("is stable within a session", () => {
+    const first = resolveStudioDistinctId();
+    expect(resolveStudioDistinctId()).toBe(first);
+    expect(first).toBeTruthy();
+  });
+
+  // Regression: this used to return the shared literal "anonymous", so every
+  // storage-restricted profile was ONE bucketing unit. Against the shipped
+  // hash `calibration-50:anonymous` lands in bucket 44, so that whole
+  // population was enrolled at a nominal 50% and would flip together on a
+  // ramp — and they all merged into one PostHog person.
+  it("differs across sessions rather than sharing one constant", () => {
+    const first = resolveStudioDistinctId();
+    __resetStudioDistinctIdForTests();
+    const second = resolveStudioDistinctId();
+    expect(second).not.toBe(first);
+    expect(first).not.toBe("anonymous");
+  });
+});

package/src/telemetry/distinctId.ts

@@ -106,9 +106,18 @@ export function resolveStudioDistinctId(): string {
       return existing;
     }
   } else {
-    // No storage at all (SSR / locked-down browser): stable within the session.
+    // No storage at all (SSR / locked-down browser): stable within the
+    // session, but RANDOM per session rather than a shared literal.
+    //
+    // It used to be the constant "anonymous", which made every
+    // storage-restricted profile one bucketing unit: computed against the
+    // shipped hash, `calibration-50:anonymous` lands in bucket 44, so 100% of
+    // that population was enrolled at a nominal 50% and would flip together
+    // on any ramp. It also merged unrelated users into a single PostHog
+    // person. A per-session id spreads them and keeps them distinct, while
+    // persisting nothing.
     // `cachedId` is guaranteed null here (early-returned at the top otherwise).
-    cachedId = "anonymous";
+    cachedId = generateId();
     return cachedId;
   }
 

package/src/telemetry/policy.test.ts

@@ -0,0 +1,81 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Each control the browser telemetry policy enforces, asserted individually.
+// This is the SSOT that `telemetry/client.ts`, `utils/studioTelemetry.ts` and
+// canary enrolment all consult, so a gap here is a gap in all three — which is
+// how `navigator.doNotTrack` and Vite dev mode came to suppress one transport
+// but not the other, nor enrolment.
+
+const DOCUMENTED_OPT_OUT = "hyperframes-studio:telemetryDisabled";
+const LEGACY_OPT_OUT = "hf-studio-telemetry-opt-out";
+
+describe("browserTelemetryAllowed", () => {
+  let browserTelemetryAllowed: typeof import("./policy").browserTelemetryAllowed;
+
+  beforeEach(async () => {
+    localStorage.clear();
+    vi.resetModules();
+    // vitest sets import.meta.env.DEV; the policy suppresses under it, so the
+    // baseline has to be an explicitly production-like env.
+    vi.stubEnv("DEV", false);
+    vi.stubEnv("VITE_HYPERFRAMES_NO_TELEMETRY", "");
+    Object.defineProperty(navigator, "doNotTrack", { value: null, configurable: true });
+    ({ browserTelemetryAllowed } = await import("./policy"));
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("allows telemetry with no control set", () => {
+    expect(browserTelemetryAllowed()).toBe(true);
+  });
+
+  it("refuses when the documented localStorage key is set", () => {
+    localStorage.setItem(DOCUMENTED_OPT_OUT, "1");
+    expect(browserTelemetryAllowed()).toBe(false);
+  });
+
+  // Anyone already opted out this way must never be quietly re-enabled by the
+  // move to the documented key.
+  it("refuses when the legacy localStorage key is set", () => {
+    localStorage.setItem(LEGACY_OPT_OUT, "1");
+    expect(browserTelemetryAllowed()).toBe(false);
+  });
+
+  it("refuses when navigator.doNotTrack is on", () => {
+    Object.defineProperty(navigator, "doNotTrack", { value: "1", configurable: true });
+    expect(browserTelemetryAllowed()).toBe(false);
+  });
+
+  it("refuses under Vite dev mode", async () => {
+    vi.stubEnv("DEV", true);
+    vi.resetModules();
+    ({ browserTelemetryAllowed } = await import("./policy"));
+    expect(browserTelemetryAllowed()).toBe(false);
+  });
+
+  it.each(["1", "true", "yes", "on", " ON "])(
+    "refuses when VITE_HYPERFRAMES_NO_TELEMETRY=%s",
+    async (value) => {
+      vi.stubEnv("VITE_HYPERFRAMES_NO_TELEMETRY", value);
+      vi.resetModules();
+      ({ browserTelemetryAllowed } = await import("./policy"));
+      expect(browserTelemetryAllowed()).toBe(false);
+    },
+  );
+
+  it("ignores an unset or unrelated VITE_HYPERFRAMES_NO_TELEMETRY value", async () => {
+    vi.stubEnv("VITE_HYPERFRAMES_NO_TELEMETRY", "0");
+    vi.resetModules();
+    ({ browserTelemetryAllowed } = await import("./policy"));
+    expect(browserTelemetryAllowed()).toBe(true);
+  });
+
+  it("is not memoized — a mid-session opt-out takes effect immediately", () => {
+    expect(browserTelemetryAllowed()).toBe(true);
+    localStorage.setItem(DOCUMENTED_OPT_OUT, "1");
+    expect(browserTelemetryAllowed()).toBe(false);
+  });
+});

package/src/telemetry/policy.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// Browser telemetry policy — the single answer to "may this profile be
+// measured?", shared by every transport and by canary enrolment.
+//
+// This exists because the answer was previously duplicated and the copies had
+// drifted: `telemetry/client.ts` enforced five controls, the older
+// `utils/studioTelemetry.ts` transport enforced one (its own localStorage
+// key), and canary evaluation enforced a different one. So a profile with
+// `navigator.doNotTrack` set, or a Vite dev build, still emitted `studio:*`
+// events AND could be bucketed into a rollout — under controls the public
+// docs say disable both.
+//
+// Deliberately imports only `./config` (localStorage helpers). Nothing here
+// may import a transport or the canary module: both of those import this, and
+// the whole point is one definition with no cycle.
+// ---------------------------------------------------------------------------
+
+import { isOptedOut } from "./config";
+
+// Write-only PostHog project key, safe to embed in client code. Duplicated
+// from client.ts intentionally — the eligibility check must not drag the
+// transport (and its queue/timer state) into modules that only need the
+// policy.
+const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
+
+/** Legacy opt-out key predating `telemetry/config.ts`. Still honoured so
+ *  anyone already opted out is never quietly re-enabled. */
+const LEGACY_OPT_OUT_KEY = "hf-studio-telemetry-opt-out";
+
+function isLegacyOptedOut(): boolean {
+  try {
+    return localStorage.getItem(LEGACY_OPT_OUT_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+
+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. Match the CLI's
+// affirmative privacy-control spellings.
+// `import.meta.env` may be undefined in non-Vite bundlers (Next.js Turbopack).
+function isBuildTimeOptOut(): boolean {
+  try {
+    const v = import.meta.env.VITE_HYPERFRAMES_NO_TELEMETRY as string | undefined;
+    return v !== undefined && ["1", "true", "yes", "on"].includes(v.trim().toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+// `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 {
+  try {
+    return import.meta.env.DEV === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * May this browser profile be measured at all?
+ *
+ * Governs BOTH sending events and canary enrolment. Enrolment is part of
+ * measurement, not separate from it: a profile that reports nothing cannot be
+ * compared against anyone, so bucketing it changes that user's code path for
+ * no signal. The one documented exception is an explicit `HF_CANARY_*` /
+ * `?hf_canary_*=` override, which callers apply before consulting this.
+ *
+ * Not memoized — `isOptedOut()` reads localStorage, which a user can flip in
+ * DevTools mid-session, and the per-call cost is a couple of property reads.
+ * Callers that must stay stable within a session memoize their own result
+ * (canary decisions do; the transports intentionally do not).
+ */
+export function browserTelemetryAllowed(): boolean {
+  try {
+    return allowed();
+  } catch {
+    // Fail CLOSED. A storage read that throws must not enrol anyone, and must
+    // not propagate: callers include a post-commit catch block where a throw
+    // reports a committed edit as failed.
+    return false;
+  }
+}
+
+function allowed(): boolean {
+  return (
+    isApiKeyConfigured() &&
+    !isBuildTimeOptOut() &&
+    !isViteDevMode() &&
+    !isOptedOut() &&
+    !isLegacyOptedOut() &&
+    !isDoNotTrackOn()
+  );
+}