@hyperframes/studio 0.7.103 → 0.7.105

package/src/utils/dragDebug.ts

@@ -0,0 +1,98 @@
+// Canvas drag diagnostics — grep [hf-drag]. Off by default; opt in per session
+// with `localStorage.setItem("hf-drag-debug", "1")` (then reload).
+//
+// A drag that "jumps" is a position that changed without the pointer asking. The
+// pointer delta, what snapping did to it, what each member was told to move, and
+// where each member actually ended up are logged at every stage, so the frame the
+// position diverges from the pointer is visible rather than inferred.
+import { makeStudioDebugLogger } from "./studioDebug";
+
+export const logDrag = makeStudioDebugLogger("drag");
+
+let moveN = 0;
+
+/** Per-pointermove logging, throttled: the first move then every 8th. */
+export function logDragMove(data: Record<string, unknown>): void {
+  logDrag("move", () => {
+    moveN += 1;
+    return moveN % 8 === 1 ? { n: moveN, ...data } : null;
+  });
+}
+
+export function resetDragMoveLog(): void {
+  moveN = 0;
+}
+
+/** Where these elements are rendered right now, in preview-document pixels. */
+export function readDragPositions(
+  elements: Array<{ key: string; element: HTMLElement }>,
+): Record<string, string> {
+  const positions: Record<string, string> = {};
+  for (const { key, element } of elements) {
+    const rect = element.getBoundingClientRect();
+    positions[key] = `${Math.round(rect.left)},${Math.round(rect.top)}`;
+  }
+  return positions;
+}
+
+/**
+ * Members whose screen movement disagrees with the rest of the group this frame.
+ *
+ * A group moves as one object, so every member travels the same distance; one
+ * that does not is the whole bug, and averaged-looking samples hide it. Compares
+ * each member's movement against the group's median and names the outliers, so a
+ * single element drifting shows up as itself rather than as "the group jumped".
+ */
+export function findNonRigidMembers(
+  before: Record<string, string>,
+  after: Record<string, string>,
+): string[] {
+  const moves = new Map<string, string>();
+  for (const key of Object.keys(after)) {
+    const from = before[key]?.split(",").map(Number);
+    const to = after[key]?.split(",").map(Number);
+    if (!from || !to || from.length !== 2 || to.length !== 2) continue;
+    moves.set(key, `${Math.round(to[0]! - from[0]!)},${Math.round(to[1]! - from[1]!)}`);
+  }
+  const counts = new Map<string, number>();
+  for (const move of moves.values()) counts.set(move, (counts.get(move) ?? 0) + 1);
+  let common = "";
+  let best = 0;
+  for (const [move, count] of counts) {
+    if (count > best) [common, best] = [move, count];
+  }
+  return [...moves]
+    .filter(([, move]) => move !== common)
+    .map(([key, move]) => `${key.split("|")[2] ?? key} moved ${move}, group moved ${common}`);
+}
+
+/**
+ * Sample the group now and again after the commit has had time to land. The drop
+ * is the one moment a jump can hide: the source write, the preview reload and the
+ * timeline resume all happen within a few frames of each other, and any of them
+ * can put the elements back where they started before the new position arrives.
+ */
+export function logDragSettle(
+  stage: string,
+  elements: Array<{ key: string; element: HTMLElement }>,
+): void {
+  logDrag(stage, () => {
+    const at = readDragPositions(elements);
+    const win = elements[0]?.element.ownerDocument.defaultView;
+    if (win) {
+      win.setTimeout(
+        () => logDrag(`${stage}+120ms`, () => ({ at: readDragPositions(elements) })),
+        120,
+      );
+      win.setTimeout(
+        () => logDrag(`${stage}+400ms`, () => ({ at: readDragPositions(elements) })),
+        400,
+      );
+      win.setTimeout(
+        () => logDrag(`${stage}+900ms`, () => ({ at: readDragPositions(elements) })),
+        900,
+      );
+    }
+    return { at };
+  });
+}

package/src/utils/razorSplitTransaction.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../player";
 import { buildAtomicCutIntents, runAtomicCutTransaction } from "./razorSplitTransaction";
+import { consumeStudioWriteToken, resetStudioWriteTokens } from "./studioFileVersion";
 
 const element = (over: Partial<TimelineElement> = {}): TimelineElement => ({
   id: "clip",
@@ -14,7 +15,10 @@ const element = (over: Partial<TimelineElement> = {}): TimelineElement => ({
   ...over,
 });
 
-afterEach(() => vi.unstubAllGlobals());
+afterEach(() => {
+  resetStudioWriteTokens();
+  vi.unstubAllGlobals();
+});
 
 describe("buildAtomicCutIntents", () => {
   it("deduplicates runtime aliases but keeps repeated authored hosts distinct", () => {
@@ -45,12 +49,16 @@ describe("buildAtomicCutIntents", () => {
 });
 
 function installCutServer(options: { status?: number } = {}) {
-  const requests: Array<{ url: string; body?: unknown }> = [];
+  const requests: Array<{ url: string; body?: unknown; headers?: HeadersInit }> = [];
   vi.stubGlobal(
     "fetch",
     vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
       const url = String(input);
-      requests.push({ url, body: init?.body ? JSON.parse(String(init.body)) : undefined });
+      requests.push({
+        url,
+        body: init?.body ? JSON.parse(String(init.body)) : undefined,
+        headers: init?.headers,
+      });
       if (url.includes("/files/")) {
         return new Response(JSON.stringify({ content: "before", version: '"v0"' }), {
           status: 200,
@@ -109,6 +117,10 @@ describe("runAtomicCutTransaction", () => {
       "/api/projects/launch%2Fdemo/files/index.html",
       "/api/projects/launch%2Fdemo/file-mutations/split-batch",
     ]);
+    const splitRequest = requests.find((request) => request.url.includes("split-batch"));
+    const writeToken = new Headers(splitRequest?.headers).get("X-Hyperframes-Write-Token");
+    expect(writeToken).toMatch(/^cut:/);
+    expect(consumeStudioWriteToken(writeToken)).toBe(true);
     expect(writeProjectFile).not.toHaveBeenCalled();
     expect(recordEdit).toHaveBeenCalledWith({
       label: "Split timeline clip",

package/src/utils/razorSplitTransaction.ts

@@ -3,6 +3,7 @@ import type { RecordEditInput } from "../hooks/timelineEditingHelpers";
 import { buildPatchTarget } from "./timelineElementSplit";
 import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
 import { buildProjectApiPath } from "./projectRouting";
+import { markStudioWriteToken } from "./studioFileVersion";
 
 type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
 
@@ -117,6 +118,7 @@ async function requestAtomicCut(
     });
   }
   const transactionToken = `cut:${crypto.randomUUID()}`;
+  markStudioWriteToken(transactionToken);
   const response = await fetch(buildProjectApiPath(projectId, "/file-mutations/split-batch"), {
     method: "POST",
     headers: {

package/src/utils/reloadDebug.ts

@@ -0,0 +1,10 @@
+// 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.
+import { makeStudioDebugLogger } from "./studioDebug";
+
+export const logReload = makeStudioDebugLogger("reload");

package/src/utils/resizeDebug.ts

@@ -1,33 +1,18 @@
 // Resize/gesture diagnostics — grep [hf-resize]. Off by default; opt in per
 // session with `localStorage.setItem("hf-resize-debug", "1")` (then reload).
-// Granular per-move/per-gesture tracing that complements the always-on
-// [hf-commit] transaction telemetry in gestureTransaction.ts.
-let moveN = 0;
-let enabled: boolean | null = null;
+// Granular per-move/per-gesture tracing for resize investigation.
+import { makeStudioDebugLogger } from "./studioDebug";
 
-function isEnabled(): boolean {
-  if (enabled === null) {
-    try {
-      enabled = localStorage.getItem("hf-resize-debug") === "1";
-    } catch {
-      enabled = false;
-    }
-  }
-  return enabled;
-}
+export const logResize = makeStudioDebugLogger("resize");
 
-export function logResize(stage: string, data: Record<string, unknown>): void {
-  if (!isEnabled()) return;
-  console.log(
-    `[hf-resize] ${JSON.stringify({ stage, t: Math.round(performance.now()), ...data })}`,
-  );
-}
+let moveN = 0;
 
 /** Per-pointermove logging, throttled: first move then every 8th. */
 export function logResizeMove(data: Record<string, unknown>): void {
-  if (!isEnabled()) return;
-  moveN += 1;
-  if (moveN % 8 === 1) logResize("move", { n: moveN, ...data });
+  logResize("move", () => {
+    moveN += 1;
+    return moveN % 8 === 1 ? { n: moveN, ...data } : null;
+  });
 }
 
 export function resetResizeMoveLog(): void {
@@ -36,11 +21,10 @@ export function resetResizeMoveLog(): void {
 
 /** Snapshot the element's live geometry now and again after 200ms (jump detector). */
 export function logResizeSettle(el: HTMLElement, tag: string): void {
-  if (!isEnabled()) return;
-  const snap = (phase: string) => {
+  const snapshot = (phase: string) => {
     const r = el.getBoundingClientRect();
     const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
-    logResize("settle", {
+    return {
       tag,
       phase,
       rect: { x: r.x, y: r.y, w: r.width, h: r.height },
@@ -48,8 +32,14 @@ export function logResizeSettle(el: HTMLElement, tag: string): void {
       cssH: cs?.height,
       transform: cs?.transform,
       inlineStyle: el.getAttribute("style"),
-    });
+    };
   };
-  snap("t0");
-  setTimeout(() => snap("t200"), 200);
+  logResize("settle", () => {
+    const current = snapshot("t0");
+    el.ownerDocument.defaultView?.setTimeout(
+      () => logResize("settle", () => snapshot("t200")),
+      200,
+    );
+    return current;
+  });
 }

package/src/utils/selectDebug.ts

@@ -0,0 +1,9 @@
+// Canvas selection diagnostics — grep [hf-select]. Off by default; opt in with
+// `localStorage.setItem("hf-select-debug", "1")` (then reload).
+//
+// Selection failures are silent by nature: a handler returns early and nothing
+// happens, which looks identical to a click that never landed. These lines say
+// which branch ran and what it decided.
+import { makeStudioDebugLogger } from "./studioDebug";
+
+export const logSelect = makeStudioDebugLogger("select");

package/src/utils/studioDebug.test.ts

@@ -0,0 +1,32 @@
+// @vitest-environment happy-dom
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { makeStudioDebugLogger } from "./studioDebug";
+
+describe("makeStudioDebugLogger", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("does no console work while its channel is disabled", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const buildDetails = vi.fn(() => ({ expensive: true }));
+
+    makeStudioDebugLogger("commit")("persisted", buildDetails);
+
+    expect(buildDetails).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it("logs only after its exact channel is enabled", () => {
+    localStorage.setItem("hf-commit-debug", "1");
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    makeStudioDebugLogger("commit")("persisted", { mutations: 2 });
+
+    expect(log).toHaveBeenCalledOnce();
+    expect(log.mock.calls[0]?.[0]).toContain('[hf-commit] {"stage":"persisted"');
+    expect(log.mock.calls[0]?.[0]).toContain('"mutations":2');
+  });
+});

package/src/utils/studioDebug.ts

@@ -0,0 +1,30 @@
+// Opt-in diagnostic channels — one per question worth tracing, all off by
+// default. Turn one on for the session with `localStorage.setItem("hf-<name>-debug",
+// "1")` and reload, then grep the console for `[hf-<name>]`.
+// Live channels: reload, select, drag, resize, commit.
+//
+// These exist because the interesting failures here are decisions, not crashes:
+// a preview that reloads when it should not, a shift-click that selects nothing.
+// Nothing is thrown and nothing is logged by default, so without a trace of the
+// decision the only way to find the cause is to guess.
+type DebugDetails = Record<string, unknown> | (() => Record<string, unknown> | null);
+type DebugLogger = (stage: string, data?: DebugDetails) => void;
+
+export function makeStudioDebugLogger(name: string): DebugLogger {
+  let enabled: boolean | null = null;
+  return (stage, data = {}) => {
+    if (enabled === null) {
+      try {
+        enabled = localStorage.getItem(`hf-${name}-debug`) === "1";
+      } catch {
+        enabled = false;
+      }
+    }
+    if (!enabled) return;
+    const details = typeof data === "function" ? data() : data;
+    if (!details) return;
+    console.log(
+      `[hf-${name}] ${JSON.stringify({ stage, t: Math.round(performance.now()), ...details })}`,
+    );
+  };
+}

package/src/utils/studioFileVersion.ts

@@ -48,6 +48,21 @@ export async function studioExpectedFileVersion(
   return versions.get(path);
 }
 
-export function createStudioWriteToken(): string {
+function createStudioWriteToken(): string {
   return globalThis.crypto.randomUUID();
 }
+
+/**
+ * Headers that claim the write a mutation request is about to make as our own.
+ *
+ * The token is marked BEFORE the request goes out on purpose: the server writes
+ * the file and the watcher broadcasts it while the request is still in flight, so
+ * a token marked from the response can arrive after the echo it was meant to
+ * match. An unmatched echo reads as an external change and costs a full preview
+ * reload, which the user sees as a flash right after their own edit.
+ */
+export function studioWriteHeaders(): Record<string, string> {
+  const token = createStudioWriteToken();
+  markStudioWriteToken(token);
+  return { "X-Hyperframes-Write-Token": token };
+}

package/src/utils/studioUrlState.test.ts

@@ -77,8 +77,11 @@ function renderStudioUrlStateHarness(
     rightCollapsed: true,
     activeCompPathHydrated: true,
     domEditSelection: null,
+    domEditGroupSelections: [],
+    applyMarqueeSelection: () => {},
     buildDomSelectionFromTarget: () => Promise.resolve(null),
     applyDomSelection: () => {},
+    setRightPanelTab: () => {},
     initialState: {
       activeCompPath: null,
       currentTime: 4.2,
@@ -116,6 +119,12 @@ function StudioUrlStateHarness(props: Parameters<typeof useStudioUrlState>[0]) {
   return null;
 }
 
+function previewIframeFor(contentDocument: Document): HTMLIFrameElement {
+  const iframe = document.createElement("iframe");
+  Object.defineProperty(iframe, "contentDocument", { value: contentDocument });
+  return iframe;
+}
+
 describe("studio url state", () => {
   it("parses persisted studio state from project hash", () => {
     const state = parseStudioUrlStateFromHash(
@@ -132,7 +141,135 @@ describe("studio url state", () => {
       id: "hero",
       selector: undefined,
       selectorIndex: undefined,
+      group: undefined,
+    });
+  });
+
+  /**
+   * A link to a bug hit while several elements were selected has to carry the
+   * whole selection. Without the group the URL reopens one element, the report
+   * cannot be reproduced from it, and it reads as "works for me".
+   */
+  it("round-trips a multi-selection through the hash", () => {
+    const hash = buildStudioHash("demo", {
+      activeCompPath: null,
+      currentTime: null,
+      rightPanelTab: null,
+      rightCollapsed: null,
+      timelineVisible: null,
+      selection: {
+        sourceFile: "index.html",
+        id: "chip",
+        group: [
+          { sourceFile: "index.html", id: "card" },
+          { sourceFile: "index.html", selector: ".dot", selectorIndex: 1 },
+        ],
+      },
+    });
+
+    expect(parseStudioUrlStateFromHash(hash).selection?.group).toEqual([
+      { sourceFile: "index.html", id: "card" },
+      { sourceFile: "index.html", selector: ".dot", selectorIndex: 1 },
+    ]);
+  });
+
+  it("reads a single selection as having no group", () => {
+    const hash = parseStudioUrlStateFromHash("#project/demo?v=1&selFile=index.html&selId=hero");
+    expect(hash.selection?.group).toBeUndefined();
+  });
+
+  it("restores selector-based multi-selection members from the hash", async () => {
+    const previewDoc = document.implementation.createHTMLDocument("preview");
+    const primaryElement = previewDoc.createElement("div");
+    primaryElement.id = "hero";
+    const memberElement = previewDoc.createElement("div");
+    memberElement.className = "dot";
+    previewDoc.body.append(primaryElement, memberElement);
+    const primary = { element: primaryElement, id: "hero", sourceFile: "index.html" };
+    const member = {
+      element: memberElement,
+      selector: ".dot",
+      selectorIndex: 0,
+      sourceFile: "index.html",
+    };
+    const applyMarqueeSelection = vi.fn();
+
+    const harness = renderStudioUrlStateHarness({
+      previewIframeRef: {
+        current: previewIframeFor(previewDoc),
+      },
+      applyMarqueeSelection,
+      buildDomSelectionFromTarget: (target) =>
+        Promise.resolve(target === primaryElement ? primary : member),
+      initialState: {
+        activeCompPath: null,
+        currentTime: null,
+        rightPanelTab: null,
+        rightCollapsed: null,
+        timelineVisible: null,
+        selection: {
+          sourceFile: "index.html",
+          id: "hero",
+          group: [{ sourceFile: "index.html", selector: ".dot", selectorIndex: 0 }],
+        },
+      },
+    });
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(applyMarqueeSelection).toHaveBeenCalledWith([primary, member], false);
+    harness.unmount();
+  });
+
+  it("does not let an older async URL selection overwrite a newer hash", async () => {
+    const previewDoc = document.implementation.createHTMLDocument("preview");
+    const firstElement = previewDoc.createElement("div");
+    firstElement.id = "first";
+    const secondElement = previewDoc.createElement("div");
+    secondElement.id = "second";
+    previewDoc.body.append(firstElement, secondElement);
+    const first = { element: firstElement, id: "first", sourceFile: "index.html" };
+    const second = { element: secondElement, id: "second", sourceFile: "index.html" };
+    let resolveFirst = (_selection: typeof first) => undefined;
+    const firstResolution = new Promise<typeof first>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const applyDomSelection = vi.fn();
+    const harness = renderStudioUrlStateHarness({
+      previewIframeRef: { current: previewIframeFor(previewDoc) },
+      applyDomSelection,
+      buildDomSelectionFromTarget: (target) =>
+        target === firstElement ? firstResolution : Promise.resolve(second),
+      initialState: {
+        activeCompPath: null,
+        currentTime: null,
+        rightPanelTab: null,
+        rightCollapsed: null,
+        timelineVisible: null,
+        selection: null,
+      },
+    });
+
+    act(() => {
+      window.history.replaceState(null, "", "#project/demo?v=1&selId=first");
+      window.dispatchEvent(new HashChangeEvent("hashchange"));
+      window.history.replaceState(null, "", "#project/demo?v=1&selId=second");
+      window.dispatchEvent(new HashChangeEvent("hashchange"));
+    });
+    await act(async () => {
+      await Promise.resolve();
     });
+    expect(applyDomSelection).toHaveBeenCalled();
+    expect(applyDomSelection.mock.calls.every(([selection]) => selection === second)).toBe(true);
+    const appliedBeforeOlderResolution = applyDomSelection.mock.calls.length;
+
+    await act(async () => {
+      resolveFirst(first);
+      await firstResolution;
+    });
+    expect(applyDomSelection).toHaveBeenCalledTimes(appliedBeforeOlderResolution);
+    harness.unmount();
   });
 
   it("builds a project hash with persisted studio state", () => {
@@ -228,7 +365,7 @@ describe("studio url state", () => {
 
     const harness = renderStudioUrlStateHarness({
       previewIframeRef: {
-        current: { contentDocument: previewDoc } as HTMLIFrameElement,
+        current: previewIframeFor(previewDoc),
       },
       rightPanelTab: "design",
       rightCollapsed: false,
@@ -279,6 +416,31 @@ describe("studio url state", () => {
     expect(window.location.hash).toContain("t=4.2");
     expect(window.location.hash).toContain("selId=hero");
 
+    const selectorMember = {
+      ...restoredSelection,
+      element: document.createElement("div"),
+      id: "",
+      selector: ".dot",
+      selectorIndex: 1,
+      label: "Dot",
+    };
+    harness.rerender({
+      currentTime: 4.2,
+      domEditSelection: restoredSelection,
+      domEditGroupSelections: [restoredSelection, selectorMember],
+    });
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(parseStudioUrlStateFromHash(window.location.hash).selection?.group).toEqual([
+      {
+        sourceFile: "index.html",
+        id: undefined,
+        selector: ".dot",
+        selectorIndex: 1,
+      },
+    ]);
+
     harness.unmount();
   });
 });

package/src/utils/studioUrlState.ts

@@ -2,13 +2,23 @@ import type { RightPanelTab } from "./studioHelpers";
 import { buildProjectHash, parseProjectHashRoute } from "./projectRouting";
 import { roundTo3 } from "./rounding";
 
-export interface StudioUrlSelectionState {
+export interface StudioUrlSelectionTarget {
   sourceFile?: string;
   id?: string;
   selector?: string;
   selectorIndex?: number;
 }
 
+export interface StudioUrlSelectionState extends StudioUrlSelectionTarget {
+  /**
+   * The other members of a multi-selection, primary excluded.
+   * A link to a bug in a group edit is only reproducible if it carries the group;
+   * without this, opening the URL lands on one element and the report reads as
+   * "works for me".
+   */
+  group?: StudioUrlSelectionTarget[];
+}
+
 export interface StudioUrlState {
   activeCompPath: string | null;
   currentTime: number | null;
@@ -63,19 +73,63 @@ function parseTab(value: string | null): RightPanelTab | null {
   return VALID_TABS.includes(value as RightPanelTab) ? (value as RightPanelTab) : null;
 }
 
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function normalizedIndex(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.max(0, Math.floor(value))
+    : undefined;
+}
+
+function parseSelectionTarget(value: unknown): StudioUrlSelectionTarget | null {
+  if (!value || typeof value !== "object") return null;
+  const sourceFile = optionalString(Reflect.get(value, "sourceFile"));
+  const id = optionalString(Reflect.get(value, "id"));
+  const selector = optionalString(Reflect.get(value, "selector"));
+  if (!id && !selector) return null;
+  return {
+    sourceFile,
+    id,
+    selector,
+    selectorIndex: normalizedIndex(Reflect.get(value, "selectorIndex")),
+  };
+}
+
+/** The other members of a multi-selection, dropping invalid hand-edited entries. */
+function parseGroup(value: string | null): StudioUrlSelectionTarget[] | undefined {
+  if (!value) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    // Compatibility with links produced by the first id-only implementation.
+    const legacy = value
+      .split(",")
+      .map((id) => id.trim())
+      .filter(Boolean)
+      .map((id) => ({ id }));
+    return legacy.length > 0 ? legacy : undefined;
+  }
+  if (!Array.isArray(parsed)) return undefined;
+  const targets = parsed.map(parseSelectionTarget).filter((target) => target !== null);
+  return targets.length > 0 ? targets : undefined;
+}
+
 function normalizeSelection(params: URLSearchParams): StudioUrlSelectionState | null {
   const sourceFile = params.get("selFile") || undefined;
   const id = params.get("selId") || undefined;
   const selector = params.get("selSelector") || undefined;
-  const selectorIndex = parseNumber(params.get("selIndex"));
-
   if (!sourceFile && !id && !selector) return null;
 
+  const selectorIndex = parseNumber(params.get("selIndex"));
   return {
     sourceFile,
     id,
     selector,
     selectorIndex: selectorIndex != null ? Math.max(0, Math.floor(selectorIndex)) : undefined,
+    group: parseGroup(params.get("selGroup")),
   };
 }
 
@@ -130,6 +184,9 @@ export function buildStudioHash(projectId: string, state: StudioUrlState): strin
     if (typeof state.selection.selectorIndex === "number") {
       params.set("selIndex", String(Math.max(0, Math.floor(state.selection.selectorIndex))));
     }
+    if (state.selection.group?.length) {
+      params.set("selGroup", JSON.stringify(state.selection.group));
+    }
   }
 
   return buildProjectHash(projectId, params);

package/src/utils/timelineCompositionInsert.ts

@@ -2,6 +2,7 @@ import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
 import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 import type { RecordEditInput } from "./studioFileHistory";
 import { buildProjectApiPath } from "./projectRouting";
+import { studioWriteHeaders } from "./studioFileVersion";
 
 interface TimelineCompositionInsertionResult {
   path: string;
@@ -34,7 +35,7 @@ async function insertTimelineComposition(input: {
     ),
     {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
       body: JSON.stringify({
         sourcePath: input.sourcePath,
         start: input.start,