@hyperframes/studio 0.8.107 → 0.8.108

package/src/player/components/useClipToolState.ts

@@ -0,0 +1,92 @@
+import { useEffect, useState } from "react";
+import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
+import { HF_AUDIO_CARVE_ATTR } from "@hyperframes/core/audio-carve";
+import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
+import { HF_COLOR_GRADING_ATTR } from "@hyperframes/core/color-grading";
+import type { TimelineElement } from "../store/playerStore";
+import { useLivePreviewIframe } from "../store/previewIframeStore";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { findTimelineElementInIframe } from "../../hooks/timelineEditingHelpers";
+import { committedClipPath } from "../../components/editor/cropPresetStore";
+import { isAudibleVideoNode } from "../lib/timelineElementHelpers";
+import type { ClipToolState } from "./clipToolAttrs";
+
+const LINK_ATTR = "data-link";
+
+const WATCHED_ATTRS = [
+  HF_AUDIO_FX_ATTR,
+  HF_AUDIO_AUTOMATION_ATTR,
+  HF_AUDIO_CARVE_ATTR,
+  HF_COLOR_GRADING_ATTR,
+  LINK_ATTR,
+  "data-volume",
+  "data-has-audio",
+  "muted",
+  "style",
+];
+
+function readVolume(node: Element): number | null {
+  const volume = Number.parseFloat(node.getAttribute("data-volume") ?? "");
+  return Number.isFinite(volume) ? volume : null;
+}
+
+function toolStateFromNode(node: Element): ClipToolState {
+  const tag = node.tagName.toLowerCase();
+  return {
+    tag,
+    hasSound: tag === "audio" || isAudibleVideoNode(node),
+    volume: readVolume(node),
+    muted: node.hasAttribute("muted"),
+    fxChain: node.getAttribute(HF_AUDIO_FX_ATTR),
+    automation: node.getAttribute(HF_AUDIO_AUTOMATION_ATTR),
+    colorGrading: node.getAttribute(HF_COLOR_GRADING_ATTR),
+    clipPath: committedClipPath(node),
+    carve: node.getAttribute(HF_AUDIO_CARVE_ATTR),
+    link: node.getAttribute(LINK_ATTR),
+  };
+}
+
+function toolStateFromElement(el: TimelineElement): ClipToolState {
+  const tag = el.tag.trim().toLowerCase();
+  return {
+    tag,
+    hasSound: tag === "audio" || el.hasAudio === true,
+    volume: el.volume ?? null,
+    muted: el.muted === true,
+    fxChain: el.fxChain ?? null,
+    automation: el.automation ?? null,
+    colorGrading: null,
+    clipPath: null,
+    carve: null,
+    link: null,
+  };
+}
+
+/** Inline style changes every frame under a tween; only a changed reading re-renders. */
+function keepIfUnchanged(prev: ClipToolState, next: ClipToolState): ClipToolState {
+  return JSON.stringify(prev) === JSON.stringify(next) ? prev : next;
+}
+
+/** A clip's tool attributes as the live preview node holds them, kept current as they change. */
+export function useClipToolState(el: TimelineElement): ClipToolState {
+  const iframe = useLivePreviewIframe();
+  const activeCompPath = useStudioShellContextOptional()?.activeCompPath ?? null;
+  const [state, setState] = useState<ClipToolState>(() => toolStateFromElement(el));
+
+  useEffect(() => {
+    const node = findTimelineElementInIframe(iframe, el, activeCompPath);
+    if (!node) {
+      setState(toolStateFromElement(el));
+      return;
+    }
+    const refresh = () => setState((prev) => keepIfUnchanged(prev, toolStateFromNode(node)));
+    refresh();
+    const view = node.ownerDocument.defaultView;
+    if (!view) return;
+    const observer = new view.MutationObserver(refresh);
+    observer.observe(node, { attributes: true, attributeFilter: WATCHED_ATTRS });
+    return () => observer.disconnect();
+  }, [iframe, el, activeCompPath]);
+
+  return state;
+}

package/src/player/lib/timelineElementHelpers.ts

@@ -231,6 +231,15 @@ export function isVideoAudible(opts: {
   return opts.tag.toLowerCase() === "video" && !opts.muted;
 }
 
+export function isAudibleVideoNode(el: Element): boolean {
+  if (el.tagName.toLowerCase() !== "video" || el.hasAttribute("muted")) return false;
+  return isVideoAudible({
+    tag: "video",
+    hasAudioAttr: el.getAttribute("data-has-audio"),
+    muted: false,
+  });
+}
+
 /** What the mixer gets: the compiler's `data-has-audio` rule, muted and volume. */
 function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): void {
   const media = resolveMediaElement(el) ?? el;

package/src/timelineChromeExports.test.tsx

@@ -6,6 +6,7 @@ import {
   AudioMeterStrip,
   TimelineHistoryButtons,
   TimelineToolbar,
+  useAudioMetersVisible as exportedAudioMetersVisible,
   useClipboard,
   usePlayerStore,
   type UseClipboardOptions,
@@ -51,6 +52,12 @@ describe("timeline chrome package exports, outside Studio's shell", () => {
     await act(async () => root.unmount());
   });
 
+  it("exports the meter visibility store a host toggles", () => {
+    expect(exportedAudioMetersVisible).toBe(useAudioMetersVisible);
+    exportedAudioMetersVisible.getState().setVisible(true);
+    expect(useAudioMetersVisible.getState().visible).toBe(true);
+  });
+
   it("runs the clipboard with no DOM edit session", async () => {
     const toasts: string[] = [];
     const options: UseClipboardOptions = {

package/src/utils/audioMeterMath.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../player";
 import {
+  hasProjectAudio,
   levelToFraction,
   markFraction,
   SILENT_CHANNEL,
@@ -42,3 +44,38 @@ describe("stepPair", () => {
     expect(stepPair(rest, { l: 1, r: 0 }, 32, 16)).not.toBe(rest);
   });
 });
+
+describe("hasProjectAudio", () => {
+  const clip = (overrides: Partial<TimelineElement>): TimelineElement => ({
+    id: "c",
+    tag: "div",
+    start: 0,
+    duration: 1,
+    track: 0,
+    ...overrides,
+  });
+
+  it("ignores an audible video left on native output at unity gain", () => {
+    expect(hasProjectAudio([clip({ tag: "video", hasAudio: true })])).toBe(false);
+    expect(hasProjectAudio([clip({ tag: "video", hasAudio: true, volume: 1 })])).toBe(false);
+  });
+
+  it.each<[string, Partial<TimelineElement>]>([
+    ["an above-unity gain", { volume: 2 }],
+    ["an fx chain", { fxChain: "[]" }],
+    ["automation", { automation: "{}" }],
+    ["a group", { audioGroup: "music" }],
+  ])("counts an audible video routed through Web Audio by %s", (_, fields) => {
+    expect(hasProjectAudio([clip({ tag: "video", hasAudio: true, ...fields })])).toBe(true);
+  });
+
+  it("ignores a muted video even when it carries processing", () => {
+    expect(hasProjectAudio([clip({ tag: "video", hasAudio: true, muted: true, volume: 2 })])).toBe(
+      false,
+    );
+  });
+
+  it("ignores a silent video", () => {
+    expect(hasProjectAudio([clip({ tag: "video" })])).toBe(false);
+  });
+});

package/src/utils/audioMeterMath.ts

@@ -1,5 +1,6 @@
 import { useMemo } from "react";
 import { audioDbToGain, audioGainToDb } from "@hyperframes/core/audio-gain";
+import { audibleVideoNeedsWebAudio } from "@hyperframes/core/audible-video";
 import { usePlayerStore, type TimelineElement } from "../player";
 import { isAudioTimelineElement } from "./timelineInspector";
 
@@ -67,9 +68,14 @@ export function stepPair(
   return [stepChannel(l, raw?.l ?? 0, now, dtMs), stepChannel(r, raw?.r ?? 0, now, dtMs)];
 }
 
-/** The meters appear only for a project with at least one audio clip or group. */
-function hasProjectAudio(elements: readonly TimelineElement[]): boolean {
-  return elements.some((el) => isAudioTimelineElement(el) || el.audioGroup !== undefined);
+/** The meters appear only for a project with an audio clip, a group, or a video Web Audio carries. */
+export function hasProjectAudio(elements: readonly TimelineElement[]): boolean {
+  return elements.some(
+    (el) =>
+      isAudioTimelineElement(el) ||
+      el.audioGroup !== undefined ||
+      (el.hasAudio === true && !el.muted && audibleVideoNeedsWebAudio(el)),
+  );
 }
 
 /** Scans once per `elements` change, not on every store update (the playhead ticks each frame). */

package/src/utils/exportPeakCeiling.ts

@@ -0,0 +1 @@
+export const EXPORT_PEAK_CEILING = 10 ** (-1 / 20);

package/src/utils/previewRelativePath.ts

@@ -0,0 +1,19 @@
+import { buildProjectApiPath } from "./projectRouting";
+
+/** Resolve a media src to its project-relative preview path, or null. */
+export function resolvePreviewRelative(
+  src: string | undefined,
+  pid: string,
+  origin: string,
+): string | null {
+  if (!src) return null;
+  try {
+    const parsed = new URL(src, origin);
+    const base = new URL(buildProjectApiPath(pid, `/preview/`), origin).pathname;
+    return parsed.pathname.startsWith(base)
+      ? decodeURIComponent(parsed.pathname.slice(base.length))
+      : null;
+  } catch {
+    return null;
+  }
+}

package/src/utils/sourcePatcher.ts

@@ -21,7 +21,7 @@ export function escapeHtmlAttribute(value: string): string {
 }
 
 /** Reverse escapeHtmlAttribute so callers get the original value. */
-function unescapeHtmlAttribute(value: string): string {
+export function unescapeHtmlAttribute(value: string): string {
   return value
     .replace(/"/g, '"')
     .replace(/&lt;/g, "<")

package/src/utils/studioPendingEdits.test.ts

@@ -2,8 +2,10 @@
 import { describe, expect, it, vi } from "vitest";
 import {
   addStudioPendingEditFlushListener,
+  beginStudioPendingEdit,
   flushStudioPendingEdits,
   hasStudioPendingEdits,
+  revertNewestStudioPendingEdit,
   trackStudioPendingEdit,
   trackedStudioEdit,
 } from "./studioPendingEdits";
@@ -211,3 +213,67 @@ describe("trackedStudioEdit", () => {
     expect(hasStudioPendingEdits()).toBe(false);
   });
 });
+
+describe("a pending edit undo can paint back", () => {
+  const shown: string[] = [];
+  const edit = (name: string) =>
+    beginStudioPendingEdit(() => {
+      shown.push(`${name} undone`);
+      return () => shown.push(`${name} again`);
+    });
+
+  it("paints back only the newest edit, once, and shows it again on request", () => {
+    shown.length = 0;
+    const first = edit("first");
+    const second = edit("second");
+    const again = revertNewestStudioPendingEdit();
+    expect(shown).toEqual(["second undone"]);
+    expect(second.reverted()).toBe(true);
+    expect(first.reverted()).toBe(false);
+    expect(revertNewestStudioPendingEdit()).toBeNull();
+    again!();
+    expect(shown).toEqual(["second undone", "second again"]);
+    first.settle();
+    second.settle();
+  });
+
+  it("paints nothing when the newest edit has no revert", async () => {
+    shown.length = 0;
+    const move = edit("move");
+    let saved!: () => void;
+    trackStudioPendingEdit(new Promise<void>((resolve) => (saved = resolve)));
+    expect(revertNewestStudioPendingEdit()).toBeNull();
+    expect(shown).toEqual([]);
+    saved();
+    move.settle();
+    await flushStudioPendingEdits();
+  });
+
+  it("counts what the edit starts inside adopt as that edit, not a newer one", async () => {
+    shown.length = 0;
+    const move = edit("move");
+    let saved!: () => void;
+    const save = move.adopt(() =>
+      trackStudioPendingEdit(new Promise<void>((resolve) => (saved = resolve))),
+    );
+    move.settle(save);
+    revertNewestStudioPendingEdit();
+    expect(shown).toEqual(["move undone"]);
+    saved();
+    await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
+    expect(hasStudioPendingEdits()).toBe(false);
+  });
+});
+
+describe("a pending edit whose start throws", () => {
+  it("ends, so undo and export never wait on it", async () => {
+    const edit = beginStudioPendingEdit(null);
+    expect(() =>
+      edit.adopt(() => {
+        throw new Error("The commit threw.");
+      }),
+    ).toThrow("The commit threw.");
+    await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
+    expect(hasStudioPendingEdits()).toBe(false);
+  });
+});

package/src/utils/studioPendingEdits.ts

@@ -9,7 +9,10 @@ interface StudioFlushPendingEditsDetail {
 
 export type StudioPendingEditsDrainResult = StudioSaveDrainResult;
 
-const pendingEditPromises = new Set<Promise<unknown>>();
+export type StudioEditRevert = () => () => void;
+
+const pendingEdits = new Map<Promise<unknown>, { revert: StudioEditRevert | null }>();
+let adopting = false;
 
 function waitForPostBlurEffects(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
@@ -34,11 +37,11 @@ function focusedField(): HTMLElement | null {
 }
 
 export function hasStudioPendingEdits(): boolean {
-  return pendingEditPromises.size > 0 || focusedField() !== null;
+  return pendingEdits.size > 0 || focusedField() !== null;
 }
 
 export function isStudioEditSaving(): boolean {
-  return pendingEditPromises.size > 0;
+  return pendingEdits.size > 0;
 }
 
 export function afterStudioPendingEdits(run: () => void): () => void {
@@ -46,7 +49,7 @@ export function afterStudioPendingEdits(run: () => void): () => void {
   const check = () => {
     if (!waiting) return;
     if (isStudioEditSaving()) {
-      void Promise.allSettled([...pendingEditPromises]).then(check);
+      void Promise.allSettled([...pendingEdits.keys()]).then(check);
       return;
     }
     waiting = false;
@@ -63,10 +66,11 @@ export function trackStudioPendingEdit(
 ): Promise<unknown> | undefined {
   if (!result) return undefined;
   const promise = Promise.resolve(result);
-  pendingEditPromises.add(promise);
+  if (adopting) return promise;
+  pendingEdits.set(promise, { revert: null });
   promise.then(
-    () => pendingEditPromises.delete(promise),
-    () => pendingEditPromises.delete(promise),
+    () => pendingEdits.delete(promise),
+    () => pendingEdits.delete(promise),
   );
   return promise;
 }
@@ -81,12 +85,42 @@ export function trackedStudioEdit<Args extends unknown[], R>(
   };
 }
 
+export function beginStudioPendingEdit(revert: StudioEditRevert | null) {
+  let settle!: (saved?: Promise<unknown>) => void;
+  const promise = trackStudioPendingEdit(new Promise<unknown>((resolve) => (settle = resolve)))!;
+  const entry = pendingEdits.get(promise)!;
+  entry.revert = revert;
+  return {
+    settle,
+    reverted: () => entry.revert === null && revert !== null,
+    // Only what `start` registers synchronously is adopted; a registration after an await is a newer edit.
+    adopt<T>(start: () => T): T {
+      adopting = true;
+      try {
+        return start();
+      } catch (error) {
+        settle();
+        throw error;
+      } finally {
+        adopting = false;
+      }
+    },
+  };
+}
+
+export function revertNewestStudioPendingEdit(): (() => void) | null {
+  const newest = [...pendingEdits.values()].at(-1);
+  const revert = newest?.revert;
+  if (!newest || !revert) return null;
+  newest.revert = null;
+  return revert();
+}
+
 export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrainResult> {
   const active = focusedField();
   if (active) {
     active.blur();
-    // ponytail: Preserve synchronous/microtask blur commits, then cross one task boundary
-    // so React effects triggered by the blur can register their flush listener.
+    // ponytail: keep blur commits, then cross one task so effects the blur runs can add their listener.
     await Promise.resolve();
     await waitForPostBlurEffects();
   }
@@ -96,8 +130,8 @@ export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrain
   );
   let conflict: StudioFileConflictError | undefined;
   let firstFailure: PromiseRejectedResult | undefined;
-  while (detail.promises.length > 0 || pendingEditPromises.size > 0) {
-    const promises = [...detail.promises, ...pendingEditPromises];
+  while (detail.promises.length > 0 || pendingEdits.size > 0) {
+    const promises = [...detail.promises, ...pendingEdits.keys()];
     detail.promises = [];
     const batchFailures = inspectDrainFailures(await Promise.allSettled(promises));
     conflict ??= batchFailures.conflict;

package/src/utils/timelineInspector.test.ts

@@ -4,6 +4,7 @@ import {
   canHideSelections,
   isAudioDomElement,
   isAudioTimelineElement,
+  isMusicSourceElement,
   isMusicTrack,
   resolveBeatSourceTrack,
 } from "./timelineInspector";
@@ -12,9 +13,15 @@ import type { TimelineElement } from "../player";
 // Minimal element factory for tests
 function el(
   overrides: Partial<
-    Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "duration">
+    Pick<
+      TimelineElement,
+      "tag" | "src" | "id" | "domId" | "timelineRole" | "duration" | "hasAudio" | "muted"
+    >
   >,
-): Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "duration"> {
+): Pick<
+  TimelineElement,
+  "tag" | "src" | "id" | "domId" | "timelineRole" | "duration" | "hasAudio" | "muted"
+> {
   return {
     tag: "audio",
     src: "assets/track.mp3",
@@ -153,3 +160,27 @@ describe("isAudioDomElement / canHideSelections", () => {
     expect(canHideSelections([{ element: el("hf-audio-group") }])).toBe(false);
   });
 });
+
+describe("beat source from a video with sound", () => {
+  const talk = { tag: "video", src: "assets/clip.mp4", hasAudio: true };
+
+  it("counts an audible video as a music source but never a muted or silent one", () => {
+    expect(isMusicSourceElement(el(talk))).toBe(true);
+    expect(isMusicSourceElement(el({ ...talk, muted: true }))).toBe(false);
+    expect(isMusicSourceElement(el({ ...talk, hasAudio: false }))).toBe(false);
+    expect(isAudioTimelineElement(el(talk))).toBe(false);
+  });
+
+  it("takes a video tagged as music as the beat source", () => {
+    const video = el({ ...talk, timelineRole: "music" });
+    expect(isMusicTrack(video)).toBe(true);
+    expect(resolveBeatSourceTrack([video])).toEqual({ element: video, isFallback: false });
+  });
+
+  it("falls back to the longest audible video when there is no audio", () => {
+    const short = el({ ...talk, id: "a", duration: 3 });
+    const long = el({ ...talk, id: "b", duration: 9 });
+    const muted = el({ ...talk, id: "c", duration: 20, muted: true });
+    expect(resolveBeatSourceTrack([short, long, muted])?.element).toBe(long);
+  });
+});

package/src/utils/timelineInspector.ts

@@ -44,17 +44,29 @@ export function isAudioOrVideoTimelineElement(
   return isAudioTimelineElement(element) || element.tag.trim().toLowerCase() === "video";
 }
 
+type MusicSourceFacts = Pick<TimelineElement, "tag" | "src" | "hasAudio" | "muted">;
+
+/** Can carry the music: an audio clip, or a video whose own sound plays. Lane zoning is unaffected. */
+export function isMusicSourceElement(element: MusicSourceFacts): boolean {
+  if (isAudioTimelineElement(element)) return true;
+  return (
+    element.tag.trim().toLowerCase() === "video" &&
+    element.hasAudio === true &&
+    element.muted !== true
+  );
+}
+
 /** True for the music track: an audio element with data-timeline-role="music",
  *  or — when no role is set — an id matching the music regex. Voiceover/other
  *  audio (explicit non-music role) is excluded. */
 export function isMusicTrack(
   element:
-    | Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole">
+    | Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "hasAudio" | "muted">
     | null
     | undefined,
 ): boolean {
   if (!element) return false;
-  if (!isAudioTimelineElement(element)) return false;
+  if (!isMusicSourceElement(element)) return false;
   if (element.timelineRole === "music") return true;
   if (element.timelineRole && element.timelineRole !== "music") return false;
   const id = element.domId ?? element.id ?? "";
@@ -75,7 +87,7 @@ export function isMusicTrack(
 export function resolveBeatSourceTrack(
   elements: readonly Pick<
     TimelineElement,
-    "tag" | "src" | "id" | "domId" | "timelineRole" | "duration"
+    "tag" | "src" | "id" | "domId" | "timelineRole" | "duration" | "hasAudio" | "muted"
   >[],
 ): { element: (typeof elements)[number]; isFallback: boolean } | null {
   const explicit = elements.find(isMusicTrack);
@@ -85,7 +97,7 @@ export function resolveBeatSourceTrack(
   // like "sfx" or "voiceover" to avoid triggering beat analysis on those).
   let best: (typeof elements)[number] | null = null;
   for (const el of elements) {
-    if (!isAudioTimelineElement(el)) continue;
+    if (!isMusicSourceElement(el)) continue;
     if (el.timelineRole && el.timelineRole !== "music") continue;
     if (!best || el.duration > best.duration) best = el;
   }