@hyperframes/studio 0.8.80 → 0.8.82

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

@@ -11,6 +11,7 @@ import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
 import { SILENT_CHANNEL } from "../../utils/audioMeterMath";
 import {
   AudioMeterStrip,
+  type AudioMeterStripProps,
   evictGoneMeterState,
   followMeterHook,
   stepAndPaintStrips,
@@ -20,8 +21,9 @@ import {
 
 const iframe = { contentWindow: null as unknown };
 const previewIframeRef = { current: iframe };
+let shell: { previewIframeRef: typeof previewIframeRef } | null = { previewIframeRef };
 vi.mock("../../contexts/StudioContext", () => ({
-  useStudioShellContext: () => ({ previewIframeRef }),
+  useStudioShellContextOptional: () => shell,
 }));
 
 const onSetAudioGroupAttributeLive = vi.fn();
@@ -88,6 +90,7 @@ const tick = () => {
 };
 
 beforeEach(() => {
+  shell = { previewIframeRef };
   frames = [];
   vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => frames.push(cb));
   vi.stubGlobal("cancelAnimationFrame", () => {});
@@ -103,11 +106,11 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
-function mount() {
+function mount(props: AudioMeterStripProps = {}) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
-  act(() => root.render(<AudioMeterStrip />));
+  act(() => root.render(<AudioMeterStrip {...props} />));
   roots.push(root);
   return { host, root };
 }
@@ -177,6 +180,26 @@ describe("AudioMeterStrip", () => {
     expect(second.read).toHaveBeenCalled();
   });
 
+  it("reads a host's preview iframe over the shell's", () => {
+    usePlayerStore.setState({ elements: [clip({ audioGroup: "vo" })] });
+    const shellHook = makeHook();
+    setHook(shellHook);
+    const hostHook = makeHook();
+    const hostIframe = { contentWindow: { __hf: { audioMeter: hostHook } } };
+    mount({ previewIframeRef: { current: hostIframe as unknown as HTMLIFrameElement } });
+    tick();
+    expect(hostHook.start).toHaveBeenCalledTimes(1);
+    expect(shellHook.start).not.toHaveBeenCalled();
+  });
+
+  it("mounts with no shell and no preview iframe", () => {
+    shell = null;
+    usePlayerStore.setState({ elements: [clip({ audioGroup: "vo" })] });
+    const { host } = mount();
+    tick();
+    expect(host.querySelector("[data-testid=audio-meter-strip]")).not.toBeNull();
+  });
+
   it("keeps authored gain 2 above unity and writes exactly 1 at the midpoint", () => {
     usePlayerStore.setState({ elements: [clip({ audioGroup: "vo", audioGroupVolume: 2 })] });
     const { host } = mount();

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/panels/VariablesOtherCompositions.tsx

@@ -85,7 +85,7 @@ function CompositionSection({
 }
 
 export function VariablesOtherCompositions({
-  fileTree,
+  compositionPaths,
   excludePath,
   refreshKey,
   readProjectFile,
@@ -93,8 +93,8 @@ export function VariablesOtherCompositions({
   recordEdit,
   reloadPreview,
 }: {
-  fileTree: string[];
-  excludePath: string;
+  compositionPaths: string[];
+  excludePath: string | null;
   refreshKey: unknown;
   readProjectFile: (path: string) => Promise<string>;
   writeProjectFile: (path: string, content: string) => Promise<void>;
@@ -103,7 +103,7 @@ export function VariablesOtherCompositions({
 }) {
   const [selfRefresh, setSelfRefresh] = useState(0);
   const groups = useProjectCompositionVariables(
-    fileTree,
+    compositionPaths,
     excludePath,
     readProjectFile,
     `${refreshKey}:${selfRefresh}`,

package/src/components/panels/VariablesPanel.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { openComposition } from "@hyperframes/sdk";
+import { VariablesPanel } from "./VariablesPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const withTitle = (id: string, label: string) => `<!DOCTYPE html>
+<html data-composition-variables='[{"id":"title","type":"string","label":"${label}","default":"Hello"}]'>
+<body><div data-composition-id="${id}" data-hf-id="hf-stage" data-hf-root data-duration="5"></div></body>
+</html>`;
+
+const files: Record<string, string> = {
+  "index.html":
+    '<html><body><div data-hf-id="hf-stage" data-hf-root data-duration="5"></div></body></html>',
+  "main.html": withTitle("main", "Main title"),
+  "scene.html": withTitle("scene", "Scene title"),
+  ".hyperframes/preview/4884df6e.html": withTitle("root", "Generated title"),
+};
+const shell = {
+  activeCompPath: "index.html" as string | null,
+  compositions: ["index.html", "scene.html"],
+};
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({ activeCompPath: shell.activeCompPath, showToast: vi.fn() }),
+  useStudioPlaybackContext: () => ({ refreshKey: 0 }),
+}));
+vi.mock("../../contexts/DomEditContext", () => ({
+  useDomEditContext: () => ({ domEditSelection: null }),
+}));
+vi.mock("../../contexts/FileManagerContext", () => ({
+  useFileManagerContext: () => ({
+    readProjectFile: async (path: string) => files[path] ?? "",
+    writeProjectFile: vi.fn(),
+    fileTree: Object.keys(files),
+    compositions: shell.compositions,
+  }),
+}));
+
+let root: Root | null = null;
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  document.body.innerHTML = "";
+});
+
+async function renderOtherCompositions(sessionPath: string): Promise<string> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  const session = await openComposition(files[sessionPath]!, { history: false });
+  await act(async () => {
+    root?.render(
+      <VariablesPanel
+        sdkSession={session}
+        publishSdkSession={vi.fn()}
+        reloadPreview={vi.fn()}
+        recordEdit={vi.fn(async () => {})}
+      />,
+    );
+  });
+  const other = () =>
+    [...host.querySelectorAll("p")].find((p) => p.textContent === "Other compositions")
+      ?.parentElement?.textContent ?? "";
+  await vi.waitFor(() => expect(other()).toContain("scene.html"));
+  return other();
+}
+
+describe("VariablesPanel other compositions", () => {
+  it("lists the project's compositions, not Studio's generated preview documents", async () => {
+    shell.activeCompPath = "index.html";
+    shell.compositions = ["index.html", "scene.html"];
+    expect(await renderOtherCompositions("index.html")).not.toContain(".hyperframes/preview");
+  });
+
+  it("leaves out the main composition in the master view when it is not index.html", async () => {
+    shell.activeCompPath = null;
+    shell.compositions = ["main.html", "scene.html"];
+    expect(await renderOtherCompositions("main.html")).not.toContain("main.html");
+  });
+});

package/src/components/panels/VariablesPanel.tsx

@@ -254,7 +254,7 @@ export const VariablesPanel = memo(function VariablesPanel({
 }: VariablesPanelProps) {
   const { activeCompPath, showToast } = useStudioShellContext();
   const { refreshKey } = useStudioPlaybackContext();
-  const { readProjectFile, writeProjectFile, fileTree, compositions } = useFileManagerContext();
+  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
   const { domEditSelection } = useDomEditContext();
   // Master view (no activeCompPath) targets the real main composition, not a
   // hardcoded index.html — used for both the persist write target and the
@@ -537,8 +537,8 @@ export const VariablesPanel = memo(function VariablesPanel({
           </button>
         )}
         <VariablesOtherCompositions
-          fileTree={fileTree}
-          excludePath={activeCompPath ?? "index.html"}
+          compositionPaths={compositions}
+          excludePath={effectiveCompPath}
           refreshKey={`${refreshKey}:${revision}`}
           readProjectFile={readProjectFile}
           writeProjectFile={writeProjectFile}

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/sidebar/SidebarLintButton.test.tsx

@@ -44,6 +44,35 @@ describe("SidebarLintButton badge", () => {
     expect(badge?.textContent).toContain("including errors");
   });
 
+  it("pulses a few times and then holds still, so an idle Studio paints nothing", () => {
+    const badge = renderBadge(true);
+    expect(badge?.style.animationIterationCount).toBe("3");
+  });
+
+  it("pulses again when the finding count changes", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    root = createRoot(host);
+    const render = (findingCount: number) =>
+      act(() => {
+        root?.render(
+          <SidebarLintButton
+            onLint={vi.fn()}
+            linting={false}
+            findingCount={findingCount}
+            hasError
+          />,
+        );
+      });
+    render(2);
+    const first = host.querySelector("[data-lint-badge]");
+    render(2);
+    expect(host.querySelector("[data-lint-badge]")).toBe(first);
+    render(3);
+    // A new element restarts its CSS animation; a text change on the old one would not.
+    expect(host.querySelector("[data-lint-badge]")).not.toBe(first);
+  });
+
   it("stays still when the findings are warnings only", () => {
     const badge = renderBadge(false);
     expect(badge?.dataset.lintBadge).toBe("warning");

package/src/components/sidebar/SidebarLintButton.tsx

@@ -1,3 +1,5 @@
+const ERROR_PULSES_BEFORE_IDLE = 3;
+
 export function SidebarLintButton({
   onLint,
   linting,
@@ -31,7 +33,9 @@ export function SidebarLintButton({
         {linting ? "Linting…" : "Lint"}
         {!linting && findingCount != null && findingCount > 0 && (
           <span
+            key={findingCount}
             data-lint-badge={hasError ? "error" : "warning"}
+            style={hasError ? { animationIterationCount: ERROR_PULSES_BEFORE_IDLE } : undefined}
             className={
               hasError
                 ? "ml-1 min-w-[16px] rounded-full bg-panel-danger/25 px-1 text-[9px] font-bold text-panel-danger animate-pulse motion-reduce:animate-none"

package/src/components/studioColorGradingScope.ts

@@ -22,7 +22,7 @@ interface ApplyColorGradingScopeOptions {
   scope: ColorGradingScope;
   value: string | null;
   selectedSourceFile: string;
-  fileTree: string[];
+  compositionPaths: string[];
   projectId: string;
   waitForPendingDomEditSaves: () => Promise<void>;
   readProjectFile: ProjectFileReader;
@@ -35,36 +35,9 @@ interface ApplyColorGradingScopeOptions {
 function colorGradingScopePaths(
   scope: ColorGradingScope,
   selectedSourceFile: string,
-  fileTree: string[],
+  compositionPaths: string[],
 ): string[] {
-  return scope === "source-file"
-    ? [selectedSourceFile]
-    : fileTree.filter((path) => /\.html?$/i.test(path));
-}
-
-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 };
+  return scope === "source-file" ? [selectedSourceFile] : compositionPaths;
 }
 
 // fallow-ignore-next-line complexity
@@ -72,7 +45,7 @@ export async function applyColorGradingScopeUpdate({
   scope,
   value,
   selectedSourceFile,
-  fileTree,
+  compositionPaths,
   projectId,
   waitForPendingDomEditSaves,
   readProjectFile,
@@ -90,24 +63,25 @@ export async function applyColorGradingScopeUpdate({
     return EMPTY_COLOR_GRADING_SCOPE_RESULT;
   }
 
-  const { files, changedElements } = await patchColorGradingScopeFiles(
-    colorGradingScopePaths(scope, selectedSourceFile, fileTree),
-    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>;
 }