@hyperframes/studio 0.8.107 → 0.8.108

package/src/components/editor/useFxCarveGrouping.ts

@@ -20,6 +20,11 @@ import {
   resolveAudioGroups,
   resolveCarveSourceIds,
 } from "@hyperframes/core/audio-groups";
+import { isAudibleVideoNode } from "../../player/lib/timelineElementHelpers";
+
+export function isCarveVoiceElement(el: Element | null): el is Element {
+  return el !== null && (el.tagName === "AUDIO" || isAudibleVideoNode(el));
+}
 
 /**
  * An id for a new voiceover group, de-duped against every id already in the
@@ -130,7 +135,7 @@ function excludedFor(groupByMember: Map<string, { id: string }>, bedId?: string)
 
 export function collectCarveCandidates(
   doc: Document,
-  others: readonly HTMLAudioElement[],
+  others: readonly Element[],
   overlapsBed: (a: Element) => boolean,
   /** The bed's own id, so neither it nor the group it belongs to is offered. */
   bedId?: string,
@@ -141,7 +146,7 @@ export function collectCarveCandidates(
   const excluded = excludedFor(groupByMember, bedId);
   const offeredGroupIds = new Set<string>();
   const described: CarveCandidate[] = [];
-  for (const a of others) {
+  for (const a of others.filter(isCarveVoiceElement)) {
     const group = groupByMember.get(a.id);
     if (excluded.has(a.id) || (group && excluded.has(group.id))) continue;
     if (!group) {
@@ -161,7 +166,7 @@ export function collectCarveCandidates(
       // iframe document, so the constructor is a different realm's and the
       // instanceof is false for every one (mirrors resolveCarveVoices in
       // useFxCarve.ts).
-      .filter((el): el is HTMLElement => el?.tagName === "AUDIO");
+      .filter((el): el is HTMLElement => isCarveVoiceElement(el));
     if (!members.some(overlapsBed)) continue;
     offeredGroupIds.add(group.id);
     described.push({

package/src/components/nle/AudioMeterStrip.test.tsx

@@ -12,6 +12,8 @@ import { SILENT_CHANNEL } from "../../utils/audioMeterMath";
 import {
   AudioMeterStrip,
   type AudioMeterStripProps,
+  CLIP_LATCH_PEAK,
+  stepClipLatch,
   evictGoneMeterState,
   followMeterHook,
   stepAndPaintStrips,
@@ -416,3 +418,54 @@ describe("stepAndPaintStrips", () => {
     expect(state.has("loud")).toBe(true);
   });
 });
+
+describe("CLIP light", () => {
+  const hookAt = (peak: number) => ({
+    start: vi.fn(),
+    stop: vi.fn(),
+    read: vi.fn(() => ({ master: { l: peak, r: 0 }, groups: {} })),
+  });
+
+  it("latches at the -1 dBFS export ceiling, stays lit when the level drops, and resets on click", () => {
+    usePlayerStore.setState({ elements: [clip({})] });
+    const hook = hookAt(1);
+    setHook(hook);
+    const { host } = mount();
+    const light = host.querySelector<HTMLElement>("[data-testid=meter-clip-light]");
+    expect(light?.dataset.lit).toBe("false");
+    tick();
+    expect(light?.dataset.lit).toBe("true");
+    hook.read.mockReturnValue({ master: { l: 0.1, r: 0.1 }, groups: {} });
+    tick();
+    expect(light?.dataset.lit).toBe("true");
+    act(() => light?.click());
+    expect(light?.dataset.lit).toBe("false");
+    tick();
+    expect(light?.dataset.lit).toBe("false");
+  });
+
+  it("stays dark in the red band just under the ceiling", () => {
+    usePlayerStore.setState({ elements: [clip({})] });
+    setHook(hookAt(10 ** (-1.2 / 20)));
+    const { host } = mount();
+    tick();
+    expect(host.querySelector<HTMLElement>("[data-testid=meter-clip-light]")?.dataset.lit).toBe(
+      "false",
+    );
+  });
+});
+
+describe("stepClipLatch", () => {
+  it("lights exactly at -1 dBFS on either channel, not below", () => {
+    expect(CLIP_LATCH_PEAK).toBeCloseTo(0.891251, 6);
+    expect(stepClipLatch(false, { l: CLIP_LATCH_PEAK, r: 0 })).toBe(true);
+    expect(stepClipLatch(false, { l: 0, r: CLIP_LATCH_PEAK })).toBe(true);
+    expect(stepClipLatch(false, { l: CLIP_LATCH_PEAK - 1e-6, r: 0 })).toBe(false);
+    expect(stepClipLatch(false, undefined)).toBe(false);
+  });
+
+  it("holds once lit, whatever comes next", () => {
+    expect(stepClipLatch(true, { l: 0, r: 0 })).toBe(true);
+    expect(stepClipLatch(true, undefined)).toBe(true);
+  });
+});

package/src/components/nle/AudioMeterStrip.tsx

@@ -5,6 +5,7 @@ import {
   useMemo,
   useRef,
   type PointerEvent as ReactPointerEvent,
+  type ReactNode,
   type Ref,
   type RefObject,
 } from "react";
@@ -20,6 +21,7 @@ import type { StereoLevel } from "@hyperframes/core/runtime/levelTap";
 import { usePlayerStore } from "../../player";
 import { clampNumber } from "../../utils/studioHelpers";
 import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
+import { EXPORT_PEAK_CEILING } from "../../utils/exportPeakCeiling";
 import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import {
@@ -49,6 +51,24 @@ type StripBars = [Bars, Bars];
 
 const MONITOR_LABEL = "Monitor";
 
+/** The CLIP light latches at the export ceiling, stricter than RED_AT. */
+export const CLIP_LATCH_PEAK = EXPORT_PEAK_CEILING;
+
+export function stepClipLatch(latched: boolean, master: StereoLevel | undefined): boolean {
+  if (latched || !master) return latched;
+  return Math.max(master.l, master.r) >= CLIP_LATCH_PEAK;
+}
+
+function paintClipLight(el: HTMLElement | null, lit: boolean): void {
+  if (!el) return;
+  el.dataset.lit = String(lit);
+  el.style.setProperty(
+    "background-color",
+    lit ? "var(--color-red-500)" : "var(--color-neutral-800)",
+  );
+  el.style.setProperty("color", lit ? "var(--color-white)" : "var(--color-neutral-500)");
+}
+
 /** Where the fill turns amber, then red, on the same piecewise dB scale the marks use. */
 const AMBER_AT = markFraction(-6);
 const RED_AT = markFraction(-3);
@@ -178,10 +198,16 @@ export function stepAndPaintStrips(
 }
 
 /** One rAF loop re-reads the hook off the live preview window, so a reloaded iframe is followed. */
+interface ClipLatch {
+  lit: boolean;
+  light: HTMLElement | null;
+}
+
 function useMeterLoop(
   strips: Strip[],
   bars: RefObject<Map<string | null, StripBars>>,
   iframeRef: RefObject<HTMLIFrameElement | null> | undefined,
+  clip: RefObject<ClipLatch>,
 ) {
   const shell = useStudioShellContextOptional();
   const previewIframeRef = iframeRef ?? shell?.previewIframeRef;
@@ -200,6 +226,11 @@ function useMeterLoop(
       last = now;
       evictGoneMeterState(state, new Set(stripsRef.current.map((s) => s.id)));
       stepAndPaintStrips(stripsRef.current, state, bars.current, levels, now, dt);
+      const lit = stepClipLatch(clip.current.lit, levels?.master);
+      if (lit !== clip.current.lit) {
+        clip.current.lit = lit;
+        paintClipLight(clip.current.light, lit);
+      }
     };
     raf = requestAnimationFrame(tick);
     return () => {
@@ -210,7 +241,29 @@ function useMeterLoop(
         // Preview iframe already gone.
       }
     };
-  }, [previewIframeRef, bars]);
+  }, [previewIframeRef, bars, clip]);
+}
+
+function ClipLight({ clip }: { clip: RefObject<ClipLatch> }) {
+  return (
+    <button
+      type="button"
+      data-testid="meter-clip-light"
+      data-lit="false"
+      title="Lights when the preview reaches −1 dBFS, the export ceiling. Click to reset."
+      ref={(el) => {
+        clip.current.light = el;
+        paintClipLight(el, clip.current.lit);
+      }}
+      onClick={() => {
+        clip.current.lit = false;
+        paintClipLight(clip.current.light, false);
+      }}
+      className="rounded-[2px] px-1 font-mono text-[9px] leading-[14px] font-bold tracking-wide"
+    >
+      CLIP
+    </button>
+  );
 }
 
 function Bar({ maskRef, peakRef }: { maskRef: Ref<HTMLDivElement>; peakRef: Ref<HTMLDivElement> }) {
@@ -341,11 +394,13 @@ function MeterStrip({
   register,
   onLive,
   onCommit,
+  clipLight,
 }: {
   strip: Strip;
   register: (id: string | null, bars: StripBars | null) => void;
   onLive: (id: string | null, volume: number) => void;
   onCommit: (id: string | null, volume: number) => void;
+  clipLight?: ReactNode;
 }) {
   const refs = [
     useRef<HTMLDivElement>(null),
@@ -364,6 +419,7 @@ function MeterStrip({
   }, [strip.id, register]);
   return (
     <div className="flex w-[104px] shrink-0 flex-col items-center gap-1 px-1.5 pt-2 pb-1">
+      {clipLight}
       <div
         className="flex min-h-0 flex-1 items-stretch gap-1.5"
         aria-label={`${strip.label} level`}
@@ -421,7 +477,8 @@ function MeterStripBody({ previewIframeRef }: AudioMeterStripProps) {
     else bars.current.delete(id);
   }).current;
   const { onLive, onCommit } = useVolumeHandlers();
-  useMeterLoop(strips, bars, previewIframeRef);
+  const clip = useRef<ClipLatch>({ lit: false, light: null });
+  useMeterLoop(strips, bars, previewIframeRef, clip);
   return (
     <div
       data-testid="audio-meter-strip"
@@ -434,6 +491,7 @@ function MeterStripBody({ previewIframeRef }: AudioMeterStripProps) {
           register={register}
           onLive={onLive}
           onCommit={onCommit}
+          clipLight={strip.id === null ? <ClipLight clip={clip} /> : undefined}
         />
       ))}
     </div>

package/src/components/nle/useTimelineEditCallbacks.ts

@@ -53,6 +53,7 @@ export interface TimelineEditCallbackDeps {
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   handleRazorSplitAll: (splitTime: number) => Promise<void> | void;
+  handleFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;
   /** C1's ungrouped-track FX pointer — same auto-grouping write B6's carve uses. */
   handleGroupClips?: (
     clipIds: readonly string[],
@@ -132,6 +133,7 @@ export function useTimelineEditCallbacks({
   handleTimelineElementSplit,
   handleRazorSplit,
   handleRazorSplitAll,
+  handleFreezeFrame,
   handleGroupClips,
   setElementFxAttribute,
 }: TimelineEditCallbackDeps): TimelineEditCallbacks {
@@ -227,6 +229,7 @@ export function useTimelineEditCallbacks({
       onSplitElement: handleTimelineElementSplit,
       onRazorSplit: handleRazorSplit,
       onRazorSplitAll: handleRazorSplitAll,
+      onFreezeFrame: handleFreezeFrame,
       onDeleteAllKeyframes: (element, animationId) => {
         // Hold the element where it is (collapse keyframes to a static set) rather
         // than deleting the whole animation — deleting strands a stale GSAP base
@@ -423,6 +426,7 @@ export function useTimelineEditCallbacks({
       handleTimelineElementSplit,
       handleRazorSplit,
       handleRazorSplitAll,
+      handleFreezeFrame,
       handleGsapRemoveAllKeyframes,
       resolveElementAnimations,
       resolveKeyframeTarget,

package/src/contexts/TimelineEditContext.tsx

@@ -42,6 +42,7 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {
   onSplitElement: true,
   onRazorSplit: true,
   onRazorSplitAll: true,
+  onFreezeFrame: true,
   onDeleteKeyframe: true,
   onDeleteAllKeyframes: true,
   onMoveKeyframeToPlayhead: true,

package/src/hooks/useEditHistoryActions.paint.test.tsx

@@ -206,7 +206,9 @@ it("an undo pressed while a nudge waits for more keys never shows the move befor
   const s = await studio();
   await s.edit();
   resetNudgeKeys();
+  let finish!: () => void;
   const save = vi.fn(async () => {
+    await new Promise<void>((resolve) => (finish = resolve));
     writeFileSync(s.path, NUDGED);
     await s.history().recordEdit({
       label: "Move layer",
@@ -218,12 +220,51 @@ it("an undo pressed while a nudge waits for more keys never shows the move befor
     window.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", cancelable: true }));
   });
 
+  const nudge = () => s.element("box").style.getPropertyValue("translate");
+  expect(nudge()).not.toBe("");
+
   const undone = s.actions().undo();
   expect(s.box()).toBe("50px");
+  expect(nudge()).toBe("");
+  await vi.waitFor(() => expect(save).toHaveBeenCalledTimes(1));
+  expect(nudge()).toBe("");
+  finish();
   await act(() => undone);
   expect(save).toHaveBeenCalledTimes(1);
   expect(s.file()).toBe(AFTER);
   expect(s.box()).toBe("50px");
+  expect(nudge()).toBe("");
+});
+
+it("an undo pressed while a nudge's save is queued shows the nudge undone in the key's own task", async () => {
+  const s = await studio();
+  await s.edit();
+  resetNudgeKeys();
+  let finish!: () => void;
+  const save = vi.fn(async () => {
+    await new Promise<void>((resolve) => (finish = resolve));
+    writeFileSync(s.path, NUDGED);
+    await s.history().recordEdit({
+      label: "Move layer",
+      files: { "index.html": { before: AFTER, after: NUDGED } },
+    });
+  });
+  s.mount(createElement(Nudge, { target: s.element("box"), save }));
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", cancelable: true }));
+  });
+  await vi.waitFor(() => expect(save).toHaveBeenCalledTimes(1));
+  const nudge = () => s.element("box").style.getPropertyValue("translate");
+  expect(nudge()).not.toBe("");
+
+  const undone = s.actions().undo();
+  expect(nudge()).toBe("");
+  expect(s.box()).toBe("50px");
+  finish();
+  await act(() => undone);
+  expect(s.file()).toBe(AFTER);
+  expect(nudge()).toBe("");
+  expect(s.box()).toBe("50px");
 });
 
 it("an undo pressed while a queued save fails undoes the edit before it, file and box alike", async () => {

package/src/hooks/useEditHistoryActions.ts

@@ -3,6 +3,7 @@ import { useCallback, useMemo } from "react";
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import type { RestoreFiles } from "../utils/gsapUndoRestore";
+import { revertNewestStudioPendingEdit } from "../utils/studioPendingEdits";
 
 interface HistoryResult {
   ok: boolean;
@@ -74,7 +75,10 @@ export function useEditHistoryActions({
       const noun = direction === "undo" ? "Undo" : "Redo";
       // Paint the step in the key's own task when this tab knows it; the server's answer then confirms or corrects.
       const predicted = editHistory.predict?.(direction) ?? null;
-      const putBack = predicted ? (showHistoryRestoreNow?.(predicted.files) ?? null) : null;
+      const predictedShown = predicted ? (showHistoryRestoreNow?.(predicted.files) ?? null) : null;
+      const pendingEditShown =
+        !predictedShown && direction === "undo" ? revertNewestStudioPendingEdit() : null;
+      const putBack = predictedShown ?? pendingEditShown;
       let result: HistoryResult = { ok: false, reason: "failed" };
       let serverSteppedShown = false;
       try {
@@ -83,8 +87,10 @@ export function useEditHistoryActions({
           readFile: readHistoryFile,
           serialize: serializeHistoryFiles,
         });
-        serverSteppedShown =
-          Boolean(putBack && result.ok && result.label) && result.undoes === predicted?.id;
+        const stepped = Boolean(result.ok && result.label);
+        serverSteppedShown = predictedShown
+          ? stepped && result.undoes === predicted?.id
+          : stepped && Boolean(pendingEditShown);
       } finally {
         if (putBack && !serverSteppedShown) putBack();
       }
@@ -100,7 +106,10 @@ export function useEditHistoryActions({
         return;
       }
       if (result.ok && result.label) {
-        const files = serverSteppedShown ? fromShown(result.files, predicted!.files) : result.files;
+        const files =
+          serverSteppedShown && predictedShown
+            ? fromShown(result.files, predicted!.files)
+            : result.files;
         const restore = { paths: result.paths, files };
         onAfterUndoRedo?.(restore);
         if (activeCompPath && result.paths?.includes(activeCompPath)) {

package/src/hooks/useElementPicker.test.ts

@@ -19,6 +19,22 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
+// The runtime's element-picked message, posted by `from`.
+const picked = (from: Window | null, selector: string) =>
+  act(() => {
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        source: from,
+        data: {
+          source: "hf-preview",
+          type: "element-picked",
+          elementInfo: { selector, tagName: "h1" },
+          ...runtimeProtocolMetadata(30),
+        },
+      }),
+    );
+  });
+
 // The preview page: the saved markup plus what the runtime adds to it.
 function mountPreview(mounted = ""): HTMLIFrameElement {
   const iframe = document.createElement("iframe");
@@ -61,19 +77,7 @@ function mountPicker(
   }
   root = createRoot(document.createElement("div"));
   act(() => root?.render(React.createElement(Harness)));
-  act(() => {
-    window.dispatchEvent(
-      new MessageEvent("message", {
-        source: iframe.contentWindow,
-        data: {
-          source: "hf-preview",
-          type: "element-picked",
-          elementInfo: { selector, tagName: "h1" },
-          ...runtimeProtocolMetadata(30),
-        },
-      }),
-    );
-  });
+  picked(iframe.contentWindow, selector);
   const picker = () => api as ReturnType<typeof useElementPicker>;
   return {
     picker,
@@ -170,3 +174,48 @@ describe("an edit to a picked element without an id", () => {
     expect(synced).toEqual([]);
   });
 });
+
+describe("a pick across a reload that swaps the preview frame", () => {
+  function mountSwapping() {
+    const live = mountPreview();
+    const ref: { current: HTMLIFrameElement | null } = { current: live };
+    let api: ReturnType<typeof useElementPicker> | null = null;
+    function Harness() {
+      api = useElementPicker(ref);
+      return null;
+    }
+    root = createRoot(document.createElement("div"));
+    act(() => root?.render(React.createElement(Harness)));
+    return { live, ref, picker: () => api as ReturnType<typeof useElementPicker> };
+  }
+
+  it("keeps a pick posted by the frame it was made in after a new frame took its place", () => {
+    const { live, ref, picker } = mountSwapping();
+    picked(live.contentWindow, "h1");
+    act(() => picker().clearPick());
+    // The reload promotes its frame before the old frame's pick message is handled.
+    const old = live.contentWindow;
+    ref.current = mountPreview();
+    live.remove();
+    picked(old, "h1.next");
+    expect(picker().pickedElement?.selector).toBe("h1.next");
+  });
+
+  it("does not keep trusting a zoomed frame once the zoom is gone", () => {
+    const { picker } = mountSwapping();
+    const zoom = mountPreview();
+    act(() => picker().setActiveIframe(zoom));
+    picked(zoom.contentWindow, "h1");
+    expect(picker().pickedElement?.selector).toBe("h1");
+    act(() => picker().setActiveIframe(null));
+    picked(zoom.contentWindow, "h1.late");
+    expect(picker().pickedElement?.selector).toBe("h1");
+  });
+
+  it("still ignores a frame it never showed", () => {
+    const { picker } = mountSwapping();
+    const stranger = mountPreview();
+    picked(stranger.contentWindow, "h1");
+    expect(picker().pickedElement).toBeNull();
+  });
+});

package/src/hooks/useElementPicker.ts

@@ -97,6 +97,8 @@ export function useElementPicker(
     setPickedElement(null);
   }, []);
 
+  const windowsThatWerePrimary = useRef(new WeakSet<MessageEventSource>());
+
   // Listen for picker messages from the iframe
   useMountEffect(() => {
     // One guard per message field, then one branch per message type.
@@ -105,10 +107,16 @@ export function useElementPicker(
       const data = e.data;
       if (data?.source !== "hf-preview") return;
       if (!acceptStudioRuntimeMessage(data)) return;
-      // Accept events from either the primary iframe or the active override
+      // The primary frame, the active override, or a primary frame a reload just swapped out.
       const activeIframe = getActiveIframe();
       if (!activeIframe) return;
-      if (e.source !== activeIframe.contentWindow && e.source !== iframeRef.current?.contentWindow)
+      if (!e.source) return;
+      if (e.source === iframeRef.current?.contentWindow)
+        windowsThatWerePrimary.current.add(e.source);
+      else if (
+        e.source !== activeIframe.contentWindow &&
+        !windowsThatWerePrimary.current.has(e.source)
+      )
         return;
 
       if (data.type === "element-picked" && data.elementInfo) {

package/src/hooks/useFreezeFrame.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { requestFreezeFrame } from "./useFreezeFrame";
+
+afterEach(() => vi.unstubAllGlobals());
+
+const element: TimelineElement = {
+  id: "talk",
+  domId: "talk",
+  tag: "video",
+  start: 5,
+  duration: 6,
+  track: 0,
+  parentCompositionStart: 4,
+};
+
+function stubFetch(freezeResponse: { status: number; body: unknown }) {
+  const calls: Array<{ url: string; body: unknown }> = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init?: { body?: string }) => {
+      calls.push({ url, body: init?.body ? JSON.parse(init.body) : null });
+      if (url.includes("/files/")) return new Response(JSON.stringify({ version: "v1" }));
+      return new Response(JSON.stringify(freezeResponse.body), { status: freezeResponse.status });
+    }),
+  );
+  return calls;
+}
+
+describe("requestFreezeFrame", () => {
+  it("posts the clip target, file version and an authored-time playhead", async () => {
+    const calls = stubFetch({ status: 200, body: { before: "a", after: "b", version: "v2" } });
+    const result = await requestFreezeFrame({
+      projectId: "p",
+      path: "scene.html",
+      element,
+      playhead: 7.5,
+    });
+    expect(result).toEqual({ before: "a", after: "b", version: "v2" });
+    const post = calls[1];
+    expect(post?.url).toContain("/file-mutations/freeze-frame");
+    expect(post?.body).toMatchObject({
+      path: "scene.html",
+      expectedVersion: "v1",
+      target: { id: "talk" },
+      playhead: 3.5,
+    });
+  });
+
+  it("surfaces the server's error", async () => {
+    stubFetch({ status: 400, body: { error: "Move the playhead inside a video clip to freeze" } });
+    await expect(
+      requestFreezeFrame({ projectId: "p", path: "index.html", element, playhead: 7 }),
+    ).rejects.toThrow("Move the playhead inside a video clip to freeze");
+  });
+});