@hyperframes/studio 0.8.56 → 0.8.58

package/src/telemetry/tabId.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resetTabIdForTests, resolveTabId, tabIdProperty } from "./tabId";
+
+afterEach(() => {
+  resetTabIdForTests();
+});
+
+describe("tab id", () => {
+  it("is stable for the life of the page", () => {
+    // The whole value of the property: every event from one page load must
+    // carry the SAME id, or a burst still reads as several sources.
+    const first = resolveTabId();
+    expect(resolveTabId()).toBe(first);
+    expect(tabIdProperty()).toBe(first);
+  });
+
+  it("is not empty, since an empty value would read as an absent one", () => {
+    expect(resolveTabId().length).toBeGreaterThan(0);
+  });
+
+  it("mints a new id after a fresh page load", () => {
+    // resetTabIdForTests stands in for a reload: the memo is all that survives
+    // a page, so clearing it is exactly what a reload does.
+    const first = resolveTabId();
+    resetTabIdForTests();
+    expect(resolveTabId()).not.toBe(first);
+  });
+
+  it("never touches storage", () => {
+    // Deliberate: a stored id would drift into a tab-session id, silently
+    // changing what every query means. This asserts the intent directly rather
+    // than inferring it, so adding a read OR a write fails here.
+    const seen: string[] = [];
+    vi.stubGlobal("localStorage", {
+      getItem: (k: string) => (seen.push(`get:${k}`), null),
+      setItem: (k: string) => void seen.push(`set:${k}`),
+      removeItem: (k: string) => void seen.push(`remove:${k}`),
+    });
+    resolveTabId();
+    expect(seen).toEqual([]);
+    vi.unstubAllGlobals();
+  });
+});

package/src/telemetry/tabId.ts

@@ -0,0 +1,44 @@
+/**
+ * A per-page-load identifier, attached to every Studio event from BOTH
+ * transports (`studio:*` via utils/studioTelemetry.ts, `studio_*` via
+ * telemetry/system.ts).
+ *
+ * Why it exists: `distinct_id` identifies a browser, not a page. Several
+ * investigations have stalled on "two tabs or one tab switching?" — a burst of
+ * events alternating between two project hashes is indistinguishable from a
+ * user moving between projects, and `session_start` fires once per page LOAD
+ * (main.tsx), so counting it cannot tell them apart either. Nothing in the
+ * payload named the page. This does.
+ *
+ * Semantics, stated plainly because the name invites the wrong reading: one id
+ * per PAGE LOAD. A hard reload mints a new one. It is not "the same tab across
+ * reloads" — that is a different, harder question, and nobody has needed it yet.
+ *
+ * Deliberately not persisted. Storage would survive a reload and turn this into
+ * a tab-session id, silently changing what every query means; and a blocked or
+ * cleared storage would make the property intermittently absent, which reads as
+ * "old client" rather than "storage unavailable".
+ *
+ * Memoized like agentRuntime.ts and distinctId.ts: fixed for the life of the
+ * page, so a per-event caller does not pay for generation on every emit.
+ */
+
+import { generateId } from "../utils/generateId";
+
+let cached: string | null = null;
+
+/** The page's id. Generated once, on first read. */
+export function resolveTabId(): string {
+  if (cached === null) cached = generateId();
+  return cached;
+}
+
+/** The same value as a telemetry property, for the `studio_*` transport's meta. */
+export function tabIdProperty(): string {
+  return resolveTabId();
+}
+
+/** Test seam: the memo would otherwise leak between cases in one module load. */
+export function resetTabIdForTests(): void {
+  cached = null;
+}

package/src/utils/previewCompositionSize.ts

@@ -0,0 +1,26 @@
+export interface PreviewCompositionSize {
+  width: number;
+  height: number;
+}
+
+/** The root composition's authored size, read from the preview document itself. */
+// fallow-ignore-next-line complexity
+export function readPreviewCompositionSize(
+  iframe: HTMLIFrameElement | null,
+): PreviewCompositionSize | null {
+  try {
+    const doc = iframe?.contentDocument;
+    const root =
+      doc?.querySelector("[data-composition-id][data-width][data-height]") ??
+      doc?.querySelector("[data-width][data-height]");
+    if (!root) return null;
+    const width = Number.parseInt(root.getAttribute("data-width") ?? "", 10);
+    const height = Number.parseInt(root.getAttribute("data-height") ?? "", 10);
+    if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+      return null;
+    }
+    return { width, height };
+  } catch {
+    return null;
+  }
+}

package/src/utils/reloadDebug.ts

@@ -1,10 +1,8 @@
 // Preview full-reload diagnostics — grep [hf-reload]. Off by default; opt in per
 // session with `localStorage.setItem("hf-reload-debug", "1")` (then reload).
 //
-// A full reload blanks the stage for ~100-300ms, so any reload the user did not
-// ask for reads as a flash. These lines answer the only question that matters
-// when one appears: who asked for it, and why the write that triggered it was
-// not recognised as Studio's own.
+// A full reload no longer blanks the stage (see useShadowPreviewReload.ts). These lines answer
+// who asked for a reload and why the write was not recognised as Studio's own.
 import { makeStudioDebugLogger } from "./studioDebug";
 
 export const logReload = makeStudioDebugLogger("reload");

package/src/utils/sourcePatcher.ts

@@ -420,7 +420,7 @@ function findMatchingClosingTagIndex(html: string, tagName: string, contentStart
   return -1;
 }
 
-const HTML_BOOLEAN_ATTRIBUTES = new Set([
+export const HTML_BOOLEAN_ATTRIBUTES = new Set([
   "loop",
   "muted",
   "autoplay",

package/src/utils/studioTelemetry.test.ts

@@ -66,6 +66,20 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
     });
   });
 
+  // The property is useless if the transport does not attach it: the module
+  // has its own test, but nothing there fails if this line is deleted.
+  it("stamps every event with a tab id that is stable within the page", async () => {
+    trackStudioEvent("first");
+    trackStudioEvent("second");
+    const events = await sentEvents();
+    expect(events).toHaveLength(2);
+    const tabIds = events.map((e) => (e["properties"] as Record<string, unknown>)["tab_id"]);
+    expect(typeof tabIds[0]).toBe("string");
+    expect((tabIds[0] as string).length).toBeGreaterThan(0);
+    // Same page, same id — otherwise a burst still reads as several sources.
+    expect(tabIds[1]).toBe(tabIds[0]);
+  });
+
   it("lets an explicit property win over the canary mixin", async () => {
     trackStudioEvent("thing_happened", { "$feature/canary-test-one": "false" });
     const events = await sentEvents();

package/src/utils/studioTelemetry.ts

@@ -2,6 +2,7 @@ import { resolveStudioDistinctId } from "../telemetry/distinctId";
 import { browserTelemetryAllowed } from "../telemetry/policy";
 import { canaryEventProperties } from "../telemetry/canary";
 import { agentRuntimeProperty } from "../telemetry/agentRuntime";
+import { tabIdProperty } from "../telemetry/tabId";
 
 // PostHog public ingest key — write-only, safe to ship in the client bundle
 const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
@@ -48,6 +49,9 @@ function getSessionProperties(): EventProperties {
     // and a property that only some events carry cannot answer it — the
     // breakdown silently reads as though the agent never used the rest.
     agent_runtime: agentRuntimeProperty(),
+    // Which page load this came from — distinct_id identifies the browser, not
+    // the page, so two tabs are otherwise one indistinguishable stream.
+    tab_id: tabIdProperty(),
     screen_width: window.screen?.width,
     screen_height: window.screen?.height,
     viewport_width: window.innerWidth,