@hyperframes/studio 0.8.5 → 0.8.7

package/src/player/components/TimelineTrackHeader.tsx

@@ -1,14 +1,22 @@
-import { Eye, EyeSlash } from "@phosphor-icons/react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { Music } from "../../icons/SystemIcons";
-import type { TimelineElement } from "../store/playerStore";
+import {
+  HF_AUDIO_FX_ATTR,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import { classifyAudioName } from "@hyperframes/core/audio-carve";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { VisibilityButton, PlainTrackHeader } from "./TimelineTrackPlainHeader";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
+import { mintGroupId } from "../../components/editor/useFxCarveGrouping";
+import { TimelineFxButton } from "./TimelineFxButton";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { groupAutomationLanes } from "./automationLaneData";
 import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import { clipTimingStart } from "../../hooks/gsapShared";
 import { LayerDisclosureRow } from "./LayerDisclosureRow";
-import { TrackClipCount } from "./TrackClipCount";
 import { LABEL_COL_W, LANE_H, getTimelineLaneTop } from "./timelineLayout";
 import type { TimelineTheme } from "./timelineTheme";
 import {
@@ -61,90 +69,6 @@ interface TimelineTrackHeaderProps {
   onSeek?: (time: number) => void;
 }
 
-function VisibilityButton({
-  hidden,
-  trackNumber,
-  trackDisplayNumber,
-  visible,
-  onToggle,
-}: {
-  hidden: boolean;
-  trackNumber: number;
-  trackDisplayNumber: number | null;
-  visible: 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 = hidden ? `Show track${suffix}` : `Hide track${suffix}`;
-  return (
-    <button
-      type="button"
-      aria-label={label}
-      title={label}
-      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
-        hidden ? "text-[#3CE6AC] hover:text-white" : "text-white/35 hover:text-white/75"
-      }`}
-      onPointerDown={(event) => event.stopPropagation()}
-      onClick={(event) => {
-        event.stopPropagation();
-        void onToggle?.(trackNumber, !hidden);
-      }}
-    >
-      {hidden ? (
-        <EyeSlash size={14} weight="bold" aria-hidden="true" />
-      ) : (
-        <Eye size={14} weight="bold" aria-hidden="true" />
-      )}
-    </button>
-  );
-}
-
-// The header a track gets when it has no keyframe clip to disclose: label, clip
-// count, eye. Not deprecated — it is the live path for every track without lanes.
-function PlainTrackHeader({
-  trackNumber,
-  trackDisplayNumber,
-  trackLabel,
-  clipCount,
-  showTrackLabel,
-  isTrackHidden,
-  isAudioTrack,
-  onToggleTrackHidden,
-}: Pick<
-  TimelineTrackHeaderProps,
-  | "trackNumber"
-  | "trackDisplayNumber"
-  | "trackLabel"
-  | "clipCount"
-  | "isTrackHidden"
-  | "isAudioTrack"
-  | "onToggleTrackHidden"
-> & { showTrackLabel: boolean }) {
-  return (
-    <>
-      {isAudioTrack && (
-        <Music size={12} weight="fill" aria-hidden="true" className="text-white/35" />
-      )}
-      {showTrackLabel && (
-        <span className="min-w-0 flex-1 truncate text-[11px]" title={trackLabel}>
-          {trackLabel}
-        </span>
-      )}
-      {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
-      <VisibilityButton
-        hidden={isTrackHidden}
-        trackNumber={trackNumber}
-        trackDisplayNumber={trackDisplayNumber}
-        visible
-        onToggle={onToggleTrackHidden}
-      />
-    </>
-  );
-}
-
 // Figma layout: prev-keyframe ‹, the add/remove toggle (children), next ›.
 function PropertyGroupNavigation({
   navigation,
@@ -406,6 +330,7 @@ function AutomationLaneHeaderRow({
   );
 }
 
+// fallow-ignore-next-line complexity
 export function TimelineTrackHeader({
   trackNumber,
   trackDisplayNumber,
@@ -457,6 +382,38 @@ export function TimelineTrackHeader({
   // left an audio clip's envelopes unreachable, since the track could not expand.
   const disclosable = lanes.length > 0 || automationRows.length > 0;
   const isKeyframeLayer = !!keyframeClip && disclosable;
+  // Solo is per-clip/per-group, never per track (design doc §2.2) — this header
+  // acts on the track's first clip as a pragmatic stand-in for "this track",
+  // the same simplification the mute button doesn't need to make (it patches
+  // every clip on the track at once).
+  const soloTargetId = trackElements[0] ? (trackElements[0].key ?? trackElements[0].id) : null;
+  const soloed = usePlayerStore((s) => s.soloed);
+  const toggleSolo = usePlayerStore((s) => s.toggleSolo);
+
+  // C1: the FX entry point. A single audio clip has one chain to point at; a
+  // track holding several ungrouped ones has no single chain — the design
+  // doc refuses to build "N clips = N chains", so that case gets a pointer
+  // at grouping (B6's normative rule) instead of a popover.
+  const { onGroupClips, onSetElementAttributeLive, onSetElementAttributeQuiet } =
+    useTimelineEditContextOptional();
+  const domEditActions = useDomEditActionsContextOptional();
+  const singleAudioClip =
+    isAudioTrack && clipCount === 1 && trackElements.length > 0 ? trackElements[0] : null;
+  const isTrackGrouped = trackElements.some((el) => el.audioGroup);
+  const writeClipFxChain = (clip: TimelineElement, next: HfAudioFxChain, live: boolean) => {
+    const value = next.nodes.length ? serializeAudioFxChain(next) : null;
+    if (live) onSetElementAttributeLive?.(clip, HF_AUDIO_FX_ATTR, value);
+    else void onSetElementAttributeQuiet?.(clip, HF_AUDIO_FX_ATTR, value, "Apply preset");
+  };
+  const openClipFxRack = (clip: TimelineElement) => {
+    void domEditActions?.handleTimelineElementSelect(clip);
+  };
+  const groupUngroupedClips = () => {
+    const doc = domEditActions?.previewIframeRef.current?.contentDocument;
+    if (!doc || !onGroupClips) return;
+    const clipIds = trackElements.map((el) => el.key ?? el.id);
+    void onGroupClips(clipIds, mintGroupId(doc));
+  };
 
   return (
     <div
@@ -476,16 +433,34 @@ export function TimelineTrackHeader({
       }}
     >
       {!keyframeClip || !disclosable ? (
-        <PlainTrackHeader
-          trackNumber={trackNumber}
-          trackDisplayNumber={trackDisplayNumber}
-          trackLabel={trackLabel}
-          clipCount={clipCount}
-          showTrackLabel={showTrackLabel}
-          isTrackHidden={isTrackHidden}
-          isAudioTrack={isAudioTrack}
-          onToggleTrackHidden={onToggleTrackHidden}
-        />
+        <>
+          <PlainTrackHeader
+            trackNumber={trackNumber}
+            trackDisplayNumber={trackDisplayNumber}
+            trackLabel={trackLabel}
+            clipCount={clipCount}
+            showTrackLabel={showTrackLabel}
+            isTrackHidden={isTrackHidden}
+            isAudioTrack={isAudioTrack}
+            isGroupMuted={trackElements.some((el) => el.audioGroupHidden)}
+            isSoloed={soloTargetId !== null && soloed.has(soloTargetId)}
+            onToggleSolo={soloTargetId ? (options) => toggleSolo(soloTargetId, options) : undefined}
+            onToggleTrackHidden={onToggleTrackHidden}
+          />
+          {singleAudioClip && (
+            <TimelineFxButton
+              variant="chain"
+              fxChainRaw={singleAudioClip.fxChain}
+              trackKind={classifyAudioName(singleAudioClip.id, singleAudioClip.src)}
+              onChainChange={(next) => writeClipFxChain(singleAudioClip, next, false)}
+              onChainPreview={(next) => writeClipFxChain(singleAudioClip, next, true)}
+              onOpenRack={() => openClipFxRack(singleAudioClip)}
+            />
+          )}
+          {isAudioTrack && clipCount > 1 && !isTrackGrouped && (
+            <TimelineFxButton variant="group-pointer" onGroupClips={groupUngroupedClips} />
+          )}
+        </>
       ) : (
         <>
           <LayerDisclosureRow
@@ -515,6 +490,7 @@ export function TimelineTrackHeader({
               trackNumber={trackNumber}
               trackDisplayNumber={trackDisplayNumber}
               visible
+              isAudioTrack={isAudioTrack}
               onToggle={onToggleTrackHidden}
             />
           </LayerDisclosureRow>

package/src/player/components/TimelineTrackPlainHeader.tsx

@@ -0,0 +1,119 @@
+import { Eye, EyeSlash, SpeakerHigh, SpeakerSlash } from "@phosphor-icons/react";
+import { isCanaryEnabled } from "../../telemetry/canary";
+import { Music } from "../../icons/SystemIcons";
+import { TimelineSoloButton } from "./TimelineSoloButton";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { TrackClipCount } from "./TrackClipCount";
+import { trackDisplaySuffix } from "./timelineTrackDisplay";
+
+// Audio tracks say "Mute", not "Hide" — the eye IS mute for sound-only rows.
+// Gated: the relabel ships behind the canary, unlike the preview fix.
+function visibilityButtonLabel(showAsMute: boolean, hidden: boolean, suffix: string): string {
+  if (showAsMute) return hidden ? "Muted" : "Mute";
+  return hidden ? `Show track${suffix}` : `Hide track${suffix}`;
+}
+
+function visibilityButtonIcon(showAsMute: boolean, hidden: boolean) {
+  const Icon = showAsMute ? (hidden ? SpeakerSlash : SpeakerHigh) : hidden ? EyeSlash : Eye;
+  return <Icon size={14} weight="bold" aria-hidden="true" />;
+}
+
+export function VisibilityButton({
+  hidden,
+  trackNumber,
+  trackDisplayNumber,
+  visible,
+  isAudioTrack,
+  onToggle,
+}: {
+  hidden: boolean;
+  trackNumber: number;
+  trackDisplayNumber: number | null;
+  visible: boolean;
+  isAudioTrack?: 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 showAsMute = Boolean(isAudioTrack) && isCanaryEnabled("audio-track-mute");
+  const label = visibilityButtonLabel(showAsMute, hidden, suffix);
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-[-1px] focus-visible:outline-[#3CE6AC] ${
+        hidden ? "text-[#3CE6AC] hover:text-white" : "text-white/35 hover:text-white/75"
+      }`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onClick={(event) => {
+        event.stopPropagation();
+        void onToggle?.(trackNumber, !hidden);
+      }}
+    >
+      {visibilityButtonIcon(showAsMute, hidden)}
+    </button>
+  );
+}
+
+// The header a track gets when it has no keyframe clip to disclose: label, clip
+// count, eye. Not deprecated — it is the live path for every track without lanes.
+export function PlainTrackHeader({
+  trackNumber,
+  trackDisplayNumber,
+  trackLabel,
+  clipCount,
+  showTrackLabel,
+  isTrackHidden,
+  isAudioTrack,
+  isGroupMuted,
+  isSoloed,
+  onToggleSolo,
+  onToggleTrackHidden,
+}: {
+  trackNumber: number;
+  trackDisplayNumber: number | null;
+  trackLabel: string;
+  clipCount: number;
+  isTrackHidden: boolean;
+  isAudioTrack: boolean;
+  onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+  showTrackLabel: boolean;
+  isGroupMuted: boolean;
+  isSoloed: boolean;
+  onToggleSolo?: (options?: { add?: boolean }) => void;
+}) {
+  return (
+    <>
+      {isAudioTrack && (
+        <Music size={12} weight="fill" aria-hidden="true" className="text-white/35" />
+      )}
+      {showTrackLabel && (
+        <span
+          className={`min-w-0 flex-1 truncate text-[11px] ${
+            isAudioTrack && (isTrackHidden || isGroupMuted) && isCanaryEnabled("audio-track-mute")
+              ? "line-through"
+              : ""
+          }`}
+          title={isGroupMuted && !isTrackHidden ? `${trackLabel} (group muted)` : trackLabel}
+        >
+          {trackLabel}
+        </span>
+      )}
+      {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
+      <VisibilityButton
+        hidden={isTrackHidden}
+        trackNumber={trackNumber}
+        trackDisplayNumber={trackDisplayNumber}
+        visible
+        isAudioTrack={isAudioTrack}
+        onToggle={onToggleTrackHidden}
+      />
+      {isAudioTrack && isCanaryEnabled("audio-track-mute") && onToggleSolo && (
+        <TimelineSoloButton isSoloed={isSoloed} onToggle={onToggleSolo} />
+      )}
+    </>
+  );
+}

package/src/player/components/VideoThumbnail.tsx

@@ -110,13 +110,18 @@ export const VideoThumbnail = memo(function VideoThumbnail({
       )}
       {snapshot.status === "loading" && urls.length === 0 && (
         <div
-          className="absolute inset-0 animate-pulse"
+          className="absolute inset-0 animate-pulse motion-reduce:animate-none"
           style={{
             background:
               "linear-gradient(90deg, rgba(255,255,255,0.02) 0%, rgba(255,255,255,0.05) 50%, rgba(255,255,255,0.02) 100%)",
           }}
         />
       )}
+      {snapshot.status === "error" && (
+        <div className="absolute inset-0 flex items-center justify-center bg-neutral-900/60">
+          <span className="rounded bg-black/50 px-1 text-[8px] text-neutral-500">no preview</span>
+        </div>
+      )}
       {label && (
         <div
           className="absolute inset-x-0 bottom-0 z-10 px-1.5 pb-0.5 pt-3"

package/src/player/components/menuKeyboardNav.ts

@@ -0,0 +1,47 @@
+import { useEffect, type RefObject } from "react";
+
+/**
+ * APG menu keyboard basics for the timeline context menus: focuses the first
+ * menu item on open, moves focus with ArrowUp/ArrowDown/Home/End, and restores
+ * focus to the previously focused element when the menu unmounts. Pair with
+ * `role="menu"` on the container and `role="menuitem"` on the buttons
+ * (dismiss/Escape handling stays in useContextMenuDismiss).
+ */
+export function useMenuKeyboardNav(menuRef: RefObject<HTMLDivElement | null>): void {
+  useEffect(() => {
+    const menu = menuRef.current;
+    if (!menu) return;
+    const previouslyFocused = document.activeElement;
+
+    const items = () =>
+      Array.from(menu.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')).filter(
+        (el) => !el.disabled,
+      );
+    items()[0]?.focus();
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "ArrowDown" && e.key !== "ArrowUp" && e.key !== "Home" && e.key !== "End") {
+        return;
+      }
+      const list = items();
+      if (list.length === 0) return;
+      e.preventDefault();
+      const idx = list.findIndex((el) => el === document.activeElement);
+      let next: number;
+      if (e.key === "ArrowDown") next = idx < 0 ? 0 : (idx + 1) % list.length;
+      else if (e.key === "ArrowUp")
+        next = idx < 0 ? list.length - 1 : (idx - 1 + list.length) % list.length;
+      else if (e.key === "Home") next = 0;
+      else next = list.length - 1;
+      list[next]?.focus();
+    };
+    menu.addEventListener("keydown", onKeyDown);
+
+    return () => {
+      menu.removeEventListener("keydown", onKeyDown);
+      if (previouslyFocused instanceof HTMLElement && document.contains(previouslyFocused)) {
+        previouslyFocused.focus();
+      }
+    };
+  }, [menuRef]);
+}

package/src/player/components/timelineCallbacks.ts

@@ -68,6 +68,32 @@ export interface TimelineEditCallbacks {
     options?: { coalesceKey?: string },
   ) => Promise<void> | void;
   onToggleTrackHidden?: (track: number, hidden: boolean) => Promise<void> | void;
+  /** B7's bus strip: live-write the group's own attribute while dragging. */
+  onSetAudioGroupAttributeLive?: (groupId: string, attr: string, value: string | null) => void;
+  /** ...and persist one undo entry on release. */
+  onSetAudioGroupAttributeQuiet?: (
+    groupId: string,
+    attr: string,
+    value: string | null,
+    label: string,
+  ) => Promise<void>;
+  /** C1's ungrouped-track FX pointer: "Group these clips" — write
+   *  `data-audio-group` on every one of them, atomically. Same shape B6's
+   *  carve auto-grouping uses. */
+  onGroupClips?: (clipIds: readonly string[], groupId: string) => Promise<void>;
+  /** C1's single-clip FX write: addressed by the clip itself rather than the
+   *  current selection, mirroring `onSetAudioGroupAttributeLive/Quiet`. */
+  onSetElementAttributeLive?: (
+    element: TimelineElement,
+    attr: string,
+    value: string | null,
+  ) => void;
+  onSetElementAttributeQuiet?: (
+    element: TimelineElement,
+    attr: string,
+    value: string | null,
+    label: string,
+  ) => Promise<void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;

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

@@ -58,6 +58,10 @@ function model(overrides: Partial<Parameters<typeof buildTimelineLogicalRows>[0]
     selectedElementId: "active",
     selectedElementIds: new Set(),
     expandedClipIds: new Set(["active"]),
+    expandedGroupIds: new Set(),
+    expandedLaneOwnerIds: new Set(),
+    groups: [],
+    trackGroupOf: new Map(),
     gsapAnimations: new Map([
       [
         "active",
@@ -244,6 +248,10 @@ describe("resolveTimelineNavigationTarget", () => {
       selectedElementId: null,
       selectedElementIds: new Set(),
       expandedClipIds: new Set(),
+      expandedGroupIds: new Set(),
+      expandedLaneOwnerIds: new Set(),
+      groups: [],
+      trackGroupOf: new Map(),
       gsapAnimations: new Map(),
     });