@hyperframes/studio 0.7.54 → 0.7.56

package/src/components/sidebar/assetHelpers.ts

@@ -30,6 +30,35 @@ export function ext(path: string): string {
   return dot > 0 ? name.slice(dot + 1).toUpperCase() : "";
 }
 
+/**
+ * Truncate a string to at most `maxLen` chars, preserving the start and end.
+ * Middle characters are replaced with an ellipsis. If the string is short
+ * enough it is returned unchanged.
+ *
+ * @example truncateMiddle("2a37eabf-long-uuid-887d8.mp4", 20) → "2a37eabf-…887d8.mp4"
+ *
+ * Pure — unit-tested.
+ */
+export function truncateMiddle(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  const keep = maxLen - 1; // 1 char for ellipsis
+  const tail = Math.floor(keep / 3);
+  const head = keep - tail;
+  return str.slice(0, head) + "…" + str.slice(str.length - tail);
+}
+
+/**
+ * Format a duration in seconds as MM:SS. Returns an empty string for
+ * non-positive, NaN, or Infinity values. Pure — unit-tested.
+ */
+export function formatDuration(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds <= 0) return "";
+  const total = Math.round(seconds);
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+
 export const CATEGORY_LABELS: Record<MediaCategory, string> = {
   audio: "Audio",
   images: "Images",

package/src/contexts/DomEditContext.tsx

@@ -98,6 +98,15 @@ export function useDomEditActionsContext(): DomEditActionsValue {
   return ctx;
 }
 
+/**
+ * Optional access — returns null outside a provider. Lets the player-package
+ * <Timeline> (a public standalone export) reach the z-order persist path when
+ * embedded in the NLE without hard-requiring the provider in standalone/test mounts.
+ */
+export function useDomEditActionsContextOptional(): DomEditActionsValue | null {
+  return useContext(DomEditActionsContext);
+}
+
 export function useDomEditSelectionContext(): DomEditSelectionValue {
   const ctx = useContext(DomEditSelectionContext);
   if (!ctx) throw new Error("useDomEditSelectionContext must be used within DomEditProvider");

package/src/contexts/StudioContext.tsx

@@ -31,8 +31,6 @@ export interface StudioShellValue {
   compositionDimensions: CompositionDimensions | null;
   waitForPendingDomEditSaves: () => Promise<void>;
   handlePreviewIframeRef: (iframe: HTMLIFrameElement | null) => void;
-  timelineVisible: boolean;
-  toggleTimelineVisibility: () => void;
 }
 
 export interface StudioPlaybackValue {
@@ -56,6 +54,15 @@ export function useStudioShellContext(): StudioShellValue {
   return ctx;
 }
 
+/**
+ * Optional access — returns null outside a provider. Lets the player-package
+ * <Timeline> (a public standalone export) read shell state when embedded in the
+ * NLE without hard-requiring the provider in standalone/test mounts.
+ */
+export function useStudioShellContextOptional(): StudioShellValue | null {
+  return useContext(StudioShellContext);
+}
+
 export function useStudioPlaybackContext(): StudioPlaybackValue {
   const ctx = useContext(StudioPlaybackContext);
   if (!ctx) throw new Error("useStudioPlaybackContext must be used within StudioPlaybackProvider");
@@ -90,8 +97,6 @@ export function StudioShellProvider({
     compositionDimensions,
     waitForPendingDomEditSaves,
     handlePreviewIframeRef,
-    timelineVisible,
-    toggleTimelineVisibility,
   } = value;
 
   const stable = useMemo<StudioShellValue>(
@@ -108,14 +113,11 @@ export function StudioShellProvider({
       compositionDimensions,
       waitForPendingDomEditSaves,
       handlePreviewIframeRef,
-      timelineVisible,
-      toggleTimelineVisibility,
     }),
     [
       projectId,
       activeCompPath,
       compositionDimensions,
-      timelineVisible,
       editHistory,
       renderQueue,
       setActiveCompPath,
@@ -125,7 +127,6 @@ export function StudioShellProvider({
       handleRedo,
       waitForPendingDomEditSaves,
       handlePreviewIframeRef,
-      toggleTimelineVisibility,
     ],
   );
   return <StudioShellContext value={stable}>{children}</StudioShellContext>;

package/src/contexts/TimelineEditContext.tsx

@@ -10,7 +10,7 @@ export function useTimelineEditContext(): TimelineEditCallbacks {
 }
 
 /**
- * Optional access, returns an empty object when outside a provider.
+ * Optional access — returns an empty object when outside a provider.
  * Useful in components that can render both inside and outside the NLE.
  */
 export function useTimelineEditContextOptional(): TimelineEditCallbacks {
@@ -26,18 +26,14 @@ export function TimelineEditProvider({
 }) {
   const memoized = useMemo(
     () => value,
-    // Each callback is a stable reference from the parent, memoize the bag
+    // Each callback is a stable reference from the parent — memoize the bag
     // so consumers don't re-render when unrelated parent state changes.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
       value.onMoveElement,
-      value.onResizeElement,
       value.onMoveElements,
-      value.onResizeElements,
-      value.onPreviewMoveElements,
-      value.onPreviewResizeElements,
+      value.onResizeElement,
       value.onToggleTrackHidden,
-      value.onToggleElementHidden,
       value.onBlockedEditAttempt,
       value.onSplitElement,
       value.onRazorSplit,

package/src/hooks/deleteSelectedKeyframes.ts

@@ -0,0 +1,35 @@
+import { usePlayerStore } from "../player/store/playerStore";
+import { selectedKeyframePercentagesForElement } from "../utils/keyframeSelection";
+import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+
+let deleteKeyframesCommitCounter = 0;
+
+/**
+ * Remove the keyframes currently selected in the player store from the active
+ * element's GSAP animation. Reads selection lazily so it stays correct when
+ * invoked from a ref callback.
+ */
+export function deleteSelectedKeyframes(session: {
+  selectedGsapAnimations: readonly { id: string; keyframes?: unknown }[];
+  handleGsapRemoveKeyframe: (
+    animId: string,
+    pct: number,
+    options?: Partial<CommitMutationOptions>,
+  ) => void;
+}): void {
+  const { selectedKeyframes, selectedElementId } = usePlayerStore.getState();
+  const animation = session.selectedGsapAnimations.find((anim) => anim.keyframes);
+  if (!animation) return;
+  // Only the active element's keyframes; a stale cross-element selection must not delete here.
+  const percentages = selectedKeyframePercentagesForElement(selectedKeyframes, selectedElementId);
+  const coalesceOptions = {
+    coalesceKey: `delete-keyframes:${++deleteKeyframesCommitCounter}`,
+    coalesceMs: Number.POSITIVE_INFINITY,
+  };
+  for (const [index, pct] of percentages.entries()) {
+    session.handleGsapRemoveKeyframe(animation.id, pct, {
+      ...coalesceOptions,
+      ...(index === percentages.length - 1 ? { softReload: true } : { skipReload: true }),
+    });
+  }
+}

package/src/hooks/domEditCommitTypes.ts

@@ -1,5 +1,15 @@
 import type { DomEditSelection } from "../components/editor/domEditing";
-import type { PatchOperation } from "../utils/sourcePatcher";
+import type { PatchOperation, PatchTarget } from "../utils/sourcePatcher";
+
+export interface DomEditPatchBatch {
+  sourceFile: string;
+  patches: Array<{ target: PatchTarget; operations: PatchOperation[] }>;
+}
+
+export type CommitDomEditPatchBatches = (
+  batches: DomEditPatchBatch[],
+  options: { label: string; coalesceKey: string },
+) => Promise<void>;
 
 export type PersistDomEditOperations = (
   selection: DomEditSelection,
@@ -7,6 +17,7 @@ export type PersistDomEditOperations = (
   options?: {
     label?: string;
     coalesceKey?: string;
+    coalesceMs?: number;
     skipRefresh?: boolean;
     prepareContent?: (html: string, sourceFile: string) => string;
     shouldSave?: () => boolean;

package/src/hooks/domSelectionTestHarness.ts

@@ -1,5 +1,8 @@
 // Shared harness helpers for selection hook tests (useDomSelection,
 // usePreviewInteraction). Test-only module.
+import type React from "react";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
 import type { DomEditSelection } from "../components/editor/domEditing";
 
 export function installReactActEnvironment(): void {
@@ -9,6 +12,17 @@ export function installReactActEnvironment(): void {
   });
 }
 
+/** Mount a React element into a fresh detached host and return its root. */
+export function mountReactHarness(node: React.ReactElement): Root {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(node);
+  });
+  return root;
+}
+
 export function makeSelection(label: string, element: HTMLElement): DomEditSelection {
   return {
     element,

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();
+  });
+});