@hyperframes/studio 0.8.117 → 0.8.118

package/src/player/components/Timeline.test.ts

@@ -499,6 +499,54 @@ describe("Timeline provider boundary", () => {
     act(() => root.unmount());
   });
 
+  // An agent writes music alternatives muted; the author unmutes one and must be
+  // able to mute it again from the same row.
+  it("mutes, unmutes and mutes an audio track again from its header", () => {
+    const host = createSizedTimelineHost(640);
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      elements: [{ id: "music-b", tag: "audio", start: 0, duration: 4, track: 0, hidden: true }],
+    });
+    const onToggleTrackHidden = vi.fn((track: number, hidden: boolean) => {
+      usePlayerStore.setState({
+        elements: usePlayerStore
+          .getState()
+          .elements.map((el) => (el.track === track ? { ...el, hidden } : el)),
+      });
+    });
+    const root = createRoot(host);
+    act(() => {
+      root.render(
+        React.createElement(
+          TimelineEditProvider,
+          { value: { onToggleTrackHidden } },
+          React.createElement(Timeline),
+        ),
+      );
+    });
+    act(() => {});
+
+    const press = (label: string) => {
+      const button = host.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`);
+      if (!button) throw new Error(`Expected a "${label}" button`);
+      act(() => button.click());
+    };
+    press("Unmute track 1");
+    press("Mute track 1");
+    press("Unmute track 1");
+    press("Mute track 1");
+
+    expect(onToggleTrackHidden.mock.calls.map((call) => call[1])).toEqual([
+      false,
+      true,
+      false,
+      true,
+    ]);
+    expect(usePlayerStore.getState().elements[0]?.hidden).toBe(true);
+    act(() => root.unmount());
+  });
+
   it("splits all tracks once when shift-clicking the timeline with the razor", () => {
     const host = createSizedTimelineHost(640);
     usePlayerStore.setState({

package/src/player/components/TimelineTrackHeader.test.tsx

@@ -256,43 +256,35 @@ describe("TimelineTrackHeader", () => {
     act(() => view.root.unmount());
   });
 
-  // The visibility control is the old hide eye. On an audio track it silences
-  // rather than hides, and the row already says so with a speaker elsewhere —
-  // so the eye's slot stays empty there. A non-audio track is untouched.
-  it("keeps the visibility control off audio track headers", () => {
+  // `data-hidden` silences an audio track, so its toggle is a mute, offered in
+  // both states: an agent writes alternatives muted and the author flips them.
+  it.each([
+    [false, "Mute track 1"],
+    [true, "Unmute track 1"],
+  ])("offers the audio track toggle when hidden=%s", (isTrackHidden, label) => {
     const audio: TimelineElement = { ...ELEMENT, tag: "audio" };
     const view = renderHeader({
       keyframeClip: audio,
       trackElements: [audio],
       isAudioTrack: true,
+      isTrackHidden,
       animations: [],
     });
-    const labels = Array.from(view.host.querySelectorAll("button")).map((b) =>
-      b.getAttribute("aria-label"),
-    );
-    expect(labels.some((l) => l && /^(Hide|Show) track/.test(l))).toBe(false);
-    expect(labels).not.toContain("Mute");
+    expect(view.host.querySelector(`button[aria-label="${label}"]`)).not.toBeNull();
     act(() => view.root.unmount());
   });
 
-  // The escape hatch. `data-hidden` on audio silences it in preview and drops it
-  // from the render; the panel's "Muted" is the unrelated HTML `muted`
-  // attribute, and nothing else writes it. Withholding the eye unconditionally
-  // meant a track hidden by "Hide all" (or by hand, or before that rule existed)
-  // was silent with no control anywhere to bring it back.
-  it("offers the eye on an audio track that is already hidden, so it can be restored", () => {
-    const audio: TimelineElement = { ...ELEMENT, tag: "audio" };
+  // Same rule as the undo entry: a track with any visual clip hides, it does not mute.
+  it("offers the eye on a track mixing audio and a visual clip", () => {
+    const audio: TimelineElement = { ...ELEMENT, id: "vo", tag: "audio" };
     const view = renderHeader({
       keyframeClip: audio,
-      trackElements: [audio],
+      trackElements: [audio, ELEMENT],
+      clipCount: 2,
       isAudioTrack: true,
-      isTrackHidden: true,
       animations: [],
     });
-    const labels = Array.from(view.host.querySelectorAll("button")).map((b) =>
-      b.getAttribute("aria-label"),
-    );
-    expect(labels.some((l) => l && /^Show track/.test(l))).toBe(true);
+    expect(view.host.querySelector('button[aria-label="Hide track 1"]')).not.toBeNull();
     act(() => view.root.unmount());
   });
 

package/src/player/components/TimelineTrackHeader.tsx

@@ -12,6 +12,7 @@ import { useTimelineEditContextOptional } from "../../contexts/TimelineEditConte
 import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
 import { mintGroupId } from "../../components/editor/useFxCarveGrouping";
 import { runtimeAudioId } from "../lib/timelineElementHelpers";
+import { isAudioOnlyTrack } from "../../utils/timelineInspector";
 import { TimelineFxButton } from "./TimelineFxButton";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { elementFxChain, groupAutomationLanes, isCarveLane } from "./automationLaneData";
@@ -203,6 +204,7 @@ export function TimelineTrackHeader({
   // disclosability swapped it for the keyframe-layer row (a `◇`, no indent) the
   // moment an envelope appeared.
   const isKeyframeLayer = !!keyframeClip && disclosable && !isAudioTrack;
+  const isAudioOnly = isAudioOnlyTrack(trackElements);
   // What the lane disclosure calls this row. A row of several clips is named
   // for the TRACK, not for whichever is selected — the lanes are the track's,
   // shared per property, so "Narration 2 lanes" read as if they were that one
@@ -312,6 +314,7 @@ export function TimelineTrackHeader({
               showTrackLabel={showTrackLabel}
               isTrackHidden={isTrackHidden}
               isAudioTrack={isAudioTrack}
+              isAudioOnly={isAudioOnly}
               onToggleTrackHidden={onToggleTrackHidden}
               // On the control line rather than a third row of its own.
               trailing={
@@ -383,8 +386,7 @@ export function TimelineTrackHeader({
               hidden={isTrackHidden}
               trackNumber={trackNumber}
               trackDisplayNumber={trackDisplayNumber}
-              // Audio: only while hidden — see the plain header.
-              visible={!isAudioTrack || isTrackHidden}
+              asMute={isAudioOnly}
               onToggle={onToggleTrackHidden}
             />
           </LayerDisclosureRow>

package/src/player/components/TimelineTrackPlainHeader.test.tsx

@@ -1,17 +1,8 @@
 // @vitest-environment happy-dom
 
 /**
- * The visibility control's accessible contract.
- *
- * The wording ran behind the `audio-track-mute` canary at 0%, so it had never
- * rendered in any suite: it returned "Muted" / "Mute", which named the CURRENT
- * state rather than the action, and dropped the track suffix so every audio row
- * shared one accessible name. Pinned here because the label, the icon and the
- * callback's arguments are the whole identity of this control.
- *
- * The mute presentation itself is gone (`remove mute and solo from tracks and
- * groups`): the control is the visibility eye it always was, and an audio row
- * renders it only when already hidden, which is the way back out.
+ * The track toggle's accessible contract: the label names the action, carries
+ * the display row, and reads mute on an audio-only track.
  */
 
 import React, { act } from "react";
@@ -27,7 +18,7 @@ afterEach(() => {
 
 function renderButton(props: {
   hidden: boolean;
-  visible?: boolean;
+  asMute?: boolean;
   trackDisplayNumber: number | null;
 }): { host: HTMLElement; unmount: () => void; onToggle: ReturnType<typeof vi.fn> } {
   const host = document.createElement("div");
@@ -40,7 +31,7 @@ function renderButton(props: {
         hidden: props.hidden,
         trackNumber: 7,
         trackDisplayNumber: props.trackDisplayNumber,
-        visible: props.visible ?? true,
+        asMute: props.asMute ?? false,
         onToggle,
       }),
     ),
@@ -80,13 +71,13 @@ describe("VisibilityButton", () => {
     view.unmount();
   });
 
-  // `visible={false}` renders a SPACER, not nothing: every row's control
-  // columns have to line up whether or not this row offers the control.
-  it("holds the column with a spacer when withheld", () => {
-    const view = renderButton({ hidden: false, visible: false, trackDisplayNumber: 2 });
-    expect(view.host.querySelector("button")).toBeNull();
-    expect(view.host.querySelector("span")).toBeTruthy();
-    view.unmount();
+  it("names a mute on an audio-only track", () => {
+    const audible = renderButton({ hidden: false, asMute: true, trackDisplayNumber: 2 });
+    expect(labelOf(audible.host)).toBe("Mute track 2");
+    audible.unmount();
+    const muted = renderButton({ hidden: true, asMute: true, trackDisplayNumber: 2 });
+    expect(labelOf(muted.host)).toBe("Unmute track 2");
+    muted.unmount();
   });
 });
 
@@ -104,6 +95,7 @@ describe("PlainTrackHeader", () => {
           clipCount: 1,
           isTrackHidden: false,
           isAudioTrack: true,
+          isAudioOnly: true,
           onToggleTrackHidden: vi.fn(),
           showTrackLabel: true,
           ...overrides,
@@ -113,26 +105,20 @@ describe("PlainTrackHeader", () => {
     return { host, unmount: () => act(() => root.unmount()) };
   }
 
-  // A row that says what it is with a speaker does not also need the hide
-  // affordance sitting in the eye's slot.
-  it("withholds the eye from an audible audio track", () => {
+  it("offers a mute on an audible audio track", () => {
     const view = renderHeader();
-    expect(view.host.querySelector("button")).toBeNull();
+    expect(labelOf(view.host)).toBe("Mute track 1");
     view.unmount();
   });
 
-  // Withholding it unconditionally withheld the only way back: `data-hidden`
-  // silences the clip in preview and drops it from the render, and nothing else
-  // writes it, so a track hidden by hand or by "Hide all" was silent with no
-  // control anywhere to restore it.
-  it("offers it back once the audio track is hidden", () => {
+  it("offers the unmute on a muted audio track", () => {
     const view = renderHeader({ isTrackHidden: true });
-    expect(labelOf(view.host)).toBe("Show track 1");
+    expect(labelOf(view.host)).toBe("Unmute track 1");
     view.unmount();
   });
 
   it("keeps the eye on a visual track", () => {
-    const view = renderHeader({ isAudioTrack: false });
+    const view = renderHeader({ isAudioTrack: false, isAudioOnly: false });
     expect(labelOf(view.host)).toBe("Hide track 1");
     view.unmount();
   });

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);

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 {
@@ -445,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/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.