@hyperframes/studio 0.7.22 → 0.7.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.22",
+  "version": "0.7.24",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.22",
-    "@hyperframes/parsers": "0.7.22",
-    "@hyperframes/sdk": "0.7.22",
-    "@hyperframes/player": "0.7.22",
-    "@hyperframes/studio-server": "0.7.22"
+    "@hyperframes/core": "0.7.24",
+    "@hyperframes/sdk": "0.7.24",
+    "@hyperframes/parsers": "0.7.24",
+    "@hyperframes/player": "0.7.24",
+    "@hyperframes/studio-server": "0.7.24"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.22"
+    "@hyperframes/producer": "0.7.24"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/useDomEditSession.test.tsx

@@ -0,0 +1,277 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { shouldUseSdkCutover } from "../utils/sdkCutover";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import type { Composition } from "@hyperframes/sdk";
+import type { UseDomEditSessionParams } from "./useDomEditSession";
+
+const styleOp = (property: string, value: string): PatchOperation => ({
+  type: "inline-style",
+  property,
+  value,
+});
+
+const attrOp = (property: string, value: string): PatchOperation => ({
+  type: "attribute",
+  property,
+  value,
+});
+
+describe("shouldUseSdkCutover", () => {
+  it("returns false when flag is disabled", () => {
+    expect(shouldUseSdkCutover(false, true, "hf-abc", [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when no SDK session", () => {
+    expect(shouldUseSdkCutover(true, false, "hf-abc", [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when selection has no hfId", () => {
+    expect(shouldUseSdkCutover(true, true, null, [styleOp("color", "red")])).toBe(false);
+    expect(shouldUseSdkCutover(true, true, undefined, [styleOp("color", "red")])).toBe(false);
+  });
+
+  it("returns false when ops array is empty", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [])).toBe(false);
+  });
+
+  it("returns true when all conditions met with supported op types", () => {
+    expect(shouldUseSdkCutover(true, true, "hf-abc", [styleOp("color", "red")])).toBe(true);
+    expect(
+      shouldUseSdkCutover(true, true, "hf-abc", [styleOp("color", "red"), attrOp("data-x", "1")]),
+    ).toBe(true);
+  });
+});
+
+// ── onReorderShadow source filter (Fix 3) ────────────────────────────────────
+//
+// useDomEditSession composes ~9 sub-hooks; the only one relevant to this fix is
+// useDomEditCommits, which receives the onReorderShadow callback built inline.
+// Every other sub-hook is stubbed to a minimal shape so the hook under test can
+// render without pulling in unrelated preview/GSAP/selection machinery.
+
+const recordResolverParity = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+const capturedOnReorderShadow: { fn: ((targets: string[]) => void) | undefined } = {
+  fn: undefined,
+};
+
+vi.mock("../utils/sdkResolverShadow", () => ({
+  runResolverShadow: vi.fn(),
+  recordResolverParity: (...args: unknown[]) => recordResolverParity(...args),
+}));
+vi.mock("./useDomEditCommits", () => ({
+  useDomEditCommits: (params: { onReorderShadow?: (targets: string[]) => void }) => {
+    capturedOnReorderShadow.fn = params.onReorderShadow;
+    return {
+      resolveImportedFontAsset: vi.fn(),
+      handleDomStyleCommit: vi.fn(),
+      handleDomAttributeCommit: vi.fn(),
+      handleDomAttributeLiveCommit: vi.fn(),
+      handleDomHtmlAttributeCommit: vi.fn(),
+      handleDomTextCommit: vi.fn(),
+      handleDomTextFieldStyleCommit: vi.fn(),
+      handleDomAddTextField: vi.fn(),
+      handleDomRemoveTextField: vi.fn(),
+      handleDomBoxSizeCommit: vi.fn(),
+      handleDomManualEditsReset: vi.fn(),
+      handleDomEditElementDelete: vi.fn(),
+      handleDomZIndexReorderCommit: vi.fn(),
+    };
+  },
+}));
+vi.mock("./useDomSelection", () => ({
+  useDomSelection: () => ({
+    domEditSelection: null,
+    domEditGroupSelections: [],
+    domEditHoverSelection: null,
+    activeGroupElement: null,
+    domEditSelectionRef: { current: null },
+    domEditGroupSelectionsRef: { current: [] },
+    setActiveGroupElement: vi.fn(),
+    applyDomSelection: vi.fn(),
+    clearDomSelection: vi.fn(),
+    buildDomSelectionFromTarget: vi.fn(),
+    resolveDomSelectionFromPreviewPoint: vi.fn(),
+    resolveAllDomSelectionsFromPreviewPoint: vi.fn(),
+    updateDomEditHoverSelection: vi.fn(),
+    buildDomSelectionForTimelineElement: vi.fn(),
+    handleTimelineElementSelect: vi.fn(),
+    refreshDomEditSelectionFromPreview: vi.fn(),
+    applyMarqueeSelection: vi.fn(),
+  }),
+}));
+vi.mock("./useAskAgentModal", () => ({
+  useAskAgentModal: () => ({
+    agentModalOpen: false,
+    agentModalAnchorPoint: null,
+    copiedAgentPrompt: null,
+    agentPromptSelectionContext: null,
+    setAgentModalOpen: vi.fn(),
+    setAgentPromptSelectionContext: vi.fn(),
+    setAgentModalAnchorPoint: vi.fn(),
+    handleAskAgent: vi.fn(),
+    handleAgentModalSubmit: vi.fn(),
+  }),
+}));
+vi.mock("./useStudioSelectionPublisher", () => ({
+  useStudioSelectionPublisher: () => {},
+}));
+vi.mock("./useGsapTweenCache", () => ({
+  useGsapCacheVersion: () => ({ version: 0, bump: vi.fn() }),
+}));
+vi.mock("./useGsapScriptCommits", () => ({
+  useGsapScriptCommits: () => ({
+    commitMutation: vi.fn(),
+    updateGsapProperty: vi.fn(),
+    updateGsapMeta: vi.fn(),
+    deleteGsapAnimation: vi.fn(),
+    deleteAllForSelector: vi.fn(),
+    addGsapAnimation: vi.fn(),
+    addGsapProperty: vi.fn(),
+    removeGsapProperty: vi.fn(),
+    updateGsapFromProperty: vi.fn(),
+    addGsapFromProperty: vi.fn(),
+    removeGsapFromProperty: vi.fn(),
+    addKeyframe: vi.fn(),
+    addKeyframeBatch: vi.fn(),
+    removeKeyframe: vi.fn(),
+    moveKeyframe: vi.fn(),
+    resizeKeyframedTween: vi.fn(),
+    convertToKeyframes: vi.fn(),
+    removeAllKeyframes: vi.fn(),
+    setArcPath: vi.fn(),
+    updateArcSegment: vi.fn(),
+  }),
+}));
+vi.mock("./useGroupCommits", () => ({
+  useGroupCommits: () => ({
+    groupSelection: vi.fn(),
+    ungroupSelection: vi.fn(),
+  }),
+}));
+vi.mock("./useDomEditWiring", () => ({
+  useDomEditWiring: () => ({
+    onClickToSource: vi.fn(),
+    selectedGsapAnimations: [],
+    gsapMultipleTimelines: false,
+    gsapUnsupportedTimelinePattern: false,
+    trackGsapInteractionFailure: vi.fn(),
+    makeFetchFallback: vi.fn(),
+    handleGsapUpdateProperty: vi.fn(),
+    handleGsapUpdateMeta: vi.fn(),
+    handleGsapDeleteAnimation: vi.fn(),
+    handleGsapDeleteAllForElement: vi.fn(),
+    handleGsapAddAnimation: vi.fn(),
+    handleGsapAddProperty: vi.fn(),
+    handleGsapRemoveProperty: vi.fn(),
+    handleGsapUpdateFromProperty: vi.fn(),
+    handleGsapAddFromProperty: vi.fn(),
+    handleGsapRemoveFromProperty: vi.fn(),
+    handleGsapAddKeyframe: vi.fn(),
+    handleGsapAddKeyframeBatch: vi.fn(),
+    handleGsapRemoveKeyframe: vi.fn(),
+    handleGsapMoveKeyframeToPlayhead: vi.fn(),
+    handleGsapMoveKeyframe: vi.fn(),
+    handleGsapResizeKeyframedTween: vi.fn(),
+    handleGsapConvertToKeyframes: vi.fn(),
+    handleGsapRemoveAllKeyframes: vi.fn(),
+    handleResetSelectedElementKeyframes: vi.fn(),
+  }),
+}));
+vi.mock("./usePreviewInteraction", () => ({
+  usePreviewInteraction: () => ({
+    handlePreviewCanvasMouseDown: vi.fn(),
+    handlePreviewCanvasPointerMove: vi.fn(),
+    handlePreviewCanvasPointerLeave: vi.fn(),
+    handleBlockedDomMove: vi.fn(),
+    handleDomManualDragStart: vi.fn(),
+  }),
+}));
+vi.mock("./useGsapAwareEditing", () => ({
+  useGsapAwareEditing: () => ({
+    handleGsapAwarePathOffsetCommit: vi.fn(),
+    handleGsapAwareGroupPathOffsetCommit: vi.fn(),
+    handleGsapAwareBoxSizeCommit: vi.fn(),
+    handleGsapAwareRotationCommit: vi.fn(),
+    commitAnimatedProperty: vi.fn(),
+    commitAnimatedProperties: vi.fn(),
+    handleSetArcPath: vi.fn(),
+    handleUpdateArcSegment: vi.fn(),
+    handleUnroll: vi.fn(),
+    commitMutation: vi.fn(),
+  }),
+}));
+
+// Tell React this is an act-capable environment so act(...) flushes effects.
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("onReorderShadow source filter", () => {
+  it("passes a readSource function as the 4th recordResolverParity argument when sdkSession and activeCompPath are set", async () => {
+    const { useDomEditSession } = await import("./useDomEditSession");
+    const readProjectFile = vi.fn(async (path: string) => `content of ${path}`);
+    // Minimal opaque test double: no sub-hook under test actually calls into the
+    // session (useDomEditCommits and recordResolverParity are both mocked above),
+    // so it only needs to flow through as a reference.
+    const sdkSession = {} as unknown as Composition;
+
+    function Probe() {
+      const params: UseDomEditSessionParams = {
+        projectId: "proj-1",
+        activeCompPath: "index.html",
+        isMasterView: false,
+        compIdToSrc: new Map(),
+        captionEditMode: false,
+        compositionLoading: false,
+        previewIframeRef: { current: null },
+        timelineElements: [],
+        setSelectedTimelineElementId: vi.fn(),
+        setRightCollapsed: vi.fn(),
+        setRightPanelTab: vi.fn(),
+        showToast: vi.fn(),
+        refreshPreviewDocumentVersion: vi.fn(),
+        queueDomEditSave: vi.fn(async (save: () => Promise<void>) => save()),
+        readProjectFile,
+        writeProjectFile: vi.fn(async () => {}),
+        updateEditingFileContent: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        editHistory: { recordEdit: vi.fn(async () => {}) },
+        fileTree: [],
+        importedFontAssetsRef: { current: [] },
+        projectDir: null,
+        projectIdRef: { current: "proj-1" },
+        previewIframe: null,
+        refreshKey: 0,
+        previewDocumentVersion: 0,
+        rightPanelTab: "design",
+        applyStudioManualEditsToPreviewRef: { current: async () => {} },
+        syncPreviewHistoryHotkey: vi.fn(),
+        reloadPreview: vi.fn(),
+        setRefreshKey: vi.fn(),
+        sdkSession,
+        forceReloadSdkSession: vi.fn(),
+      };
+      useDomEditSession(params);
+      return null;
+    }
+
+    const container = document.createElement("div");
+    const root = createRoot(container);
+    act(() => {
+      root.render(<Probe />);
+    });
+    try {
+      expect(capturedOnReorderShadow.fn).toBeTypeOf("function");
+      capturedOnReorderShadow.fn?.(["hf-target"]);
+      expect(recordResolverParity).toHaveBeenCalledWith(
+        sdkSession,
+        "hf-target",
+        "reorderElements",
+        expect.any(Function),
+      );
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});

package/src/hooks/useDomEditSession.ts

@@ -87,7 +87,7 @@ export function useDomEditSession({
   showToast,
   refreshPreviewDocumentVersion,
   queueDomEditSave,
-  readProjectFile: _readProjectFile,
+  readProjectFile,
   writeProjectFile,
   updateEditingFileContent,
   domEditSaveTimestampRef,
@@ -111,7 +111,6 @@ export function useDomEditSession({
   forceReloadSdkSession,
 }: UseDomEditSessionParams) {
   void _setRefreshKey;
-  void _readProjectFile;
 
   // ── Selection ──
 
@@ -295,7 +294,14 @@ export function useDomEditSession({
     // the SDK resolves each reordered element (the reorderElements op's targets).
     onReorderShadow: sdkSession
       ? (targets: string[]) => {
-          for (const target of targets) recordResolverParity(sdkSession, target, "reorderElements");
+          // Single-flight: every target in one reorder batch shares the same file, so
+          // memoize the read instead of firing one fetch per unresolved target.
+          let reorderSrcPromise: Promise<string> | undefined;
+          const reorderSrc = activeCompPath
+            ? () => (reorderSrcPromise ??= readProjectFile(activeCompPath))
+            : undefined;
+          for (const target of targets)
+            void recordResolverParity(sdkSession, target, "reorderElements", reorderSrc);
         }
       : undefined,
   });

package/src/telemetry/config.ts

@@ -5,36 +5,21 @@
 //   localStorage.setItem('hyperframes-studio:telemetryDisabled','1')
 // ---------------------------------------------------------------------------
 
-import { generateId } from "../utils/generateId";
+import { resolveStudioDistinctId } from "./distinctId";
+import { safeLocalStorage, safeSessionStorage } from "../utils/safeStorage";
 
-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 {
-  return generateId();
-}
-
+/**
+ * Anonymous telemetry id for `studio_*` and render events.
+ *
+ * Delegates to the single source of truth in `distinctId.ts` so this id is
+ * identical to the one used for `studio:*` events (utils/studioTelemetry.ts)
+ * and, when the CLI launched Studio, to the CLI's own `config.anonymousId`.
+ */
 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;
+  return resolveStudioDistinctId();
 }
 
 export function isOptedOut(): boolean {
@@ -58,14 +43,6 @@ export function markNoticeShown(): void {
 // 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";
 }

package/src/telemetry/distinctId.test.ts

@@ -0,0 +1,103 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import {
+  resolveStudioDistinctId,
+  getCliDistinctId,
+  __resetStudioDistinctIdForTests,
+  DISTINCT_ID_KEY,
+  LEGACY_STUDIO_ANON_ID_KEY,
+} from "./distinctId";
+
+function clearCliId(): void {
+  delete window.__HF_CLI_DISTINCT_ID;
+}
+
+describe("resolveStudioDistinctId", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    clearCliId();
+    __resetStudioDistinctIdForTests();
+  });
+
+  afterEach(() => {
+    clearCliId();
+    __resetStudioDistinctIdForTests();
+  });
+
+  it("adopts the CLI-seeded id and persists it to both keys", () => {
+    window.__HF_CLI_DISTINCT_ID = "cli-machine-uuid";
+    const id = resolveStudioDistinctId();
+    expect(id).toBe("cli-machine-uuid");
+    expect(localStorage.getItem(DISTINCT_ID_KEY)).toBe("cli-machine-uuid");
+    expect(localStorage.getItem(LEGACY_STUDIO_ANON_ID_KEY)).toBe("cli-machine-uuid");
+  });
+
+  it("prefers the CLI id even over an existing persisted id", () => {
+    localStorage.setItem(DISTINCT_ID_KEY, "old-browser-id");
+    window.__HF_CLI_DISTINCT_ID = "cli-machine-uuid";
+    expect(resolveStudioDistinctId()).toBe("cli-machine-uuid");
+  });
+
+  it("ignores an empty CLI id and falls back to the persisted id", () => {
+    window.__HF_CLI_DISTINCT_ID = "";
+    localStorage.setItem(DISTINCT_ID_KEY, "persisted-id");
+    expect(resolveStudioDistinctId()).toBe("persisted-id");
+  });
+
+  it("reuses the canonical persisted id when no CLI id is present", () => {
+    localStorage.setItem(DISTINCT_ID_KEY, "canonical-id");
+    const id = resolveStudioDistinctId();
+    expect(id).toBe("canonical-id");
+    // Backfills the legacy key so both clients agree.
+    expect(localStorage.getItem(LEGACY_STUDIO_ANON_ID_KEY)).toBe("canonical-id");
+  });
+
+  it("reuses the legacy key when only it exists, and backfills the canonical key", () => {
+    localStorage.setItem(LEGACY_STUDIO_ANON_ID_KEY, "legacy-id");
+    const id = resolveStudioDistinctId();
+    expect(id).toBe("legacy-id");
+    expect(localStorage.getItem(DISTINCT_ID_KEY)).toBe("legacy-id");
+  });
+
+  it("mints and persists a new id when nothing exists (standalone Studio)", () => {
+    const id = resolveStudioDistinctId();
+    expect(id).toBeTruthy();
+    expect(localStorage.getItem(DISTINCT_ID_KEY)).toBe(id);
+    expect(localStorage.getItem(LEGACY_STUDIO_ANON_ID_KEY)).toBe(id);
+  });
+
+  it("memoizes the resolved id within a session", () => {
+    const first = resolveStudioDistinctId();
+    localStorage.setItem(DISTINCT_ID_KEY, "changed-underneath");
+    expect(resolveStudioDistinctId()).toBe(first);
+  });
+
+  it("memoizes an adopted CLI id even if window.__HF_CLI_DISTINCT_ID changes later", () => {
+    window.__HF_CLI_DISTINCT_ID = "cli-id-1";
+    expect(resolveStudioDistinctId()).toBe("cli-id-1");
+    // A late reassignment of the injected global must not change the resolved id.
+    window.__HF_CLI_DISTINCT_ID = "cli-id-2";
+    expect(resolveStudioDistinctId()).toBe("cli-id-1");
+  });
+});
+
+describe("getCliDistinctId", () => {
+  beforeEach(() => {
+    clearCliId();
+  });
+
+  it("returns the injected id when present", () => {
+    window.__HF_CLI_DISTINCT_ID = "cli-id";
+    expect(getCliDistinctId()).toBe("cli-id");
+  });
+
+  it("returns null when absent", () => {
+    expect(getCliDistinctId()).toBeNull();
+  });
+
+  it("returns null for an empty string", () => {
+    window.__HF_CLI_DISTINCT_ID = "";
+    expect(getCliDistinctId()).toBeNull();
+  });
+});

package/src/telemetry/distinctId.ts

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// Single source of truth for the Studio telemetry distinct_id.
+//
+// Studio historically minted TWO independent anonymous ids:
+//   - `hf-studio-anon-id`            (utils/studioTelemetry.ts → studio:* events)
+//   - `hyperframes-studio:anonymousId` (telemetry/config.ts → studio_* + render events)
+// so a single browser looked like two different people in PostHog. This module
+// resolves ONE id that both clients (and the render→CLI channel) share.
+//
+// CLI→Studio identity stitch (Layer 1, no login / no PII):
+// When the CLI launches Studio it injects its own `config.anonymousId`
+// (a random UUID from ~/.hyperframes/config.json) as `window.__HF_CLI_DISTINCT_ID`
+// (see packages/cli/src/server/studioServer.ts). When present we ADOPT it as the
+// Studio distinct_id and persist it, so CLI `cli_command*` events and the
+// browser's `studio:*` / `studio_*` / render events are attributed to the same
+// PostHog person. When absent (Studio opened standalone) we fall back to the
+// previous per-browser localStorage id — behaviour is unchanged.
+// ---------------------------------------------------------------------------
+
+import { generateId } from "../utils/generateId";
+import { safeLocalStorage } from "../utils/safeStorage";
+
+// Canonical storage key. Both legacy keys are kept in sync (below) so any code
+// still reading them directly, plus older cached values, resolve to one id.
+export const DISTINCT_ID_KEY = "hyperframes-studio:anonymousId";
+// Legacy key used by utils/studioTelemetry.ts for `studio:*` events.
+export const LEGACY_STUDIO_ANON_ID_KEY = "hf-studio-anon-id";
+
+// Global injected by the CLI's embedded studio server at page load. Read-only
+// from the browser's perspective.
+declare global {
+  interface Window {
+    __HF_CLI_DISTINCT_ID?: string;
+  }
+}
+
+let cachedId: string | null = null;
+
+/**
+ * The distinct_id the CLI seeded into the page, if any. A non-empty string
+ * means "this Studio was launched by the HyperFrames CLI, adopt its identity".
+ */
+export function getCliDistinctId(): string | null {
+  try {
+    const id = typeof window === "undefined" ? undefined : window.__HF_CLI_DISTINCT_ID;
+    return typeof id === "string" && id.length > 0 ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+// Persist to both the canonical and legacy keys so the two Studio clients and
+// any cached reads converge on one id. Best-effort — private browsing / quota
+// failures are non-fatal (we still return the in-memory id for this session).
+function persist(ls: Storage, id: string): void {
+  for (const key of [DISTINCT_ID_KEY, LEGACY_STUDIO_ANON_ID_KEY]) {
+    try {
+      ls.setItem(key, id);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Resolve the single Studio telemetry distinct_id.
+ *
+ * Precedence:
+ *   1. CLI-seeded id (`window.__HF_CLI_DISTINCT_ID`) — adopted + persisted so
+ *      the browser session joins the CLI machine's PostHog person.
+ *   2. Existing persisted id (canonical or legacy key) — unchanged behaviour.
+ *   3. A freshly generated UUID — persisted for future loads.
+ *
+ * Memoized per module instance so repeated calls in a session are stable even
+ * if localStorage is unavailable.
+ */
+export function resolveStudioDistinctId(): string {
+  if (cachedId) return cachedId;
+
+  const ls = safeLocalStorage();
+
+  // 1. CLI-seeded identity wins. Adopt + persist so it's stable across reloads
+  //    and shared by every Studio telemetry path.
+  const cliId = getCliDistinctId();
+  if (cliId) {
+    cachedId = cliId;
+    if (ls) persist(ls, cliId);
+    return cliId;
+  }
+
+  // 2. Reuse an existing persisted id (prefer canonical, fall back to legacy).
+  if (ls) {
+    // getItem can throw in storage-restricted contexts (partitioned / sandboxed
+    // storage) even when the localStorage reference itself resolved — stay
+    // fail-silent (telemetry must never break Studio) and treat it as "no id".
+    let existing: string | null = null;
+    try {
+      existing = ls.getItem(DISTINCT_ID_KEY) ?? ls.getItem(LEGACY_STUDIO_ANON_ID_KEY);
+    } catch {
+      /* ignore */
+    }
+    if (existing) {
+      cachedId = existing;
+      // Backfill the other key so both clients agree going forward.
+      persist(ls, existing);
+      return existing;
+    }
+  } else {
+    // No storage at all (SSR / locked-down browser): stable within the session.
+    // `cachedId` is guaranteed null here (early-returned at the top otherwise).
+    cachedId = "anonymous";
+    return cachedId;
+  }
+
+  // 3. Mint a new id and persist it.
+  const id = generateId();
+  cachedId = id;
+  persist(ls, id);
+  return id;
+}
+
+/** Test-only: clear the memoized id so a fresh resolution can be exercised. */
+export function __resetStudioDistinctIdForTests(): void {
+  cachedId = null;
+}

package/src/utils/safeStorage.ts

@@ -0,0 +1,20 @@
+// Best-effort access to Web Storage. Reading the `localStorage` /
+// `sessionStorage` globals can throw (SSR, storage disabled, sandboxed or
+// partitioned browsing contexts), so callers get `null` instead of an
+// exception — telemetry must never break Studio.
+
+export function safeLocalStorage(): Storage | null {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function safeSessionStorage(): Storage | null {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}