@hyperframes/studio 0.8.81 → 0.8.82

package/src/components/nle/AudioMeterStrip.tsx

@@ -20,7 +20,7 @@ import type { StereoLevel } from "@hyperframes/core/runtime/levelTap";
 import { usePlayerStore } from "../../player";
 import { clampNumber } from "../../utils/studioHelpers";
 import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
-import { useStudioShellContext } from "../../contexts/StudioContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import {
   METER_DB_MARKS,
@@ -107,7 +107,7 @@ function useVolumeHandlers(): {
 
 type PreviewWindow = (Window & { __hf?: { audioMeter?: AudioMeterHook } }) | null | undefined;
 
-function readHook(iframe: HTMLIFrameElement | null): AudioMeterHook | null {
+function readHook(iframe: HTMLIFrameElement | null | undefined): AudioMeterHook | null {
   try {
     return (iframe?.contentWindow as PreviewWindow)?.__hf?.audioMeter ?? null;
   } catch {
@@ -123,9 +123,8 @@ function paintPeak(el: HTMLElement | null, peak: number): void {
   el.style.setProperty("transform", peak >= 1 ? "translateY(1px)" : "none");
 }
 
-/** The fill is a fixed green/amber/red backdrop; painting only moves the dark
- *  mask that covers the unlit top portion, so a loud peak lights the real red
- *  band instead of tinting a flat colour brighter. */
+/** The fill is a fixed green/amber/red backdrop; painting only moves the dark mask that covers the unlit top
+ *  portion, so a loud peak lights the real red band instead of tinting a flat colour brighter. */
 function paint(bars: StripBars | undefined, channels: Pair): void {
   channels.forEach((ch, i) => {
     bars?.[i]?.mask?.style.setProperty("height", `${(1 - ch.level) * 100}%`);
@@ -179,8 +178,13 @@ export function stepAndPaintStrips(
 }
 
 /** One rAF loop re-reads the hook off the live preview window, so a reloaded iframe is followed. */
-function useMeterLoop(strips: Strip[], bars: RefObject<Map<string | null, StripBars>>) {
-  const { previewIframeRef } = useStudioShellContext();
+function useMeterLoop(
+  strips: Strip[],
+  bars: RefObject<Map<string | null, StripBars>>,
+  iframeRef: RefObject<HTMLIFrameElement | null> | undefined,
+) {
+  const shell = useStudioShellContextOptional();
+  const previewIframeRef = iframeRef ?? shell?.previewIframeRef;
   const stripsRef = useRef(strips);
   stripsRef.current = strips;
   useEffect(() => {
@@ -190,7 +194,7 @@ function useMeterLoop(strips: Strip[], bars: RefObject<Map<string | null, StripB
     const state = new Map<string | null, Pair>();
     const tick = (now: number) => {
       raf = requestAnimationFrame(tick);
-      active = followMeterHook(active, readHook(previewIframeRef.current));
+      active = followMeterHook(active, readHook(previewIframeRef?.current));
       const levels = active?.read();
       const dt = now - last;
       last = now;
@@ -395,14 +399,21 @@ function MeterStrip({
   );
 }
 
-export const AudioMeterStrip = memo(function AudioMeterStrip() {
+export interface AudioMeterStripProps {
+  /** Pass a stable ref (useRef): a new object each render restarts the meter loop. */
+  previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+}
+
+export const AudioMeterStrip = memo(function AudioMeterStrip({
+  previewIframeRef,
+}: AudioMeterStripProps) {
   const visible = useAudioMetersVisible((s) => s.visible);
   const projectHasAudio = useProjectHasAudio();
   if (!visible || !projectHasAudio) return null;
-  return <MeterStripBody />;
+  return <MeterStripBody previewIframeRef={previewIframeRef} />;
 });
 
-function MeterStripBody() {
+function MeterStripBody({ previewIframeRef }: AudioMeterStripProps) {
   const strips = useStrips();
   const bars = useRef(new Map<string | null, StripBars>());
   const register = useRef((id: string | null, b: StripBars | null) => {
@@ -410,7 +421,7 @@ function MeterStripBody() {
     else bars.current.delete(id);
   }).current;
   const { onLive, onCommit } = useVolumeHandlers();
-  useMeterLoop(strips, bars);
+  useMeterLoop(strips, bars, previewIframeRef);
   return (
     <div
       data-testid="audio-meter-strip"

package/src/components/pointerTargetSize.test.tsx

@@ -7,7 +7,7 @@ import { CompositionsTab } from "./sidebar/CompositionsTab";
 import { TimelineToolbar } from "./TimelineToolbar";
 
 vi.mock("../contexts/StudioContext", () => ({
-  useStudioShellContext: () => ({
+  useStudioShellContextOptional: () => ({
     editHistory: { canUndo: false, canRedo: false },
     handleUndo: vi.fn(),
     handleRedo: vi.fn(),

package/src/components/studioColorGradingScope.ts

@@ -40,31 +40,6 @@ function colorGradingScopePaths(
   return scope === "source-file" ? [selectedSourceFile] : compositionPaths;
 }
 
-async function patchColorGradingScopeFiles(
-  paths: string[],
-  value: string | null,
-  readProjectFile: ProjectFileReader,
-): Promise<{ files: Record<string, string>; changedElements: number }> {
-  const snapshots = await Promise.all(
-    Array.from(new Set(paths)).map(async (path) => ({
-      path,
-      before: await readProjectFile(path),
-    })),
-  );
-  const files: Record<string, string> = {};
-  let changedElements = 0;
-
-  for (const { path, before } of snapshots) {
-    const result = patchMediaColorGradingInHtml(before, value);
-    if (result.html !== before) {
-      files[path] = result.html;
-      changedElements += result.count;
-    }
-  }
-
-  return { files, changedElements };
-}
-
 // fallow-ignore-next-line complexity
 export async function applyColorGradingScopeUpdate({
   scope,
@@ -88,24 +63,25 @@ export async function applyColorGradingScopeUpdate({
     return EMPTY_COLOR_GRADING_SCOPE_RESULT;
   }
 
-  const { files, changedElements } = await patchColorGradingScopeFiles(
-    colorGradingScopePaths(scope, selectedSourceFile, compositionPaths),
-    value,
-    readProjectFile,
-  );
-  if (Object.keys(files).length === 0) {
-    showToast("No color grading changed", "info");
-    return EMPTY_COLOR_GRADING_SCOPE_RESULT;
-  }
-
+  let changedElements = 0;
+  const patchGrading = (before: string) => {
+    const result = patchMediaColorGradingInHtml(before, value);
+    changedElements += result.count;
+    return result.html;
+  };
+  const paths = colorGradingScopePaths(scope, selectedSourceFile, compositionPaths);
   const changedPaths = await saveProjectFilesWithHistory({
     projectId,
     label: value ? "Apply color grading" : "Clear color grading",
-    files,
+    files: Object.fromEntries(paths.map((path) => [path, patchGrading])),
     readFile: readProjectFile,
     writeFile: writeProjectFile,
     recordEdit,
   });
+  if (changedPaths.length === 0) {
+    showToast("No color grading changed", "info");
+    return EMPTY_COLOR_GRADING_SCOPE_RESULT;
+  }
   reloadPreview();
   showToast(
     `${value ? "Applied" : "Cleared"} color grading on ${changedElements} media item${changedElements === 1 ? "" : "s"}`,

package/src/contexts/TimelineEditContext.test.tsx

@@ -0,0 +1,49 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";
+import { TimelineEditProvider, useTimelineEditContext } from "./TimelineEditContext";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function mountProvider() {
+  const seen: TimelineEditCallbacks[] = [];
+  function Consumer() {
+    seen.push(useTimelineEditContext());
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  const render = (value: TimelineEditCallbacks) =>
+    act(() =>
+      root.render(
+        <TimelineEditProvider value={value}>
+          <Consumer />
+        </TimelineEditProvider>,
+      ),
+    );
+  return { seen, render, unmount: () => act(() => root.unmount()) };
+}
+
+describe("TimelineEditProvider", () => {
+  it("hands consumers the latest multi-clip resize callback", () => {
+    const { seen, render, unmount } = mountProvider();
+    const onMoveElement = vi.fn();
+    const staleResize = vi.fn();
+    const currentResize = vi.fn();
+    render({ onMoveElement, onResizeElements: staleResize });
+    render({ onMoveElement, onResizeElements: currentResize });
+    expect(seen.at(-1)!.onResizeElements).toBe(currentResize);
+    unmount();
+  });
+
+  it("keeps the same bag when the parent passes the same callbacks in a new object", () => {
+    const { seen, render, unmount } = mountProvider();
+    const onMoveElement = vi.fn();
+    const onResizeElements = vi.fn();
+    render({ onMoveElement, onResizeElements });
+    render({ onMoveElement, onResizeElements });
+    expect(seen.at(-1)).toBe(seen[0]);
+    unmount();
+  });
+});

package/src/contexts/TimelineEditContext.tsx

@@ -25,6 +25,32 @@ export function useTimelineEditContextValue(): TimelineEditCallbacks | null {
   return useContext(TimelineEditContext);
 }
 
+const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {
+  onMoveElement: true,
+  onMoveElements: true,
+  onResizeElement: true,
+  onResizeElements: true,
+  onToggleTrackHidden: true,
+  onSetAudioGroupAttributeLive: true,
+  onSetAudioGroupAttributeQuiet: true,
+  onRevertAudioGroupAttributeLive: true,
+  onGroupClips: true,
+  onSetElementAttributeLive: true,
+  onSetElementAttributeQuiet: true,
+  onRevertElementAttributeLive: true,
+  onBlockedEditAttempt: true,
+  onSplitElement: true,
+  onRazorSplit: true,
+  onRazorSplitAll: true,
+  onDeleteKeyframe: true,
+  onDeleteAllKeyframes: true,
+  onMoveKeyframeToPlayhead: true,
+  onMoveKeyframe: true,
+  onToggleKeyframeAtPlayhead: true,
+  onTogglePropertyGroupKeyframe: true,
+};
+const EDIT_CALLBACK_KEYS = Object.keys(EDIT_CALLBACK_KEY_SET) as (keyof TimelineEditCallbacks)[];
+
 export function TimelineEditProvider({
   value,
   children,
@@ -37,29 +63,7 @@ export function TimelineEditProvider({
     // 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.onMoveElements,
-      value.onResizeElement,
-      value.onToggleTrackHidden,
-      value.onSetAudioGroupAttributeLive,
-      value.onSetAudioGroupAttributeQuiet,
-      value.onRevertAudioGroupAttributeLive,
-      value.onGroupClips,
-      value.onSetElementAttributeLive,
-      value.onSetElementAttributeQuiet,
-      value.onRevertElementAttributeLive,
-      value.onBlockedEditAttempt,
-      value.onSplitElement,
-      value.onRazorSplit,
-      value.onRazorSplitAll,
-      value.onDeleteKeyframe,
-      value.onDeleteAllKeyframes,
-      value.onMoveKeyframeToPlayhead,
-      value.onMoveKeyframe,
-      value.onToggleKeyframeAtPlayhead,
-      value.onTogglePropertyGroupKeyframe,
-    ],
+    EDIT_CALLBACK_KEYS.map((key) => value[key]),
   );
   return <TimelineEditContext.Provider value={memoized}>{children}</TimelineEditContext.Provider>;
 }

package/src/hooks/canvasQuickSaves.test.tsx

@@ -0,0 +1,195 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection, DomEditTextField } from "../components/editor/domEditing";
+import type { TimelineElement } from "../player/store/playerStore";
+import { buildTimelineMoveTimingPatch, persistTimelineEdit } from "./timelineEditingHelpers";
+import { useDomEditCommits } from "./useDomEditCommits";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const SOURCE =
+  '<!doctype html><html><head></head><body><div data-hf-id="hf-card" style="color: red">Card</div>' +
+  '<div id="clip" class="clip" data-start="1" data-duration="5" data-track-index="0"></div></body></html>';
+
+// The server patches whatever is on disk; the writer refuses a stale base like If-Match does.
+// The first write can be held mid-flight.
+function fakeProject() {
+  let disk = SOURCE;
+  const refused: string[] = [];
+  let writes = 0;
+  let release = () => {};
+  const firstWrite = new Promise<void>((resolve) => (release = resolve));
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: string, init?: RequestInit) => {
+      if (input.includes("/file-mutations/patch-element/")) {
+        const { operations } = JSON.parse(String(init?.body)) as {
+          operations: Array<{ property?: string; value?: string }>;
+        };
+        for (const op of operations) {
+          if (op.property === "color") disk = disk.replace(/color: \w+/, `color: ${op.value}`);
+        }
+        return Response.json({ ok: true, changed: true, matched: true, content: disk });
+      }
+      return Response.json({ content: disk });
+    }),
+  );
+  const writeProjectFile = async (path: string, content: string, expected?: string) => {
+    if (++writes === 1) await firstWrite;
+    if (expected !== undefined && expected !== disk && content !== disk) {
+      refused.push(path);
+      throw new Error(`409 conflict on ${path}`);
+    }
+    disk = content;
+  };
+  return { writeProjectFile, refused, release: () => release(), read: () => disk };
+}
+
+type Project = ReturnType<typeof fakeProject>;
+
+function mountCanvasCommits(project: Project) {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  iframe.contentDocument!.body.innerHTML =
+    '<div data-hf-id="hf-card" style="color: red">Card</div>';
+  const element = iframe.contentDocument!.querySelector<HTMLElement>('[data-hf-id="hf-card"]')!;
+  const selection = {
+    element,
+    label: "Card",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 120, height: 40 },
+    textContent: "Card",
+    dataAttributes: {},
+    inlineStyles: { color: "red" },
+    computedStyles: {},
+    textFields: [],
+    capabilities: { canSelect: true, canEditStyles: true, canMove: true, canResize: true },
+    hfId: "hf-card",
+    selector: '[data-hf-id="hf-card"]',
+    selectorIndex: 0,
+  } as unknown as DomEditSelection;
+  const captured: { current: ReturnType<typeof useDomEditCommits> | null } = { current: null };
+  const toasts: string[] = [];
+  function Probe() {
+    captured.current = useDomEditCommits({
+      activeCompPath: "index.html",
+      previewIframeRef: { current: iframe },
+      showToast: (message) => toasts.push(message),
+      queueDomEditSave: (save) => save(),
+      writeProjectFile: project.writeProjectFile,
+      editHistory: { recordEdit: async () => {} },
+      fileTree: [],
+      importedFontAssetsRef: { current: [] },
+      projectId: "p1",
+      projectIdRef: { current: "p1" },
+      reloadPreview: () => {},
+      domEditSelection: selection,
+      applyDomSelection: () => {},
+      clearDomSelection: () => {},
+      refreshDomEditSelectionFromPreview: () => {},
+      buildDomSelectionFromTarget: async () => null,
+      readOnlyPreview: false,
+    });
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(createElement(Probe)));
+  return { hook: captured.current!, selection, toasts };
+}
+
+const selfText: DomEditTextField = {
+  key: "self",
+  label: "self",
+  value: "Card",
+  tagName: "div",
+  attributes: [],
+  inlineStyles: {},
+  computedStyles: {},
+  source: "self",
+};
+
+const moveClip = (project: Project) =>
+  persistTimelineEdit({
+    projectId: "p1",
+    activeCompPath: "index.html",
+    element: {
+      id: "clip",
+      key: "clip",
+      domId: "clip",
+      tag: "div",
+      start: 1,
+      duration: 5,
+      track: 0,
+    } as TimelineElement,
+    label: "Move clip",
+    buildPatches: (original, target) => buildTimelineMoveTimingPatch(original, target, 3, 5),
+    writeProjectFile: project.writeProjectFile,
+    recordEdit: async () => {},
+    pendingTimelineEditPathRef: { current: new Set<string>() },
+  });
+
+// Starts the second save while the first one's write is in flight; both must land unrefused.
+async function expectBothLand(
+  project: Project,
+  first: () => Promise<unknown>,
+  second: () => Promise<unknown>,
+) {
+  await act(async () => {
+    const saves = [first()];
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    saves.push(second());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    project.release();
+    await Promise.allSettled(saves);
+  });
+  expect(project.refused).toEqual([]);
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+});
+
+describe("canvas edit commits share the file queue", () => {
+  it("lands a second canvas commit started while the first one's font write is held", async () => {
+    const project = fakeProject();
+    const { hook, selection, toasts } = mountCanvasCommits(project);
+    const font = {
+      family: "Imported",
+      path: "fonts/Imported.woff2",
+      url: "/api/projects/p1/preview/fonts/Imported.woff2",
+    };
+
+    await expectBothLand(
+      project,
+      () => hook.commitDomTextFields(selection, [selfText], { importedFont: font }),
+      () => hook.handleDomStyleCommit("color", "green"),
+    );
+
+    expect(toasts).toEqual([]);
+    expect(project.read()).toContain("@font-face");
+    expect(project.read()).toContain("color: green");
+  });
+
+  it("lands a canvas commit started while a timeline save is writing", async () => {
+    const project = fakeProject();
+    const { hook, toasts } = mountCanvasCommits(project);
+
+    await expectBothLand(
+      project,
+      () => moveClip(project),
+      () => hook.handleDomStyleCommit("color", "green"),
+    );
+
+    expect(toasts).toEqual([]);
+    expect(project.read()).toContain('id="clip" class="clip" data-start="3"');
+    expect(project.read()).toContain("color: green");
+  });
+});

package/src/hooks/gsapMutationClient.ts

@@ -0,0 +1,116 @@
+import { studioWriteHeaders } from "../utils/studioFileVersion";
+
+export class GsapPreviewConvergenceError extends Error {}
+export class GsapOwnershipProtocolError extends GsapPreviewConvergenceError {}
+
+/** Verify rollback ownership support before any GSAP mutation can land. */
+export async function requireGsapOwnershipProtocol(projectId: string): Promise<void> {
+  const response = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-capabilities`,
+  );
+  if (!response.ok) {
+    throw new GsapOwnershipProtocolError("Server does not support owned GSAP mutations");
+  }
+  const body = await response.json().catch(() => null);
+  if (!isRecord(body) || body.atomicOwnershipPairs !== true) {
+    throw new GsapOwnershipProtocolError("Invalid GSAP mutation capability response");
+  }
+}
+
+/** Atomically restore one GSAP mutation only while its exact output still owns
+ * the file. The server performs compare + write synchronously, eliminating the
+ * client GET→PUT window that could overwrite a successor edit. */
+export async function rollbackOwnedMutation(
+  projectId: string,
+  targetPath: string,
+  expected: string,
+  restore: string,
+): Promise<"restored" | "conflict"> {
+  if (targetPath.includes("\0") || targetPath.includes("..")) {
+    throw new Error(`Unsafe path: ${targetPath}`);
+  }
+  const response = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-rollback/${encodeURIComponent(targetPath)}`,
+    {
+      method: "POST",
+      // Deliberately unclaimed: a rollback runs because a mutation did not
+      // converge, so let the restored file reload the preview.
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ expected, restore }),
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`Failed to restore ${targetPath}`);
+  }
+  const result = (await response.json()) as { restored?: unknown; conflict?: unknown };
+  if (result.restored === true && result.conflict === false) return "restored";
+  if (result.restored === false && result.conflict === true) return "conflict";
+  throw new Error(`Invalid restore response for ${targetPath}`);
+}
+
+/** The server's GSAP-mutation response. `scriptText` is the rewritten root script for a soft
+ * reload, null when none came back: the caller then full-reloads when `mutated`, or rebinds
+ * the runtime timing in place when nothing was rewritten (see syncTimingEditPreview). */
+export type GsapMutationStatus = {
+  mutated: boolean;
+  scriptText: string | null;
+  /** Atomic whole-file ownership pair returned by the mutation endpoint. */
+  before?: string;
+  after?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function readMutationStatus(value: unknown): GsapMutationStatus {
+  if (
+    !isRecord(value) ||
+    typeof value.mutated !== "boolean" ||
+    typeof value.before !== "string" ||
+    typeof value.after !== "string" ||
+    value.mutated !== (value.before !== value.after) ||
+    ("changed" in value && value.changed !== value.mutated)
+  ) {
+    throw new GsapOwnershipProtocolError("Invalid owned GSAP mutation response");
+  }
+  return {
+    mutated: value.mutated,
+    scriptText: typeof value.scriptText === "string" ? value.scriptText : null,
+    before: value.before,
+    after: value.after,
+  };
+}
+
+function readMutationError(value: unknown, fallback: string): string {
+  if (isRecord(value) && typeof value.error === "string") return value.error;
+  return fallback;
+}
+
+export async function postGsapMutation(
+  projectId: string,
+  filePath: string,
+  mutation: Record<string, unknown>,
+  fallback: string,
+): Promise<GsapMutationStatus> {
+  let response: Response;
+  try {
+    response = await fetch(
+      `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(filePath)}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
+        body: JSON.stringify(mutation),
+      },
+    );
+  } catch (error) {
+    throw new GsapPreviewConvergenceError(`${fallback}: mutation outcome unknown`, {
+      cause: error,
+    });
+  }
+  const body: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new GsapPreviewConvergenceError(readMutationError(body, fallback));
+  }
+  return readMutationStatus(body);
+}

package/src/hooks/resizeObserverTestUtils.ts

@@ -0,0 +1,14 @@
+// Test-only ResizeObserver stand-in: a test delivers a size by hand with `reportResize`.
+let resizeCallback: ResizeObserverCallback | null = null;
+
+export function MockResizeObserver(callback: ResizeObserverCallback) {
+  resizeCallback = callback;
+  return { observe() {}, disconnect() {}, unobserve() {} };
+}
+
+export function reportResize(width: number, height: number): void {
+  resizeCallback!(
+    [{ contentRect: { width, height } } as ResizeObserverEntry],
+    {} as ResizeObserver,
+  );
+}