@hyperframes/studio 0.7.55 → 0.7.57

package/src/hooks/gestureTransaction.test.ts

@@ -0,0 +1,311 @@
+// @vitest-environment happy-dom
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
+import { isGestureTransactionCommit, runGestureTransaction } from "./gestureTransaction";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const trackStudioEventMock = vi.mocked(trackStudioEvent);
+
+function rect(x: number, y: number, width: number, height: number): DOMRect {
+  return { x, y, width, height } as DOMRect;
+}
+
+function runTwoMutationTransaction(
+  underlying: CommitMutation,
+  firstSelection: DomEditSelection,
+  secondSelection = firstSelection,
+): Promise<void> {
+  return runGestureTransaction({
+    element: firstSelection.element,
+    label: "Resize layer",
+    settle: vi.fn(),
+    persist: async (commit) => {
+      const commitMutation = commit(underlying);
+      await commitMutation(firstSelection, { type: "first" }, { label: "First" });
+      await commitMutation(secondSelection, { type: "last" }, { label: "Last", softReload: true });
+    },
+    restore: vi.fn(),
+    skipPixelAssert: true,
+  });
+}
+
+describe("runGestureTransaction", () => {
+  beforeEach(() => {
+    trackStudioEventMock.mockReset();
+  });
+
+  it("settles synchronously before persist reaches its first await", async () => {
+    const order: string[] = [];
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    const transaction = runGestureTransaction({
+      element: document.createElement("div"),
+      label: "Resize layer",
+      settle: () => order.push("settle"),
+      persist: async () => {
+        order.push("persist");
+        await gate;
+        order.push("persisted");
+      },
+      restore: vi.fn(),
+      skipPixelAssert: true,
+    });
+
+    expect(order).toEqual(["settle", "persist"]);
+    release();
+    await transaction;
+    expect(order).toEqual(["settle", "persist", "persisted"]);
+  });
+
+  it("injects one coalesce key and reloads only the final mutation", async () => {
+    const element = document.createElement("div");
+    const selection = { element, id: "clip" } as DomEditSelection;
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+    const batch = vi.fn<NonNullable<CommitMutation["batch"]>>().mockResolvedValue(undefined);
+    underlying.batch = batch;
+    const now = vi.spyOn(performance, "now").mockReturnValueOnce(100).mockReturnValueOnce(112.6);
+
+    await runTwoMutationTransaction(underlying, selection);
+
+    expect(underlying).not.toHaveBeenCalled();
+    expect(batch).toHaveBeenCalledTimes(1);
+    const [calls, mergedOptions] = batch.mock.calls[0]!;
+    const firstOptions = calls[0]!.options;
+    const lastOptions = calls[1]!.options;
+    expect(calls.map(({ mutation }) => mutation)).toEqual([{ type: "first" }, { type: "last" }]);
+    expect(firstOptions.coalesceKey).toBe(lastOptions.coalesceKey);
+    expect(firstOptions.coalesceKey).toMatch(/^tx:Resize layer:\d+$/);
+    expect(firstOptions.coalesceMs).toBe(Number.POSITIVE_INFINITY);
+    expect(lastOptions.coalesceMs).toBe(Number.POSITIVE_INFINITY);
+    expect(firstOptions).toMatchObject({ skipReload: true });
+    expect(firstOptions.softReload).toBeUndefined();
+    expect(lastOptions).toMatchObject({ softReload: true });
+    expect(lastOptions.skipReload).toBeUndefined();
+    // The transaction owns the undo label — the per-mutation "First"/"Last"
+    // labels are overridden so the coalesced entry reads "Resize layer".
+    expect(firstOptions.label).toBe("Resize layer");
+    expect(lastOptions.label).toBe("Resize layer");
+    expect(mergedOptions).toMatchObject({
+      label: "Resize layer",
+      coalesceKey: firstOptions.coalesceKey,
+      coalesceMs: Number.POSITIVE_INFINITY,
+      softReload: true,
+    });
+    expect(mergedOptions.skipReload).toBeUndefined();
+    expect(trackStudioEventMock).toHaveBeenCalledWith("commit_transaction", {
+      label: "Resize layer",
+      mutation_count: 2,
+      reload_count: 1,
+      duration_ms: 13,
+      pixel_asserted: false,
+    });
+    now.mockRestore();
+  });
+
+  it("reports one reload when a batch collapses two softReload commits", async () => {
+    const element = document.createElement("div");
+    const selection = { element, id: "clip", sourceFile: "index.html" } as DomEditSelection;
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+    underlying.batch = vi.fn<NonNullable<CommitMutation["batch"]>>().mockResolvedValue(undefined);
+
+    // Both a resize's size and offset persists request softReload; the batch is
+    // one write and one reload, so telemetry must report reload_count 1, not 2.
+    await runGestureTransaction({
+      element,
+      label: "Resize layer",
+      settle: vi.fn(),
+      persist: async (commit) => {
+        const commitMutation = commit(underlying);
+        await commitMutation(selection, { type: "size" }, { label: "Resize", softReload: true });
+        await commitMutation(selection, { type: "offset" }, { label: "Move", softReload: true });
+      },
+      restore: vi.fn(),
+      skipPixelAssert: true,
+    });
+
+    expect(underlying.batch).toHaveBeenCalledTimes(1);
+    expect(trackStudioEventMock).toHaveBeenCalledWith(
+      "commit_transaction",
+      expect.objectContaining({ mutation_count: 2, reload_count: 1 }),
+    );
+  });
+
+  it("falls back to sequential dispatch when the commit has no batch capability", async () => {
+    const element = document.createElement("div");
+    const selection = { element, id: "clip" } as DomEditSelection;
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+
+    await runTwoMutationTransaction(underlying, selection);
+
+    expect(underlying).toHaveBeenCalledTimes(2);
+    expect(underlying.mock.calls[0]![2]).toMatchObject({ skipReload: true });
+    expect(underlying.mock.calls[1]![2]).toMatchObject({ softReload: true });
+  });
+
+  it("keeps a single mutation on the original commit path", async () => {
+    const element = document.createElement("div");
+    const selection = { element, id: "clip" } as DomEditSelection;
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+    const batch = vi.fn<NonNullable<CommitMutation["batch"]>>().mockResolvedValue(undefined);
+    underlying.batch = batch;
+
+    await runGestureTransaction({
+      element,
+      label: "Move layer",
+      settle: vi.fn(),
+      persist: async (commit) => {
+        await commit(underlying)(
+          selection,
+          { type: "update-property" },
+          { label: "Move", softReload: true },
+        );
+      },
+      restore: vi.fn(),
+      skipPixelAssert: true,
+    });
+
+    expect(underlying).toHaveBeenCalledTimes(1);
+    expect(batch).not.toHaveBeenCalled();
+  });
+
+  it("does not batch mutations for different source files", async () => {
+    const element = document.createElement("div");
+    const firstSelection = { element, id: "a", sourceFile: "a.html" } as DomEditSelection;
+    const secondSelection = { element, id: "b", sourceFile: "b.html" } as DomEditSelection;
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+    const batch = vi.fn<NonNullable<CommitMutation["batch"]>>().mockResolvedValue(undefined);
+    underlying.batch = batch;
+
+    await runTwoMutationTransaction(underlying, firstSelection, secondSelection);
+
+    expect(batch).not.toHaveBeenCalled();
+    expect(underlying).toHaveBeenCalledTimes(2);
+  });
+
+  it("identifies transaction-owned commit wrappers without marking their underlying commit", async () => {
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+    let wrapped: CommitMutation | null = null;
+
+    await runGestureTransaction({
+      element: document.createElement("div"),
+      label: "Move layer",
+      settle: vi.fn(),
+      persist: async (commit) => {
+        wrapped = commit(underlying);
+      },
+      restore: vi.fn(),
+      skipPixelAssert: true,
+    });
+
+    expect(isGestureTransactionCommit(underlying)).toBe(false);
+    expect(isGestureTransactionCommit(wrapped!)).toBe(true);
+  });
+
+  it("restores exactly once and rethrows a persist failure", async () => {
+    const error = new Error("persist failed with secret selector #private-layer");
+    error.name = "PersistenceError";
+    const restore = vi.fn();
+    const element = document.createElement("div");
+    const selection = { element, id: "clip" } as DomEditSelection;
+    const underlying = vi.fn<CommitMutation>().mockResolvedValue(undefined);
+
+    await expect(
+      runGestureTransaction({
+        element,
+        label: "Resize layer",
+        settle: vi.fn(),
+        persist: async (commit) => {
+          await commit(underlying)(selection, { type: "position" }, { label: "Position" });
+          throw error;
+        },
+        restore,
+        skipPixelAssert: true,
+      }),
+    ).rejects.toBe(error);
+    expect(restore).toHaveBeenCalledTimes(1);
+    expect(trackStudioEventMock).toHaveBeenCalledWith("commit_transaction_failed", {
+      label: "Resize layer",
+      mutation_count: 1,
+      error_name: "PersistenceError",
+      restore_ran: true,
+    });
+    const failureProperties = trackStudioEventMock.mock.calls.find(
+      ([event]) => event === "commit_transaction_failed",
+    )?.[1];
+    expect(JSON.stringify(failureProperties)).not.toContain(error.message);
+    expect(JSON.stringify(failureProperties)).not.toContain("#private-layer");
+  });
+
+  it("reports when persistence changes pixels", async () => {
+    const element = document.createElement("div");
+    const getRect = vi
+      .spyOn(element, "getBoundingClientRect")
+      .mockReturnValueOnce(rect(10.04, 20.05, 100.05, 80.05))
+      .mockReturnValueOnce(rect(11.19, 17.89, 100.29, 78.99));
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const now = vi.spyOn(performance, "now").mockReturnValueOnce(50).mockReturnValueOnce(58.44);
+
+    await runGestureTransaction({
+      element,
+      label: "Resize layer",
+      settle: vi.fn(),
+      persist: async () => undefined,
+      restore: vi.fn(),
+    });
+
+    expect(getRect).toHaveBeenCalledTimes(2);
+    expect(error).toHaveBeenCalledWith(
+      "[hf-commit] persist changed pixels",
+      expect.objectContaining({
+        label: "Resize layer",
+        delta: expect.objectContaining({ x: expect.any(Number) }),
+      }),
+    );
+    expect(trackStudioEventMock).toHaveBeenCalledWith("commit_invariant_violation", {
+      label: "Resize layer",
+      delta_x: 1.2,
+      delta_y: -2.2,
+      delta_w: 0.2,
+      delta_h: -1.1,
+      mutation_count: 0,
+      reload_count: 0,
+      duration_ms: 8,
+    });
+    expect(trackStudioEventMock).toHaveBeenCalledWith(
+      "commit_transaction",
+      expect.objectContaining({ pixel_asserted: true }),
+    );
+    now.mockRestore();
+    error.mockRestore();
+  });
+
+  it("skips the pixel assertion for live position tweens", async () => {
+    const element = document.createElement("div");
+    const getRect = vi.spyOn(element, "getBoundingClientRect");
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await runGestureTransaction({
+      element,
+      label: "Resize layer",
+      settle: vi.fn(),
+      persist: async () => undefined,
+      restore: vi.fn(),
+      skipPixelAssert: true,
+    });
+
+    expect(getRect).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalledWith("[hf-commit] persist changed pixels", expect.anything());
+    expect(trackStudioEventMock).not.toHaveBeenCalledWith(
+      "commit_invariant_violation",
+      expect.anything(),
+    );
+    error.mockRestore();
+  });
+});

package/src/hooks/gestureTransaction.ts

@@ -0,0 +1,199 @@
+import type {
+  CommitMutation,
+  CommitMutationCall,
+  CommitMutationOptions,
+} from "./gsapScriptCommitTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+type PixelRect = Pick<DOMRect, "x" | "y" | "width" | "height">;
+
+export type TxCommit = (commitMutation: CommitMutation) => CommitMutation;
+
+export interface GestureTransaction {
+  element: HTMLElement;
+  label: string;
+  settle(): void;
+  persist(commit: TxCommit): Promise<void>;
+  restore(): void;
+  skipPixelAssert?: boolean;
+}
+
+let transactionCounter = 0;
+const transactionCommits = new WeakSet<CommitMutation>();
+
+/** Whether a commit function already belongs to an active gesture transaction. */
+export function isGestureTransactionCommit(commitMutation: CommitMutation): boolean {
+  return transactionCommits.has(commitMutation);
+}
+
+function readPixelRect(element: HTMLElement): PixelRect {
+  const { x, y, width, height } = element.getBoundingClientRect();
+  return { x, y, width, height };
+}
+
+function transactionOptions(
+  options: CommitMutationOptions,
+  coalesceKey: string,
+  label: string,
+): CommitMutationOptions {
+  // The transaction owns the undo label: every wrapped mutation records under
+  // `label`, so the coalesced entry reads as the gesture (e.g. "Resize layer")
+  // rather than whichever sub-mutation happened to land last (the offset
+  // persist's "Move layer").
+  const { coalesceKey: _coalesceKey, skipReload: _skipReload, softReload, ...rest } = options;
+  return softReload
+    ? { ...rest, label, softReload: true, coalesceKey, coalesceMs: Number.POSITIVE_INFINITY }
+    : { ...rest, label, skipReload: true, coalesceKey, coalesceMs: Number.POSITIVE_INFINITY };
+}
+
+function pixelDelta(before: PixelRect, after: PixelRect): PixelRect {
+  return {
+    x: after.x - before.x,
+    y: after.y - before.y,
+    width: after.width - before.width,
+    height: after.height - before.height,
+  };
+}
+
+function exceedsPixelTolerance(delta: PixelRect): boolean {
+  return Object.values(delta).some((value) => Math.abs(value) > 1);
+}
+
+function roundToOneDecimal(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+type BufferedCommit = CommitMutationCall & { dispatch: CommitMutation };
+
+function mergeTransactionOptions(calls: BufferedCommit[]): CommitMutationOptions {
+  const reloadCall = calls.find(({ options }) => options.softReload);
+  const source = reloadCall?.options ?? calls.at(-1)?.options;
+  if (!source) throw new Error("Cannot merge an empty gesture transaction");
+  const { skipReload: _skipReload, instantPatch: _instantPatch, ...options } = source;
+  return reloadCall ? { ...options, softReload: true } : { ...options, skipReload: true };
+}
+
+/**
+ * Dispatch a transaction's buffered commits and return the number of preview
+ * reloads that ACTUALLY happened — a batch collapses every buffered softReload
+ * into one reload, so reload telemetry reflects the real cost, not the count of
+ * softReload requests.
+ */
+function reloadsRequested(calls: BufferedCommit[]): number {
+  return calls.filter(({ options }) => options.softReload).length;
+}
+
+async function dispatchBufferedCommits(calls: BufferedCommit[]): Promise<number> {
+  const first = calls[0];
+  if (!first) return 0;
+  if (calls.length === 1) {
+    await first.dispatch(first.selection, first.mutation, first.options);
+    return reloadsRequested(calls);
+  }
+  const canBatch = calls.every(
+    ({ dispatch, selection }) =>
+      dispatch === first.dispatch && selection.sourceFile === first.selection.sourceFile,
+  );
+  if (canBatch && first.dispatch.batch) {
+    await first.dispatch.batch(
+      calls.map(({ selection, mutation, options }) => ({ selection, mutation, options })),
+      mergeTransactionOptions(calls),
+    );
+    // One server write, one reload — the reload count collapses with the batch.
+    return reloadsRequested(calls) > 0 ? 1 : 0;
+  }
+  for (const { dispatch, selection, mutation, options } of calls) {
+    await dispatch(selection, mutation, options);
+  }
+  return reloadsRequested(calls);
+}
+
+/**
+ * Dev-only [hf-commit] lifecycle trace. The production observability lives in
+ * the trackStudioEvent commit_* events (always on); these console lines are a
+ * developer aid and stay out of end users' consoles.
+ */
+function traceCommit(stage: string, data: Record<string, unknown>): void {
+  if (import.meta.env.DEV) console.info(`[hf-commit] ${stage}`, data);
+}
+
+/**
+ * Owns the visual + persistence + history lifecycle for one gesture release.
+ * `settle` deliberately runs before the first promise is created or awaited.
+ */
+export function runGestureTransaction(tx: GestureTransaction): Promise<void> {
+  const startedAt = performance.now();
+  const coalesceKey = `tx:${tx.label}:${++transactionCounter}`;
+  let mutationCount = 0;
+  let reloadCount = 0;
+  const bufferedCommits: BufferedCommit[] = [];
+  traceCommit("start", { label: tx.label, coalesceKey });
+  tx.settle();
+  traceCommit("settled", { label: tx.label, coalesceKey });
+
+  const before = !tx.skipPixelAssert ? readPixelRect(tx.element) : null;
+  const commit: TxCommit = (commitMutation) => {
+    const wrapped: CommitMutation = (selection, mutation, options) => {
+      mutationCount += 1;
+      bufferedCommits.push({
+        dispatch: commitMutation,
+        selection,
+        mutation,
+        options: transactionOptions(options, coalesceKey, tx.label),
+      });
+      return Promise.resolve();
+    };
+    transactionCommits.add(wrapped);
+    return wrapped;
+  };
+
+  return tx
+    .persist(commit)
+    .then(async () => {
+      reloadCount = await dispatchBufferedCommits(bufferedCommits);
+      const durationMs = Math.round(performance.now() - startedAt);
+      traceCommit("persisted", { label: tx.label, coalesceKey });
+      if (before) {
+        const after = readPixelRect(tx.element);
+        const delta = pixelDelta(before, after);
+        if (exceedsPixelTolerance(delta)) {
+          if (import.meta.env.DEV) {
+            console.error("[hf-commit] persist changed pixels", {
+              label: tx.label,
+              before,
+              after,
+              delta,
+            });
+          }
+          trackStudioEvent("commit_invariant_violation", {
+            label: tx.label,
+            delta_x: roundToOneDecimal(delta.x),
+            delta_y: roundToOneDecimal(delta.y),
+            delta_w: roundToOneDecimal(delta.width),
+            delta_h: roundToOneDecimal(delta.height),
+            mutation_count: mutationCount,
+            reload_count: reloadCount,
+            duration_ms: durationMs,
+          });
+        }
+      }
+      trackStudioEvent("commit_transaction", {
+        label: tx.label,
+        mutation_count: mutationCount,
+        reload_count: reloadCount,
+        duration_ms: durationMs,
+        pixel_asserted: before !== null,
+      });
+    })
+    .catch((error: unknown) => {
+      tx.restore();
+      trackStudioEvent("commit_transaction_failed", {
+        label: tx.label,
+        mutation_count: mutationCount,
+        error_name: error instanceof Error ? error.name : "unknown",
+        restore_ran: true,
+      });
+      traceCommit("restore", { label: tx.label, coalesceKey });
+      throw error;
+    });
+}