@hyperframes/studio 0.8.5 → 0.8.7

package/src/player/store/audioSoloSlice.test.ts

@@ -0,0 +1,113 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "./playerStore";
+import { isAudibleUnderSolo, isGroupHalfLitUnderSolo } from "./audioSoloSlice";
+import * as studioFileHistory from "../../utils/studioFileHistory";
+
+describe("audioSoloSlice", () => {
+  it("is exclusive by default, and clicking the only soloed element again clears it", () => {
+    usePlayerStore.getState().toggleSolo("a");
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["a"]));
+    usePlayerStore.getState().toggleSolo("b");
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["b"]));
+    usePlayerStore.getState().toggleSolo("b");
+    expect(usePlayerStore.getState().soloed).toEqual(new Set());
+  });
+
+  it("⌘/Ctrl-click adds and removes membership without disturbing the rest", () => {
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().toggleSolo("b", { add: true });
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["a", "b"]));
+    usePlayerStore.getState().toggleSolo("a", { add: true });
+    expect(usePlayerStore.getState().soloed).toEqual(new Set(["b"]));
+  });
+
+  it("clearSolo empties the set", () => {
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().clearSolo();
+    expect(usePlayerStore.getState().soloed).toEqual(new Set());
+  });
+});
+
+describe("export-safety: solo never touches an attribute or the save path", () => {
+  it("toggling, ⌘-adding, and clearing solo never calls setAttribute/removeAttribute on any element", () => {
+    usePlayerStore.getState().clearSolo();
+    const setAttributeSpy = vi.spyOn(Element.prototype, "setAttribute");
+    const removeAttributeSpy = vi.spyOn(Element.prototype, "removeAttribute");
+
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().toggleSolo("b", { add: true });
+    usePlayerStore.getState().toggleSolo("a", { add: true });
+    usePlayerStore.getState().clearSolo();
+
+    expect(setAttributeSpy).not.toHaveBeenCalled();
+    expect(removeAttributeSpy).not.toHaveBeenCalled();
+    setAttributeSpy.mockRestore();
+    removeAttributeSpy.mockRestore();
+  });
+
+  it("toggling, ⌘-adding, and clearing solo never invokes the project save path (setElementsHidden's own write function)", () => {
+    usePlayerStore.getState().clearSolo();
+    const saveSpy = vi.spyOn(studioFileHistory, "saveProjectFilesWithHistory");
+
+    usePlayerStore.getState().toggleSolo("a");
+    usePlayerStore.getState().toggleSolo("b", { add: true });
+    usePlayerStore.getState().clearSolo();
+
+    expect(saveSpy).not.toHaveBeenCalled();
+    saveSpy.mockRestore();
+  });
+});
+
+describe("isAudibleUnderSolo — the three-bullet rule", () => {
+  it("everything is audible when no solo is active", () => {
+    expect(isAudibleUnderSolo(new Set(), "clip-a")).toBe(true);
+    expect(isAudibleUnderSolo(new Set(), "clip-a", "group-1")).toBe(true);
+  });
+
+  it("a soloed element is audible", () => {
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-a")).toBe(true);
+  });
+
+  it("a sibling of a soloed element is silent", () => {
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-b")).toBe(false);
+  });
+
+  it("a member of a soloed group is audible (group solo = members solo)", () => {
+    expect(isAudibleUnderSolo(new Set(["group-1"]), "clip-a", "group-1")).toBe(true);
+  });
+
+  it("a member of an UNsoloed group, while a sibling group is soloed, is silent", () => {
+    expect(isAudibleUnderSolo(new Set(["group-2"]), "clip-a", "group-1")).toBe(false);
+  });
+
+  it("soloing one member of a group does not un-attenuate its siblings in the same group", () => {
+    // clip-a is soloed directly; clip-b shares its group but is not itself
+    // soloed and the group itself is not soloed — clip-b stays silent.
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "clip-b", "group-1")).toBe(false);
+  });
+
+  it("the group itself, monitored as a bus, is audible only when it or a member is soloed", () => {
+    expect(isAudibleUnderSolo(new Set(["clip-a"]), "group-1", null)).toBe(false);
+    expect(isAudibleUnderSolo(new Set(["group-1"]), "group-1", null)).toBe(true);
+  });
+});
+
+describe("isGroupHalfLitUnderSolo", () => {
+  it("is false when no solo is active", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(), "group-1", ["a", "b"])).toBe(false);
+  });
+
+  it("is false when the group itself is soloed (fully lit, not half)", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(["group-1"]), "group-1", ["a", "b"])).toBe(false);
+  });
+
+  it("is true when a member is soloed but the group is not", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(["a"]), "group-1", ["a", "b"])).toBe(true);
+  });
+
+  it("is false when an unrelated element is soloed", () => {
+    expect(isGroupHalfLitUnderSolo(new Set(["other"]), "group-1", ["a", "b"])).toBe(false);
+  });
+});

package/src/player/store/audioSoloSlice.ts

@@ -0,0 +1,43 @@
+/**
+ * "Hear only this" — session-only monitoring override, never persisted.
+ *
+ * Holds clip ids and group ids (never track numbers, per the design doc: solo
+ * is a per-element/per-group concept, not a row-position one). Exclusive by
+ * default (a plain toggle replaces the set); ⌘/Ctrl-click adds/removes one
+ * member without disturbing the rest. Never written to any attribute or
+ * document — the export-safety guarantee this slice exists to hold.
+ */
+import type { StoreApi } from "zustand";
+import { isAudibleUnderSolo, isGroupHalfLitUnderSolo } from "@hyperframes/core/audio-groups";
+
+export { isAudibleUnderSolo, isGroupHalfLitUnderSolo };
+
+export interface AudioSoloSlice {
+  soloed: ReadonlySet<string>;
+  toggleSolo: (id: string, options?: { add?: boolean }) => void;
+  clearSolo: () => void;
+}
+
+export function createAudioSoloSlice(
+  set: StoreApi<AudioSoloSlice>["setState"],
+  get: StoreApi<AudioSoloSlice>["getState"],
+): AudioSoloSlice {
+  return {
+    soloed: new Set(),
+    toggleSolo: (id, options) => {
+      const current = get().soloed;
+      if (options?.add) {
+        const next = new Set(current);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        set({ soloed: next });
+        return;
+      }
+      // Exclusive click: soloing the only-soloed element again clears it;
+      // otherwise it replaces the set.
+      const isOnlyMember = current.size === 1 && current.has(id);
+      set({ soloed: isOnlyMember ? new Set() : new Set([id]) });
+    },
+    clearSolo: () => set({ soloed: new Set() }),
+  };
+}

package/src/player/store/editingModeSlice.ts

@@ -0,0 +1,45 @@
+/**
+ * The two editing-mode toggles the timeline toolbar owns.
+ *
+ * A store slice rather than toolbar-local state because both are read far from
+ * where they are set: the motion-path arm is consumed by the canvas click
+ * handler and published by MotionPathOverlay, and the auto-keyframe flag
+ * decides what a drag/resize/rotate does inside the edit commit path.
+ *
+ * `motionPathArmed` is also cleared by playerStore on selection change — arming
+ * survives neither a new element nor a project switch, so those resets stay
+ * with the state they clear alongside.
+ */
+import type { StoreApi } from "zustand";
+
+export interface EditingModeSlice {
+  /** Motion-path "set destination" mode. Armed from the preview toolbar
+   *  (replaces the old double-click-on-canvas UX); while armed, one canvas
+   *  click places the new path's destination. */
+  motionPathArmed: boolean;
+  setMotionPathArmed: (armed: boolean) => void;
+  /** Published by MotionPathOverlay so the toolbar shows the button only when
+   *  the selected element can actually take a path. */
+  motionPathCreateAvailable: boolean;
+  setMotionPathCreateAvailable: (available: boolean) => void;
+  /** Global toggle for the "Add keyframe" diamond in the timeline toolbar
+   *  (#1808). When false, a manual drag/resize/rotate edit on an element that
+   *  already has a live tween shifts every keyframe by the edit's delta
+   *  (preserving the animation's shape) instead of inserting/updating a
+   *  keyframe at the playhead. */
+  autoKeyframeEnabled: boolean;
+  setAutoKeyframeEnabled: (enabled: boolean) => void;
+}
+
+export function createEditingModeSlice(
+  set: StoreApi<EditingModeSlice>["setState"],
+): EditingModeSlice {
+  return {
+    motionPathArmed: false,
+    setMotionPathArmed: (armed) => set({ motionPathArmed: armed }),
+    motionPathCreateAvailable: false,
+    setMotionPathCreateAvailable: (available) => set({ motionPathCreateAvailable: available }),
+    autoKeyframeEnabled: true,
+    setAutoKeyframeEnabled: (enabled) => set({ autoKeyframeEnabled: enabled }),
+  };
+}

package/src/player/store/groupLevels.ts

@@ -0,0 +1,33 @@
+// ponytail: mirrors liveTime.ts's plain pub-sub — same throttle-at-the-edge shape.
+/** A group's live meter reading, or absent when idle/unknown (never zero). */
+export type GroupLevelReading = { level: number; clipped: boolean };
+
+type Listener = (levels: ReadonlyMap<string, GroupLevelReading>) => void;
+const listeners = new Set<Listener>();
+let latest: ReadonlyMap<string, GroupLevelReading> = new Map();
+
+export const groupLevels = {
+  notify: (levels: ReadonlyMap<string, GroupLevelReading>) => {
+    latest = levels;
+    listeners.forEach((listener) => listener(levels));
+  },
+  subscribe: (listener: Listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  },
+  get: () => latest,
+};
+
+/** Turns the runtime's `group-levels` postMessage payload into the map `groupLevels.notify` wants. */
+export function parseGroupLevelsMessage(
+  data: unknown,
+): ReadonlyMap<string, GroupLevelReading> | null {
+  const levels = (data as { levels?: unknown } | null)?.levels;
+  if (!Array.isArray(levels)) return null;
+  return new Map(
+    (levels as Array<{ groupId: string; level: number; clipped: boolean }>).map((entry) => [
+      entry.groupId,
+      { level: entry.level, clipped: entry.clipped },
+    ]),
+  );
+}

package/src/player/store/keyframeSlice.ts

@@ -63,6 +63,14 @@ export interface KeyframeSlice {
   /** Union-expand clips (keyframed clips are expanded by default on load). */
   expandClips: (ids: readonly string[]) => void;
 
+  /** Groups whose member rows the caret has shown (structural, not lanes). */
+  expandedGroupIds: Set<string>;
+  toggleGroupExpanded: (id: string) => void;
+
+  /** Rows (clip id or group id) whose automation-lane rows the `∿` button opened. */
+  expandedLaneOwnerIds: Set<string>;
+  toggleLaneOwnerExpanded: (id: string) => void;
+
   /**
    * Project/session/element-scoped request. Its nonce is monotonic across store
    * resets so a stale consumer can never collide with a later request.
@@ -119,6 +127,24 @@ export function createKeyframeSlice(
         return { expandedClipIds: next };
       }),
 
+    expandedGroupIds: new Set(),
+    toggleGroupExpanded: (id) =>
+      set((state) => {
+        const next = new Set(state.expandedGroupIds);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        return { expandedGroupIds: next };
+      }),
+
+    expandedLaneOwnerIds: new Set(),
+    toggleLaneOwnerExpanded: (id) =>
+      set((state) => {
+        const next = new Set(state.expandedLaneOwnerIds);
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+        return { expandedLaneOwnerIds: next };
+      }),
+
     focusedEaseSegment: null,
     focusedEaseRequestNonce: 0,
     setFocusedEaseSegment: (target) =>

package/src/player/store/playerStore.ts

@@ -16,6 +16,8 @@ import {
 } from "./automationSelectionSlice";
 import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
+import { createAudioSoloSlice, type AudioSoloSlice } from "./audioSoloSlice";
+import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
@@ -47,7 +49,13 @@ function resolveElementSelection(
   };
 }
 
-interface PlayerState extends KeyframeSlice, AutomationSelectionSlice, ThumbnailSlice {
+interface PlayerState
+  extends
+    KeyframeSlice,
+    AutomationSelectionSlice,
+    ThumbnailSlice,
+    AudioSoloSlice,
+    EditingModeSlice {
   isPlaying: boolean;
   currentTime: number;
   duration: number;
@@ -87,20 +95,6 @@ interface PlayerState extends KeyframeSlice, AutomationSelectionSlice, Thumbnail
    *  (drag, resize, rotate) target this instead of recomputing from playhead. */
   activeKeyframePct: number | null;
   setActiveKeyframePct: (pct: number | null) => void;
-  /** Motion-path "set destination" mode. Armed from the preview toolbar (replaces
-   *  the old double-click-on-canvas UX); while armed, one canvas click places the
-   *  new path's destination. `available` is published by MotionPathOverlay so the
-   *  toolbar shows the button only when the selected element can take a path. */
-  motionPathArmed: boolean;
-  setMotionPathArmed: (armed: boolean) => void;
-  motionPathCreateAvailable: boolean;
-  setMotionPathCreateAvailable: (available: boolean) => void;
-  /** Global toggle for the "Add keyframe" diamond in the timeline toolbar (#1808).
-   *  When false, a manual drag/resize/rotate edit on an element that already has
-   *  a live tween shifts every keyframe by the edit's delta (preserving the
-   *  animation's shape) instead of inserting/updating a keyframe at the playhead. */
-  autoKeyframeEnabled: boolean;
-  setAutoKeyframeEnabled: (enabled: boolean) => void;
 
   /** Multi-select: additional selected elements beyond selectedElementId. */
   selectedElementIds: Set<string>;
@@ -146,7 +140,14 @@ interface PlayerState extends KeyframeSlice, AutomationSelectionSlice, Thumbnail
     updates: Partial<
       Pick<
         TimelineElement,
-        "start" | "duration" | "track" | "zIndex" | "hasExplicitZIndex" | "playbackStart" | "hidden"
+        | "start"
+        | "duration"
+        | "track"
+        | "zIndex"
+        | "hasExplicitZIndex"
+        | "playbackStart"
+        | "hidden"
+        | "audioGroup"
       >
     >,
   ) => void;
@@ -270,6 +271,8 @@ export function createTimelineResetState() {
     // paste through `sel.elementKey === paste.elementKey` to a stale t0.
     automationSelection: null,
     expandedClipIds: new Set<string>(),
+    expandedGroupIds: new Set<string>(),
+    expandedLaneOwnerIds: new Set<string>(),
     focusedEaseSegment: null,
     selectedElementIds: new Set<string>(),
     requestedSeekTime: null,
@@ -320,15 +323,11 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   ...createThumbnailSlice(set),
 
   ...createAutomationSelectionSlice(set),
+  ...createAudioSoloSlice(set, get),
+  ...createEditingModeSlice(set),
 
   activeKeyframePct: null,
   setActiveKeyframePct: (pct) => set({ activeKeyframePct: pct }),
-  motionPathArmed: false,
-  setMotionPathArmed: (armed) => set({ motionPathArmed: armed }),
-  motionPathCreateAvailable: false,
-  setMotionPathCreateAvailable: (available) => set({ motionPathCreateAvailable: available }),
-  autoKeyframeEnabled: true,
-  setAutoKeyframeEnabled: (enabled) => set({ autoKeyframeEnabled: enabled }),
 
   selectedElementIds: new Set<string>(),
   setSelection: (ids, anchor) => set(resolveElementSelection(ids, anchor)),

package/src/player/store/timelineElement.ts

@@ -67,6 +67,16 @@ export interface TimelineElement {
   hidden?: boolean;
   /** Value of data-timeline-role attribute — used to identify music vs. voiceover. */
   timelineRole?: string;
+  /** Verbatim `data-audio-group` — the id of the `<hf-audio-group>` this clip belongs to, when any. */
+  audioGroup?: string;
+  /** The owning group's `data-label` (falls back to its id) — resolved once per parse. */
+  audioGroupLabel?: string;
+  /** The owning group's `data-volume` (defaults to 1) — resolved once per parse. */
+  audioGroupVolume?: number;
+  /** The owning group's `data-hidden` (defaults to false) — resolved once per parse. */
+  audioGroupHidden?: boolean;
+  /** The owning group's serialized `data-fx-chain`, when set — resolved once per parse. */
+  audioGroupFxChain?: string;
   /**
    * Set by useExpandedTimelineElements on an inline-expanded sub-composition
    * child: the absolute master-timeline start of the sub-comp host the child

package/src/telemetry/events.ts

@@ -186,3 +186,15 @@ export function trackStudioFeedback(
     source: "studio",
   });
 }
+
+export function trackBlockParamCommit(props: {
+  tone: "saved" | "error" | "confirm";
+  blockName: string;
+  key: string;
+}): void {
+  trackEvent("studio_block_param_commit", {
+    tone: props.tone,
+    block_name: props.blockName,
+    param_key: props.key,
+  });
+}