@hyperframes/studio 0.8.113 → 0.8.115

package/src/player/components/useTimelineClipDrag.ts

@@ -29,6 +29,7 @@ import type {
 } from "./timelineClipDragTypes";
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
 import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
+import { exceedsHandEditLimit } from "./timelineLinkSelection";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 import { useTimelineClipCapabilities } from "./timelineReadOnly";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
@@ -158,11 +159,8 @@ export function useTimelineClipDrag({
   const elementsRef = useRef(elements);
   elementsRef.current = elements;
 
-  // Perf (frozen-per-gesture): the snap-target set and the audio-track set are
-  // fixed for the duration of one drag/resize (the store is not re-authored mid
-  // gesture), so build each ONCE and reuse it across every pointermove and every
-  // auto-scroll frame. Both caches are cleared at gesture teardown
-  // (stopClipDragAutoScroll), so the next gesture rebuilds against fresh state.
+  // The snap-target and audio-track sets are fixed for one drag/resize (the store is not
+  // re-authored mid gesture): built once, reused per pointermove, cleared at teardown.
   const snapTargetsCacheRef = useRef<Map<string, TimelineSnapTarget[]>>(new Map());
   const dragAudioTracksRef = useRef<ReadonlySet<number> | null>(null);
 
@@ -272,8 +270,7 @@ export function useTimelineClipDrag({
   const blockedClipRef = useRef<BlockedClipState | null>(null);
   const suppressClickRef = useRef(false);
 
-  // Active multi-select group-resize session, created lazily on first movement.
-  // It owns a projection only; canonical store timing changes at commit.
+  // Group-resize session, created on first movement; a projection only, committed at the end.
   const groupResizeRef = useRef<TimelineGroupResizeSession | null>(null);
 
   const onMoveElementRef = useRef(onMoveElement);
@@ -541,6 +538,8 @@ export function useTimelineClipDrag({
       if (!element || !getClipCapabilities(element).canMove) return;
       event.preventDefault();
       event.stopImmediatePropagation();
+      if (exceedsHandEditLimit(element, false, null))
+        return void onBlockedEditAttemptRef.current?.(element, "edit-many");
       setShowPopover(false);
       setRangeSelectionRef.current?.(null);
       const row = keyboardPickupInsertRow(

package/src/player/hooks/timelinePlayerSync.test.ts

@@ -31,4 +31,10 @@ describe("timelineElementsChanged", () => {
     expect(timelineElementsChanged([grouped], [clip])).toBe(true);
     expect(timelineElementsChanged([grouped], [{ ...grouped }])).toBe(false);
   });
+
+  it("sees a change to a text row's words, but not an identical re-read", () => {
+    const row = { id: "t", tag: "h1", start: 0, duration: 2, track: 0, text: { value: "Old" } };
+    expect(timelineElementsChanged([row], [{ ...row, text: { value: "Old" } }])).toBe(false);
+    expect(timelineElementsChanged([row], [{ ...row, text: { value: "New" } }])).toBe(true);
+  });
 });

package/src/player/hooks/timelinePlayerSync.ts

@@ -1,4 +1,5 @@
 import type { TimelineElement } from "../store/playerStore";
+import { sameTimelineText } from "../lib/timelineText";
 
 const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
   "id",
@@ -28,6 +29,10 @@ export function timelineElementsChanged(
   if (next.length !== previous.length) return true;
   return next.some((element, index) => {
     const prior = previous[index];
-    return !prior || RENDERED_FIELDS.some((key) => element[key] !== prior[key]);
+    return (
+      !prior ||
+      RENDERED_FIELDS.some((key) => element[key] !== prior[key]) ||
+      !sameTimelineText(element.text, prior.text)
+    );
   });
 }

package/src/player/lib/timelineElementHelpers.test.ts

@@ -1,5 +1,13 @@
+// @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
-import { isVideoAudible } from "./timelineElementHelpers";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  applyMediaMetadataFromElement,
+  getTimelineElementSelector,
+  isVideoAudible,
+  resolveMediaElement,
+} from "./timelineElementHelpers";
+import { readTimelineText, sameTimelineText } from "./timelineText";
 
 describe("isVideoAudible — the compiler's data-has-audio rule", () => {
   it("explicit data-has-audio wins", () => {
@@ -14,3 +22,81 @@ describe("isVideoAudible — the compiler's data-has-audio rule", () => {
     expect(isVideoAudible({ tag: "img", hasAudioAttr: null, muted: false })).toBe(false);
   });
 });
+
+describe("preview nodes built in another realm", () => {
+  // The Studio preview's body carries the editor window's prototypes, so its
+  // nodes fail `instanceof` against their own window's HTMLElement.
+  function foreignNode(html: string): Element {
+    const holder = document.createElement("div");
+    holder.innerHTML = html;
+    const node = holder.firstElementChild!;
+    document.body.appendChild(node);
+    Object.setPrototypeOf(node, Object.create(Element.prototype));
+    expect(node instanceof HTMLElement).toBe(false);
+    return node;
+  }
+
+  it("gives a row with an id its id selector", () => {
+    const el = foreignNode(`<div id="layer-00" class="clip layer"></div>`);
+    expect(getTimelineElementSelector(el)).toBe("#layer-00");
+  });
+
+  it("reads media metadata off a foreign <video>", () => {
+    const el = foreignNode(`<video src="a.mp4" data-source-duration="12"></video>`);
+    expect(resolveMediaElement(el)).toBe(el);
+    const entry = { id: "v", tag: "div", start: 0, duration: 4, track: 0 } as TimelineElement;
+    applyMediaMetadataFromElement(entry, el);
+    expect(entry.sourceDuration).toBe(12);
+  });
+});
+
+describe("readTimelineText", () => {
+  function layer(html: string): Element {
+    document.body.innerHTML = html;
+    return document.body.firstElementChild!;
+  }
+
+  it("reads a text layer's words, collapsed to one line, with its font and colour", () => {
+    const text = readTimelineText(
+      layer(`<h1 style="font-family: Georgia; font-weight: 700; color: rgb(255, 0, 0)">
+        Ship <span>it</span>
+      </h1>`),
+    );
+    expect(text).toMatchObject({ value: "Ship it", fontWeight: "700", color: "rgb(255, 0, 0)" });
+    expect(text?.fontFamily).toContain("Georgia");
+  });
+
+  it("leaves a layer that holds anything but text, or no words, to its picture", () => {
+    expect(
+      readTimelineText(layer(`<div><div>Title</div><div><i></i></div></div>`)),
+    ).toBeUndefined();
+    expect(readTimelineText(layer(`<div class="glyph"></div>`))).toBeUndefined();
+    expect(readTimelineText(layer(`<section>Words</section>`))).toBeUndefined();
+  });
+
+  it("keeps a layer that paints an image as a picture, and carries a flat background colour", () => {
+    expect(
+      readTimelineText(
+        layer(`<div style="background-image: linear-gradient(red, blue)">L01</div>`),
+      ),
+    ).toBeUndefined();
+    expect(
+      readTimelineText(layer(`<div style="background-color: rgb(230, 57, 70)">Go</div>`)),
+    ).toMatchObject({
+      value: "Go",
+      background: "rgb(230, 57, 70)",
+    });
+    expect(readTimelineText(layer(`<div>Go</div>`))?.background).toBeUndefined();
+    expect(
+      readTimelineText(layer(`<div style="background-color: rgba(255, 255, 255, 0.01)">Go</div>`))
+        ?.background,
+    ).toBeUndefined();
+  });
+
+  it("tells a text change apart from an identical re-read", () => {
+    const text = { value: "Old", color: "rgb(0, 0, 0)" };
+    expect(sameTimelineText(text, { ...text })).toBe(true);
+    expect(sameTimelineText(text, { ...text, value: "New" })).toBe(false);
+    expect(sameTimelineText(text, undefined)).toBe(false);
+  });
+});

package/src/player/lib/timelineElementHelpers.ts

@@ -8,11 +8,13 @@
  */
 
 import type { TimelineElement } from "../store/playerStore";
+import { readTimelineText } from "./timelineText";
 import type { ClipManifestClip } from "./playbackTypes";
 import { isFinitePositive } from "./playbackAdapter";
 import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
 import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 import { readElementFades } from "@hyperframes/core/audio-fade";
+import { isHtmlElement, isImageElement, isMediaElement } from "@hyperframes/core/runtime/dom-realm";
 import { elementVolume } from "./storedVolume";
 import {
   type AttrReader,
@@ -143,11 +145,6 @@ export function furthestClipEndFromSource(source: string): number {
 // DOM element type guards
 // ---------------------------------------------------------------------------
 
-function isHtmlElement(el: Element): el is HTMLElement {
-  const HtmlElementCtor = el.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
-  return typeof HtmlElementCtor !== "undefined" && el instanceof HtmlElementCtor;
-}
-
 function isCompositionHost(el: Element): boolean {
   return (
     el.hasAttribute("data-composition-id") ||
@@ -157,16 +154,11 @@ function isCompositionHost(el: Element): boolean {
 }
 
 export function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageElement | null {
-  const win = el.ownerDocument.defaultView ?? window;
-  const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
-  const ImageElementCtor = win.HTMLImageElement ?? globalThis.HTMLImageElement;
-  if (el instanceof MediaElementCtor || el instanceof ImageElementCtor) return el;
+  if (isMediaElement(el) || isImageElement(el)) return el;
   // A composition's media belongs to its own timeline, not the clip's: its length would cap a trim.
   if (isCompositionHost(el)) return null;
   const candidate = el.querySelector("video, audio, img");
-  return candidate instanceof MediaElementCtor || candidate instanceof ImageElementCtor
-    ? candidate
-    : null;
+  return isMediaElement(candidate) || isImageElement(candidate) ? candidate : null;
 }
 
 /** The in-point as playback reads it, and the attribute holding it; empty when neither is authored. */
@@ -255,6 +247,7 @@ function applyFadeMetadataFromElement(entry: TimelineElement, el: Element): void
 }
 
 export function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
+  setOptional(entry, "text", readTimelineText(el));
   applyPlaybackMetadataFromElement(entry, el);
   applyAudioMetadataFromElement(entry, el);
   applyFadeMetadataFromElement(entry, el);
@@ -266,9 +259,7 @@ export function applyMediaMetadataFromElement(entry: TimelineElement, el: Elemen
   const src = mediaEl.getAttribute("src");
   if (src) entry.src = src;
 
-  const win = mediaEl.ownerDocument.defaultView ?? window;
-  const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
-  if (typeof MediaElementCtor === "undefined" || !(mediaEl instanceof MediaElementCtor)) return;
+  if (!isMediaElement(mediaEl)) return;
 
   const sourceDurationAttr =
     el.getAttribute("data-source-duration") ?? mediaEl.getAttribute("data-source-duration");

package/src/player/lib/timelineText.ts

@@ -0,0 +1,40 @@
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
+import { parseCssColor } from "../../components/editor/colorValue";
+import type { TimelineText } from "../store/timelineElement";
+import {
+  getCuratedComputedStyles,
+  isEditableTextLeaf,
+  isTextBearingTag,
+} from "../../components/editor/domEditingDom";
+
+/** A layer that paints only text and a flat colour (a text tag whose children are all text leaves,
+ *  no background image): its words and look. Anything painted beyond that keeps its picture. */
+export function readTimelineText(el: Element): TimelineText | undefined {
+  if (!isHtmlElement(el) || !isTextBearingTag(el.localName)) return undefined;
+  const children = Array.from(el.children);
+  if (!children.every((child) => isHtmlElement(child) && isEditableTextLeaf(child)))
+    return undefined;
+  const value = el.textContent?.replace(/\s+/g, " ").trim();
+  if (!value) return undefined;
+  const style = getCuratedComputedStyles(el);
+  if ((style["background-image"] ?? "none") !== "none") return undefined;
+  const background = style["background-color"];
+  return {
+    value,
+    fontFamily: style["font-family"],
+    fontWeight: style["font-weight"],
+    color: style.color,
+    background: background && parseCssColor(background)?.alpha === 1 ? background : undefined,
+  };
+}
+
+export function sameTimelineText(a?: TimelineText, b?: TimelineText): boolean {
+  if (!a || !b) return a === b;
+  return (
+    a.value === b.value &&
+    a.fontFamily === b.fontFamily &&
+    a.fontWeight === b.fontWeight &&
+    a.color === b.color &&
+    a.background === b.background
+  );
+}

package/src/player/store/timelineElement.ts

@@ -95,6 +95,17 @@ export interface TimelineElement {
   authoredStartIsMasterTime?: boolean;
   /** Legacy marker for an inline sub-composition child; current rows never set it. */
   expandedHostKey?: string;
+  /** A text layer's words and look, which its row draws live instead of a captured picture. */
+  text?: TimelineText;
+}
+
+export interface TimelineText {
+  value: string;
+  fontFamily?: string;
+  fontWeight?: string;
+  color?: string;
+  /** The layer's own opaque background colour, when it paints one. */
+  background?: string;
 }
 
 type RowClock = Pick<
@@ -156,6 +167,7 @@ export type TimelineElementPatch = Partial<
     | "audioGroupHidden"
     | "audioGroupFxChain"
     | "audioGroupAutomation"
+    | "text"
   >
 >;
 

package/src/styles/theme.css

@@ -146,6 +146,9 @@
     transparent 100%
   );
   --timeline-thumbnail-label-shadow: 0 1px 2px rgba(0, 0, 0, 0.9);
+  /* A text clip's strip behind its live words: dark for light text, light for dark text. */
+  --timeline-text-clip-dark-bg: #1c2028;
+  --timeline-text-clip-light-bg: #e9e6df;
   --timeline-waveform-bar-rgb: 245, 237, 255;
   --timeline-waveform-muted-rgb: 236, 238, 242;
   --timeline-waveform-baseline-rgb: 226, 216, 238;

package/src/utils/frameCapture.ts

@@ -5,6 +5,7 @@ export interface FrameCaptureRequest {
   compositionPath: string | null;
   currentTime: number;
   origin?: string;
+  version?: number;
 }
 
 function normalizeCompositionPath(compositionPath: string | null): string {
@@ -16,6 +17,7 @@ export function buildFrameCaptureUrl({
   compositionPath,
   currentTime,
   origin = window.location.origin,
+  version = Date.now(),
 }: FrameCaptureRequest): string {
   const compPath = normalizeCompositionPath(compositionPath);
   const url = new URL(
@@ -25,7 +27,7 @@ export function buildFrameCaptureUrl({
   url.searchParams.set("t", Math.max(0, currentTime).toFixed(3));
   url.searchParams.set("format", "png");
   url.searchParams.set("output", "source");
-  url.searchParams.set("v", String(Date.now()));
+  url.searchParams.set("v", String(version));
   return url.toString();
 }
 

package/src/utils/gsapUndoRestore.browser.test.ts

@@ -6,12 +6,14 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import puppeteer, { type Browser } from "puppeteer-core";
 import { build } from "vite";
-import { afterAll, beforeAll, expect, it } from "vitest";
+import { afterAll, beforeAll, expect, it, vi } from "vitest";
 import { findSystemChrome } from "../../vite.browser";
 import { writeFixture } from "../../tests/e2e/edit-accuracy/grid.mjs";
 
 const require = createRequire(import.meta.url);
 const CROP = "inset(0px 40px 0px 0px)";
+// Real Chrome on a loaded Windows runner exceeds Vitest's 5s test and 10s hook defaults.
+vi.setConfig({ testTimeout: 60_000, hookTimeout: 60_000 });
 let browser: Browser;
 let undoBundle: string;
 
@@ -37,7 +39,7 @@ beforeAll(async () => {
   });
   undoBundle = (Array.isArray(out) ? out[0]! : (out as { output: [{ code: string }] })).output[0]
     .code;
-}, 60_000);
+});
 
 afterAll(() => browser?.close());
 

package/src/utils/keyframeUsage.ts

@@ -0,0 +1,79 @@
+import type { CommitMutationOptions, MutationResult } from "../hooks/gsapScriptCommitTypes";
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type KeyframeUsageAction = "add" | "convert" | "remove_all" | "reset";
+
+export function keyframeUsageActions(
+  mutations: ReadonlyArray<Record<string, unknown>>,
+  semanticActions?: ReadonlyArray<KeyframeUsageAction | undefined>,
+): Set<KeyframeUsageAction> {
+  const actions = new Set<KeyframeUsageAction>();
+  for (const [index, mutation] of mutations.entries()) {
+    const semanticAction = semanticActions?.[index];
+    if (semanticAction) {
+      actions.add(semanticAction);
+      continue;
+    }
+    switch (mutation.type) {
+      case "add-keyframe":
+      case "add-with-keyframes":
+        actions.add("add");
+        break;
+      case "convert-to-keyframes":
+        actions.add("convert");
+        break;
+      case "remove-all-keyframes":
+        actions.add("remove_all");
+        break;
+    }
+  }
+  return actions;
+}
+
+export function trackKeyframeUsage(action: KeyframeUsageAction, property?: string): void {
+  trackStudioEvent("keyframe", property === undefined ? { action } : { action, property });
+}
+
+export function primaryKeyframeAction(
+  actions: ReadonlySet<KeyframeUsageAction>,
+): KeyframeUsageAction | undefined {
+  return (["add", "convert", "remove_all", "reset"] as const).find((action) => actions.has(action));
+}
+
+export function changedMutationIndices(
+  result: MutationResult,
+  count: number,
+  options?: ReadonlyArray<Pick<CommitMutationOptions, "keyframeTelemetry">>,
+): number[] {
+  if (!result.ok || result.changed !== true) return [];
+  const changes = count === 1 ? [true] : result.mutationChanges;
+  if (
+    !Array.isArray(changes) ||
+    changes.length !== count ||
+    changes.some((value) => typeof value !== "boolean")
+  )
+    return [];
+  return changes.flatMap((changed, index) =>
+    changed && options?.[index]?.keyframeTelemetry !== false ? [index] : [],
+  );
+}
+
+export function trackKeyframeCommit(
+  mutations: ReadonlyArray<Record<string, unknown>>,
+  result: MutationResult,
+  options: CommitMutationOptions,
+  memberOptions?: ReadonlyArray<CommitMutationOptions>,
+): void {
+  if (!result.ok || result.changed !== true || options.keyframeTelemetry === false) return;
+  const indices = changedMutationIndices(result, mutations.length, memberOptions);
+  const actions = keyframeUsageActions(
+    indices.map((index) => mutations[index]!),
+    indices.map(
+      (index) =>
+        memberOptions?.[index]?.keyframeAction ??
+        (mutations.length === 1 ? options.keyframeAction : undefined),
+    ),
+  );
+  const action = primaryKeyframeAction(actions);
+  if (action) trackKeyframeUsage(action, action === "add" ? options.keyframeProperty : undefined);
+}

package/src/utils/previewFeatureUsage.test.ts

@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { trackPreviewEditResult } from "./previewFeatureUsage";
+import { trackStudioEvent } from "./studioTelemetry";
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+beforeEach(() => vi.clearAllMocks());
+describe("preview write usage", () => {
+  it.each([
+    { ok: true, changed: true },
+    {
+      ok: true,
+      persistence: { changed: true, sourceFile: "private.html", content: "private text" },
+    },
+  ])("sends only gesture metadata after a changed result", (result) => {
+    trackPreviewEditResult("resize", "drag", result);
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: "resize",
+      surface: "preview",
+      method: "drag",
+    });
+  });
+  it.each([
+    undefined,
+    null,
+    {},
+    { ok: false, changed: true },
+    { changed: false },
+    { persistence: { changed: false } },
+  ])("does not count unavailable, failed or unchanged results (%j)", (result) => {
+    trackPreviewEditResult("move", "drag", result);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+});

package/src/utils/previewFeatureUsage.ts

@@ -0,0 +1,46 @@
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type PreviewFeature =
+  | "move"
+  | "resize"
+  | "rotate"
+  | "crop"
+  | "nudge"
+  | "multi_select"
+  | "z_order"
+  | "text_edit"
+  | "motion_path"
+  | "gesture_recording"
+  | "snapping"
+  | "grid"
+  | "grid_spacing"
+  | "snap_to_grid"
+  | "ruler"
+  | "safe_margins";
+
+export type PreviewMethod = "drag" | "button" | "keyboard" | "field";
+
+export interface GeometryCommitResult {
+  ok: true;
+  changed: boolean;
+}
+
+export function trackPreviewFeatureUsed(feature: PreviewFeature, method: PreviewMethod): void {
+  trackStudioEvent("feature_used", { feature, surface: "preview", method });
+}
+
+export function trackPreviewEditResult(
+  feature: PreviewFeature,
+  method: PreviewMethod,
+  result: unknown,
+): void {
+  if (typeof result !== "object" || result === null) return;
+  if (Reflect.get(result, "ok") === false) return;
+  const persistence = Reflect.get(result, "persistence");
+  const changed =
+    Reflect.get(result, "changed") === true ||
+    (typeof persistence === "object" &&
+      persistence !== null &&
+      Reflect.get(persistence, "changed") === true);
+  if (changed) trackPreviewFeatureUsed(feature, method);
+}

package/src/utils/studioTelemetry.test.ts

@@ -1,5 +1,6 @@
 // @vitest-environment happy-dom
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { buildProjectHash } from "./projectRouting";
 
 // The `studio:*` path predates telemetry/config.ts and shipped its own
 // opt-out key and its own send loop, so it sat outside both contracts the
@@ -25,6 +26,8 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
   beforeEach(async () => {
     policyState.allowed = true;
     localStorage.clear();
+    sessionStorage.clear();
+    window.location.hash = "";
     vi.resetModules();
     vi.useFakeTimers();
     fetchMock = vi.fn(() => Promise.resolve({ ok: true } as Response));
@@ -33,8 +36,10 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
   });
 
   afterEach(() => {
+    window.location.hash = "";
     vi.useRealTimers();
     vi.unstubAllGlobals();
+    vi.restoreAllMocks();
   });
 
   /** Drain the queue and return the events the batch would have sent. */
@@ -87,4 +92,106 @@ describe("studioTelemetry — shared opt-out and canary properties", () => {
       "$feature/canary-test-one": "false",
     });
   });
+
+  it.each(["fetch", "beacon"] as const)(
+    "excludes project names from the complete serialized %s batch",
+    async (transport) => {
+      const projectName = "Launch #1? v2";
+      window.location.hash = buildProjectHash(projectName, { selSelector: "#private-element" });
+      const beacon = vi.fn((_url: string, _body: string) => true);
+      vi.stubGlobal("navigator", { userAgent: "test", sendBeacon: beacon });
+      for (const event of ["feature_used", "keyframe", "design_input", "toolbar_action"]) {
+        trackStudioEvent(event);
+      }
+      if (transport === "beacon") {
+        const { flushViaBeacon } = await import("./studioTelemetry");
+        flushViaBeacon();
+      } else {
+        await vi.runOnlyPendingTimersAsync();
+      }
+      const serialized =
+        transport === "beacon"
+          ? beacon.mock.calls[0]?.[1]
+          : (fetchMock.mock.calls[0]?.[1] as RequestInit)?.body;
+      expect(typeof serialized).toBe("string");
+      const body = serialized as string;
+      expect(body).not.toContain(projectName);
+      expect(body).not.toContain(encodeURIComponent(projectName));
+      expect(body).not.toContain("private-element");
+      expect(body).not.toContain("7aef12cc");
+      const payload = JSON.parse(body);
+      expect(payload.batch).toHaveLength(4);
+      for (const event of payload.batch) {
+        expect(event.properties.url_hash).toBe("project");
+        expect(event.properties.url_route_id).toMatch(/^[0-9a-f]{8}$/);
+      }
+    },
+  );
+
+  it.each([
+    ["", "home"],
+    ["#", "home"],
+    ["#unknown/Launch%20%231%3F%20v2?selection=secret", "other"],
+  ])("sends a finite route kind for %s", async (hash, routeKind) => {
+    window.location.hash = hash;
+    trackStudioEvent("thing_happened");
+    const events = await sentEvents();
+    expect(events[0]?.["properties"]).toMatchObject({ url_hash: routeKind });
+  });
+
+  it("keeps route identity stable across query changes and distinct across projects", async () => {
+    window.location.hash = buildProjectHash("Launch #1? v2");
+    trackStudioEvent("session_start");
+    window.location.hash = buildProjectHash("Launch #1? v2", { selSelector: "#another-element" });
+    trackStudioEvent("feature_used");
+    window.location.hash = buildProjectHash("Another launch");
+    trackStudioEvent("feature_used");
+    const events = await sentEvents();
+    const ids = events.map(
+      (event) => (event["properties"] as Record<string, unknown>)["url_route_id"],
+    );
+    expect(ids[0]).toMatch(/^[0-9a-f]{8}$/);
+    expect(ids[1]).toBe(ids[0]);
+    expect(ids[2]).not.toBe(ids[0]);
+    expect(ids[2]).toMatch(/^[0-9a-f]{8}$/);
+  });
+  it("reuses a route ID after reloading the same tab", async () => {
+    window.location.hash = buildProjectHash("Launch #1? v2");
+    trackStudioEvent("session_start");
+    const first = (await sentEvents())[0]?.properties as Record<string, unknown>;
+    vi.clearAllTimers();
+    vi.resetModules();
+    fetchMock.mockClear();
+    ({ trackStudioEvent } = await import("./studioTelemetry"));
+    trackStudioEvent("session_start");
+    const second = (await sentEvents())[0]?.properties as Record<string, unknown>;
+    expect(second.url_route_id).toBe(first.url_route_id);
+  });
+
+  it("assigns different random IDs to the same route in two tabs", async () => {
+    const random = vi.spyOn(crypto, "getRandomValues");
+    random.mockImplementationOnce((bytes) => {
+      (bytes as Uint8Array).set([1, 2, 3, 4]);
+      return bytes;
+    });
+    window.location.hash = buildProjectHash("Launch #1? v2");
+    trackStudioEvent("session_start");
+    const first = (await sentEvents())[0]?.properties as Record<string, unknown>;
+    // A second independent tab has its own sessionStorage and module instance.
+    sessionStorage.clear();
+    vi.clearAllTimers();
+    vi.resetModules();
+    fetchMock.mockClear();
+    random.mockImplementationOnce((bytes) => {
+      (bytes as Uint8Array).set([5, 6, 7, 8]);
+      return bytes;
+    });
+    ({ trackStudioEvent } = await import("./studioTelemetry"));
+    trackStudioEvent("session_start");
+    const second = (await sentEvents())[0]?.properties as Record<string, unknown>;
+    expect(first.url_route_id).toBe("01020304");
+    expect(second.url_route_id).toBe("05060708");
+    expect(second.url_route_id).not.toBe(first.url_route_id);
+    expect(random).toHaveBeenCalledTimes(2);
+  });
 });