@hyperframes/studio 0.8.116 → 0.8.118

package/src/player/components/TimelineTrackPlainHeader.tsx

@@ -1,39 +1,28 @@
 import type React from "react";
-import { Eye, EyeSlash } from "@phosphor-icons/react";
 import { Music } from "../../icons/SystemIcons";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { TrackClipCount } from "./TrackClipCount";
 import { trackDisplaySuffix } from "./timelineTrackDisplay";
-
-// Hide, plainly. The speaker variant was the mute presentation; with mute gone
-// this is the visibility eye it always was, and audio rows do not render it.
-function visibilityButtonLabel(hidden: boolean, suffix: string): string {
-  return hidden ? `Show track${suffix}` : `Hide track${suffix}`;
-}
-
-function visibilityButtonIcon(hidden: boolean) {
-  const Icon = hidden ? EyeSlash : Eye;
-  return <Icon size={14} weight="bold" aria-hidden="true" />;
-}
+import { HiddenToggleIcon, hiddenToggleVerb } from "./hiddenToggle";
 
 export function VisibilityButton({
   hidden,
   trackNumber,
   trackDisplayNumber,
-  visible,
+  asMute,
   onToggle,
 }: {
   hidden: boolean;
   trackNumber: number;
   trackDisplayNumber: number | null;
-  visible: boolean;
+  /** `data-hidden` silences an audio-only track, so its toggle is a mute. */
+  asMute: boolean;
   onToggle: TimelineEditCallbacks["onToggleTrackHidden"];
 }) {
-  if (!visible) return <span aria-hidden="true" className="h-6 w-6 shrink-0" />;
   // Display number in the text, real key in the callback. The two must not be
   // conflated in either direction.
   const suffix = trackDisplaySuffix(trackDisplayNumber);
-  const label = visibilityButtonLabel(hidden, suffix);
+  const label = `${hiddenToggleVerb(asMute, hidden)} track${suffix}`;
   return (
     <button
       type="button"
@@ -52,7 +41,7 @@ export function VisibilityButton({
         void onToggle?.(trackNumber, !hidden, trackDisplayNumber);
       }}
     >
-      {visibilityButtonIcon(hidden)}
+      <HiddenToggleIcon asMute={asMute} hidden={hidden} size={14} />
     </button>
   );
 }
@@ -67,6 +56,7 @@ export function PlainTrackHeader({
   showTrackLabel,
   isTrackHidden,
   isAudioTrack,
+  isAudioOnly,
   onToggleTrackHidden,
   trailing,
 }: {
@@ -76,6 +66,7 @@ export function PlainTrackHeader({
   clipCount: number;
   isTrackHidden: boolean;
   isAudioTrack: boolean;
+  isAudioOnly: boolean;
   onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
   showTrackLabel: boolean;
   /** Trailing controls that belong on the control line — the FX entry points,
@@ -111,25 +102,11 @@ export function PlainTrackHeader({
             truncating name leaves, so the controls sit on the edge whatever the
             name's length. */}
         <div className="ml-auto flex shrink-0 items-center gap-1">
-          {/* Not on an audio track. The control is the old visibility eye, and
-            on audio it silences rather than hides — but a row that already says
-            what it is with a speaker does not also need the hide affordance
-            sitting in the eye's slot. `visible={false}` rather than omitting the
-            element, so the spacer keeps every row's control columns aligned.
-
-            EXCEPT when the audio track is ALREADY hidden. Withholding the
-            control unconditionally withheld the only way back: `data-hidden`
-            silences the clip in preview and drops it from the render, the
-            panel's "Muted" is the unrelated HTML `muted` attribute, and nothing
-            else writes it — so a track hidden before this rule (or by "Hide
-            all", or by hand) was silent with no control anywhere to restore it.
-            Offering the eye only in that state keeps the affordance off a normal
-            audio row while leaving the door open from the inside. */}
           <VisibilityButton
             hidden={isTrackHidden}
             trackNumber={trackNumber}
             trackDisplayNumber={trackDisplayNumber}
-            visible={!isAudioTrack || isTrackHidden}
+            asMute={isAudioOnly}
             onToggle={onToggleTrackHidden}
           />
           {trailing}

package/src/player/components/hiddenToggle.tsx

@@ -0,0 +1,20 @@
+import { Eye, EyeSlash, SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
+
+/** The action a hide toggle offers from the current `hidden` state; on audio `data-hidden` is a mute. */
+export function hiddenToggleVerb(asMute: boolean, hidden: boolean): string {
+  if (asMute) return hidden ? "Unmute" : "Mute";
+  return hidden ? "Show" : "Hide";
+}
+
+export function HiddenToggleIcon({
+  asMute,
+  hidden,
+  size,
+}: {
+  asMute: boolean;
+  hidden: boolean;
+  size: number;
+}) {
+  const Icon = asMute ? (hidden ? SpeakerSlash : SpeakerHigh) : hidden ? EyeSlash : Eye;
+  return <Icon size={size} weight="bold" aria-hidden="true" />;
+}

package/src/utils/gsapSoftReload.test.ts

@@ -249,7 +249,7 @@ describe("applySoftReload", () => {
     // gsap present but MotionPathPlugin unset → async load path.
     const { iframe, contentWindow } = buildMockIframe({
       MotionPathPlugin: undefined,
-      gsap: { timeline: vi.fn(), registerPlugin: vi.fn() },
+      gsap: { timeline: vi.fn(), registerPlugin: vi.fn(), version: "3.14.2" },
     });
     (iframe.contentDocument as unknown as { head: unknown }).head = head;
 
@@ -260,7 +260,7 @@ describe("applySoftReload", () => {
     // script has NOT executed yet, so the timeline isn't rebound synchronously.
     expect(result).toBe("applied");
     expect(appendedScripts).toHaveLength(1);
-    expect(appendedScripts[0]!.src).toContain("MotionPathPlugin");
+    expect(appendedScripts[0]!.src).toContain("gsap@3.14.2/dist/MotionPathPlugin");
     expect(contentWindow.__hfForceTimelineRebind).not.toHaveBeenCalled();
 
     // onerror must NOT run the script (that would reference a missing plugin) —
@@ -384,6 +384,16 @@ describe("ensureMotionPathPluginLoaded", () => {
     expect(appendedScripts).toHaveLength(0);
   });
 
+  it("loads the plugin at the composition's own gsap version", () => {
+    const { iframe, appendedScripts } = buildBootstrapIframe({
+      gsap: { version: "3.14.2", registerPlugin: vi.fn() },
+    });
+    ensureMotionPathPluginLoaded(iframe);
+    expect(appendedScripts[0]!.src).toBe(
+      "https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/MotionPathPlugin.min.js",
+    );
+  });
+
   it("appends the plugin script once and registers it on load", () => {
     const { iframe, contentWindow, appendedScripts, registerPlugin } = buildBootstrapIframe();
     ensureMotionPathPluginLoaded(iframe);
@@ -481,6 +491,45 @@ describe("applySoftReload authored-style restore", () => {
     return el.style.getPropertyValue("opacity");
   }
 
+  it("flushes only elements when a tween targets a plain object (the runtime's duration filler)", () => {
+    const el = document.createElement("div");
+    // GSAP's clearProps writes target.style.cssText, which throws on a plain object.
+    const set = vi.fn((targets: Array<{ style: CSSStyleDeclaration }>) => {
+      for (const t of targets) t.style.cssText = "";
+    });
+    const { iframe } = buildIframeWithTarget(el, {
+      gsap: { timeline: vi.fn(), set },
+      __timelines: {
+        root: {
+          kill: vi.fn(),
+          getChildren: () => [{ targets: () => [el] }, { targets: () => [{}] }],
+        },
+      },
+    });
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("applied");
+    expect(set).toHaveBeenCalledWith([el], { clearProps: "all" });
+  });
+
+  it("falls back to a full reload, and says why, when the flush throws", () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { iframe } = buildIframeWithTarget(document.createElement("div"), {
+      gsap: {
+        timeline: vi.fn(),
+        set: vi.fn(() => {
+          throw new Error("flush failed");
+        }),
+      },
+    });
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
+    expect(error).toHaveBeenCalledWith(
+      expect.stringContaining("soft reload threw"),
+      expect.any(Error),
+    );
+    error.mockRestore();
+  });
+
   it("restores opacity from the after-write HTML (matched by data-hf-id)", () => {
     const el = document.createElement("img");
     el.setAttribute("data-hf-id", "hf-1");

package/src/utils/gsapSoftReload.ts

@@ -1,4 +1,5 @@
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+import { motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
 import { findAuthoredElement } from "./authoredSource";
 import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "./authoredOpacity";
 import { authoringFile, collectResetTargets, compositionFile, fileDocs } from "./softReloadTargets";
@@ -14,6 +15,7 @@ type IframeWindow = Window & {
   // re-flash the iframe. Cleared once the plugin loads or errors.
   __hfMotionPathPluginLoading?: boolean;
   gsap?: {
+    version?: string;
     timeline?: (...args: unknown[]) => unknown;
     registerPlugin?: (...plugins: unknown[]) => unknown;
     set?: (targets: Element | Element[], vars: Record<string, unknown>) => void;
@@ -22,14 +24,6 @@ type IframeWindow = Window & {
   MotionPathPlugin?: unknown;
 };
 
-/**
- * CDN URL for the GSAP MotionPathPlugin. Shared between the one-time preview
- * bootstrap (ensureMotionPathPluginLoaded) and the soft-reload fallback so the
- * version is pinned in a single place.
- */
-const MOTION_PATH_PLUGIN_CDN =
-  "https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/MotionPathPlugin.min.js";
-
 /**
  * Pre-load + register MotionPathPlugin ONCE in the preview iframe so
  * `win.MotionPathPlugin` is reliably set before any studio edit. Called from the
@@ -66,7 +60,7 @@ export function ensureMotionPathPluginLoaded(iframe: HTMLIFrameElement | null):
   try {
     win.__hfMotionPathPluginLoading = true;
     const pluginScript = doc.createElement("script");
-    pluginScript.src = MOTION_PATH_PLUGIN_CDN;
+    pluginScript.src = motionPathPluginUrl(win.gsap?.version);
     const finalize = () => {
       win.__hfMotionPathPluginLoading = false;
       try {
@@ -152,7 +146,8 @@ function runSuppressed(win: IframeWindow, reload: () => void): boolean {
     if (win.__hfSuppressSceneMutations) win.__hfSuppressSceneMutations(reload);
     else reload();
     return true;
-  } catch {
+  } catch (error) {
+    console.error("[Studio] GSAP soft reload threw; falling back to a full reload", error);
     return false;
   }
 }
@@ -369,16 +364,11 @@ export function applySoftReload(
     // HTML `style=""` attribute. Save → clear → restore → what GSAP wrote, from the file.
     const allTargets = [...targets.keys()];
     if (allTargets.length > 0 && win.gsap?.set) {
-      const saved: Array<[HTMLElement, string]> = [];
-      for (const el of allTargets) {
-        // Iframe-realm node: instanceof HTMLElement fails across realms, and
-        // gsap targets() only yields elements here — style access is duck-typed.
-        const styled = el as HTMLElement;
-        if (styled.style?.cssText != null) saved.push([styled, styled.style.cssText]);
-      }
-      try {
-        win.gsap.set(allTargets, { clearProps: "all" });
-      } catch {}
+      // Iframe-realm nodes: instanceof HTMLElement fails across realms, so style access is duck-typed.
+      const saved = allTargets.map(
+        (el) => [el as HTMLElement, (el as HTMLElement).style.cssText] as const,
+      );
+      win.gsap.set(allTargets, { clearProps: "all" });
       for (const [el, css] of saved) {
         const s = el.style;
         s.cssText = css;
@@ -449,7 +439,7 @@ export function applySoftReload(
       }
       win.__hfMotionPathPluginLoading = true;
       const pluginScript = doc.createElement("script");
-      pluginScript.src = MOTION_PATH_PLUGIN_CDN;
+      pluginScript.src = motionPathPluginUrl(win.gsap?.version);
       pluginScript.onload = () => {
         win.__hfMotionPathPluginLoading = false;
         executeScript();

package/src/utils/gsapUndoRestore.browser.test.ts

@@ -16,11 +16,9 @@ const CROP = "inset(0px 40px 0px 0px)";
 vi.setConfig({ testTimeout: 60_000, hookTimeout: 60_000 });
 let browser: Browser;
 let undoBundle: string;
+let softReloadBundle: string;
 
-beforeAll(async () => {
-  const executablePath = findSystemChrome();
-  if (!executablePath) throw new Error("no Chrome found: set HYPERFRAMES_BROWSER_PATH");
-  browser = await puppeteer.launch({ executablePath, headless: true, args: ["--no-sandbox"] });
+async function bundle(file: string, name: string): Promise<string> {
   const out = await build({
     configFile: false,
     logLevel: "silent",
@@ -30,68 +28,85 @@ beforeAll(async () => {
     build: {
       write: false,
       minify: false,
-      lib: {
-        entry: fileURLToPath(new URL("./gsapUndoRestore.ts", import.meta.url)),
-        formats: ["iife"],
-        name: "hfUndo",
-      },
+      lib: { entry: fileURLToPath(new URL(file, import.meta.url)), formats: ["iife"], name },
     },
   });
-  undoBundle = (Array.isArray(out) ? out[0]! : (out as { output: [{ code: string }] })).output[0]
-    .code;
+  return (Array.isArray(out) ? out[0]! : (out as { output: [{ code: string }] })).output[0].code;
+}
+
+beforeAll(async () => {
+  const executablePath = findSystemChrome();
+  if (!executablePath) throw new Error("no Chrome found: set HYPERFRAMES_BROWSER_PATH");
+  browser = await puppeteer.launch({ executablePath, headless: true, args: ["--no-sandbox"] });
+  undoBundle = await bundle("./gsapUndoRestore.ts", "hfUndo");
+  softReloadBundle = await bundle("./gsapSoftReload.ts", "hfSoftReload");
 });
 
 afterAll(() => browser?.close());
 
+type Spec = { gsap: string; placement: string; rotation: number; time: number };
+
+/** The bench's root crop fixture, shown at `spec.time` with the module under test loaded. */
+async function openCase(spec: Spec, moduleBundle: string) {
+  const dir = join(mkdtempSync(join(tmpdir(), "undo-gsap-")), "case");
+  writeFixture({ gesture: "crop", nesting: "root", zoom: 100, ...spec }, dir);
+  const restored = readFileSync(join(dir, "index.html"), "utf8");
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1920, height: 1080 });
+  await page.setRequestInterception(true);
+  // Only the fixture's GSAP CDN script is served; anything else is refused, never fetched.
+  page.on("request", (request) =>
+    request.url().endsWith("/gsap.min.js")
+      ? request.respond({ body: readFileSync(require.resolve("gsap/dist/gsap.min.js"), "utf8") })
+      : request.abort("blockedbyclient"),
+  );
+  await page.setContent(restored, { waitUntil: "load" });
+  await page.evaluate(readFileSync(require.resolve("@hyperframes/core/runtime"), "utf8"));
+  await page.waitForFunction(() => "__player" in window);
+  await page.evaluate(moduleBundle);
+  await page.evaluate(
+    (time) => (window as unknown as { __player: { seek(t: number): void } }).__player.seek(time),
+    spec.time,
+  );
+  const box = () =>
+    page.evaluate(() => {
+      const { left, top, width, height } = document
+        .getElementById("target")!
+        .getBoundingClientRect();
+      return [left, top, width, height].map((n) => Math.round(n * 100) / 100);
+    });
+  return { page, restored, box };
+}
+
 // The first case opens the cold browser's first page, which overran 5 s on a loaded CI runner.
 it.each([
-  { gsap: "hold", placement: "px", rotation: 0 },
-  { gsap: "tween", placement: "px", rotation: 0 },
-  { gsap: "tween", placement: "xpercent", rotation: 30 },
+  { gsap: "hold", placement: "px", rotation: 0, time: 1 },
+  { gsap: "tween", placement: "px", rotation: 0, time: 1 },
+  { gsap: "tween", placement: "xpercent", rotation: 30, time: 1 },
+  { gsap: "keys", placement: "px", rotation: 0, time: 1 },
+  { gsap: "keys", placement: "px", rotation: 30, time: 2 },
+  { gsap: "scale", placement: "px", rotation: 0, time: 1 },
+  { gsap: "spin", placement: "px", rotation: 30, time: 1 },
+  { gsap: "fromto", placement: "px", rotation: 0, time: 1 },
 ])(
-  "an undone crop leaves a $gsap $placement r$rotation layer where it was",
+  "an undone crop leaves a $gsap $placement r$rotation layer at t$time where it was",
   async (spec) => {
-    const dir = join(mkdtempSync(join(tmpdir(), "undo-gsap-")), "case");
-    writeFixture({ gesture: "crop", nesting: "root", zoom: 100, ...spec }, dir);
-    const restored = readFileSync(join(dir, "index.html"), "utf8");
+    const { page, restored, box } = await openCase(spec, undoBundle);
     const previous = restored.replace(
       `<div id="target"`,
       `<div id="target" style="clip-path: ${CROP}"`,
     );
-    const page = await browser.newPage();
-    await page.setViewport({ width: 1920, height: 1080 });
-    await page.setRequestInterception(true);
-    // Only the fixture's GSAP CDN script is served; anything else is refused, never fetched.
-    page.on("request", (request) =>
-      request.url().endsWith("/gsap.min.js")
-        ? request.respond({ body: readFileSync(require.resolve("gsap/dist/gsap.min.js"), "utf8") })
-        : request.abort("blockedbyclient"),
-    );
-    await page.setContent(restored, { waitUntil: "load" });
-    await page.evaluate(readFileSync(require.resolve("@hyperframes/core/runtime"), "utf8"));
-    await page.waitForFunction(() => "__player" in window);
-    await page.evaluate(undoBundle);
-
-    const box = () =>
-      page.evaluate(() => {
-        const { left, top, width, height } = document
-          .getElementById("target")!
-          .getBoundingClientRect();
-        return [left, top, width, height].map((n) => Math.round(n * 100) / 100);
-      });
-    await page.evaluate(() =>
-      (window as unknown as { __player: { seek(t: number): void } }).__player.seek(1),
-    );
     const before = await box();
     const outcome = await page.evaluate(
-      (files, crop) => {
+      (files, crop, time) => {
         document.getElementById("target")!.style.setProperty("clip-path", crop);
         const undo = (window as unknown as { hfUndo: typeof import("./gsapUndoRestore") }).hfUndo;
         const iframe = { contentDocument: document, contentWindow: window } as HTMLIFrameElement;
-        return undo.applyUndoRestoreToPreview(iframe, "index.html", files, 1, () => {});
+        return undo.applyUndoRestoreToPreview(iframe, "index.html", files, time, () => {});
       },
       { "index.html": { previous, restored } },
       CROP,
+      spec.time,
     );
 
     expect(outcome).toBe("soft");
@@ -100,3 +115,35 @@ it.each([
   },
   30_000,
 );
+
+// A drop saves the file and soft-reloads it; the re-run must place an animated layer where it was.
+it.each([
+  { gsap: "tween", placement: "px", rotation: 0, time: 1 },
+  { gsap: "keys", placement: "px", rotation: 30, time: 2 },
+  { gsap: "spin", placement: "px", rotation: 0, time: 1 },
+])(
+  "a soft reload keeps a $gsap $placement r$rotation layer at t$time where it was",
+  async (spec) => {
+    const { page, restored, box } = await openCase(spec, softReloadBundle);
+    const before = await box();
+    const outcome = await page.evaluate(
+      (html, time) => {
+        const soft = (window as unknown as { hfSoftReload: typeof import("./gsapSoftReload") })
+          .hfSoftReload;
+        const iframe = { contentDocument: document, contentWindow: window } as HTMLIFrameElement;
+        const script = soft.extractGsapScriptText(html)!;
+        return soft.applySoftReload(iframe, script, {
+          currentTimeOverride: time,
+          authoredHtml: html,
+        });
+      },
+      restored,
+      spec.time,
+    );
+
+    expect(outcome).toBe("applied");
+    expect(await box()).toEqual(before);
+    await page.close();
+  },
+  30_000,
+);

package/src/utils/softReloadTargets.ts

@@ -1,8 +1,9 @@
 // Which elements a GSAP soft reload resets, what their tweens wrote, and which file writes each.
 import { parseSavedSource } from "./authoredSource";
+import { elementTargets } from "./elementGsap";
 
 type TweenLike = {
-  targets?: () => Element[];
+  targets?: () => unknown[];
   vars?: Record<string, unknown>;
   getChildren?: (deep: boolean) => TweenLike[];
 };
@@ -36,7 +37,7 @@ export function authoringFile(el: Element): string | null {
 
 function addTweenTargets(tween: TweenLike, targets: Map<Element, Set<string>>): void {
   const props = tweenedProps(tween.vars);
-  for (const el of tween.targets?.() ?? []) {
+  for (const el of elementTargets(tween)) {
     const seen = targets.get(el) ?? new Set<string>();
     for (const prop of props) seen.add(prop);
     targets.set(el, seen);
@@ -68,7 +69,7 @@ function tweenTargetsIn(timelines: Set<unknown>): Set<Element> {
   for (const tl of timelines) {
     try {
       for (const tween of (tl as TweenLike | undefined)?.getChildren?.(true) ?? []) {
-        for (const el of tween.targets?.() ?? []) els.add(el);
+        for (const el of elementTargets(tween)) els.add(el);
       }
     } catch {}
   }

package/src/utils/studioFileHistory.ts

@@ -9,6 +9,7 @@ export interface RecordEditInput {
   coalesceKey?: string;
   coalesceMs?: number;
   files: Record<string, { before: string; after: string }>;
+  created?: string[];
 }
 
 export interface DomEditCommitBaseParams {

package/src/utils/timelineInspector.ts

@@ -34,6 +34,13 @@ export function isAudioTimelineElement(
   return Boolean(element.src && AUDIO_SOURCE_EXT_RE.test(element.src));
 }
 
+/** A track whose hide toggle reads as mute: the header button and its undo entry. */
+export function isAudioOnlyTrack(
+  elements: readonly Pick<TimelineElement, "tag" | "src">[],
+): boolean {
+  return elements.length > 0 && elements.every(isAudioTimelineElement);
+}
+
 /** The two tags the property panel lets you put a volume automation lane on.
  * Single owner: `groupAutomationLanes`, `automationLaneCountOf` and
  * `TimelineAutomationLaneSlot`'s clip filter all have to agree on this set. */
@@ -108,11 +115,9 @@ export function resolveBeatSourceTrack(
  * May this multi-selection be hidden as one action?
  *
  * Audio has no visual to hide, and `data-hidden` on an audio element is what
- * MUTES it — preview silences it and the render drops it from the mix. The
- * timeline withholds the eye on an audio track for that reason
- * (`visible={!isAudioTrack}`), and the single-selection panel gates the same
- * write on `audioSelection`. The multi-selection "Hide all" was the one path
- * left back to it, on a control whose label promises visibility.
+ * mutes it: preview silences it and the render drops it from the mix. The timeline
+ * and the single-selection panel offer it as a mute; "Hide all" would reach it on a
+ * control whose label promises visibility.
  *
  * A shared predicate rather than a check in the handler so the panel's button
  * and the handler's refusal cannot disagree — the button is not the only caller.