@hyperframes/studio 0.8.6 → 0.8.8

package/src/player/hooks/previewMessageRouter.ts

@@ -0,0 +1,127 @@
+/**
+ * The `window.message` router for the preview iframe.
+ *
+ * Extracted from `useTimelinePlayer`, which had grown past the studio's 600-line
+ * file cap and carried a `fallow-ignore-next-line complexity` on this function
+ * admitting the same thing. Nothing here is new logic — it is the same four
+ * branches (accept-gate, group levels, state, timeline) against the same refs,
+ * with the suppression retired rather than moved.
+ */
+
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { ClipManifestClip, IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
+import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
+import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
+import { groupLevels, parseGroupLevelsMessage } from "../store/groupLevels";
+import { parseTimelineFromDOM } from "../lib/timelineDOM";
+
+/** What `processTimelineMessage` accepts — the clip-manifest postMessage. */
+export interface ClipManifestMessage {
+  clips: ClipManifestClip[];
+  durationInFrames: number;
+  scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
+  protocolVersion?: unknown;
+  capabilities?: unknown;
+  fps?: unknown;
+}
+
+interface PreviewMessage {
+  source?: string;
+  type?: string;
+  clips?: unknown;
+}
+
+export interface PreviewMessageRouterDeps {
+  iframeRef: { current: HTMLIFrameElement | null };
+  /** Kept as refs by the caller so the listener can be registered once. */
+  processTimelineMessageRef: { current: (data: ClipManifestMessage) => void };
+  enrichMissingCompositionsRef: { current: () => void };
+  lastTimelineMessageRef: { current: number };
+  getAdapter: () => PlaybackAdapter | null;
+  syncTimelineElements: (elements: TimelineElement[]) => void;
+}
+
+/** True when the message did not come from OUR preview iframe. */
+function isForeignSource(e: MessageEvent, iframe: HTMLIFrameElement | null): boolean {
+  return Boolean(e.source && iframe && e.source !== iframe.contentWindow);
+}
+
+/** A preview message worth acting on, or null: the fixture lease, the sender
+ *  check and the protocol accept-gate collapsed into one answer so the listener
+ *  below stays a flat dispatch. */
+function acceptedPreviewMessage(
+  e: MessageEvent,
+  iframe: HTMLIFrameElement | null,
+): PreviewMessage | null {
+  if (hasTimelinePerformanceFixtureLease()) return null;
+  if (isForeignSource(e, iframe)) return null;
+  const data = e.data as PreviewMessage | null;
+  if (data?.source !== "hf-preview") return null;
+  return acceptStudioRuntimeMessage(data) ? data : null;
+}
+
+/** One meter reading per group with an active member. */
+function handleGroupLevelsMessage(data: PreviewMessage): void {
+  const levels = parseGroupLevelsMessage(data);
+  if (levels) groupLevels.notify(levels);
+}
+
+/**
+ * A `state` tick doubles as a recovery hook: if the store still has no
+ * elements, read the manifest straight off the iframe, and if no `timeline`
+ * message has arrived recently, re-run enrichment.
+ */
+function handleStateMessage(
+  deps: PreviewMessageRouterDeps,
+  iframe: HTMLIFrameElement | null,
+): void {
+  try {
+    if (usePlayerStore.getState().elements.length === 0) {
+      const manifest = (iframe?.contentWindow as IframeWindow | null)?.__clipManifest;
+      if (manifest && manifest.clips.length > 0) {
+        deps.processTimelineMessageRef.current(manifest);
+      }
+    }
+    if (Date.now() - deps.lastTimelineMessageRef.current > 500) {
+      deps.enrichMissingCompositionsRef.current();
+    }
+  } catch {}
+}
+
+/**
+ * The clip list. When it arrives empty-handed — the store still has nothing —
+ * fall back to parsing the live DOM, which is the only source left before the
+ * next tick.
+ */
+function handleTimelineMessage(
+  deps: PreviewMessageRouterDeps,
+  iframe: HTMLIFrameElement | null,
+  data: ClipManifestMessage,
+): void {
+  deps.lastTimelineMessageRef.current = Date.now();
+  deps.processTimelineMessageRef.current(data);
+  deps.enrichMissingCompositionsRef.current();
+  if (usePlayerStore.getState().elements.length > 0) return;
+  try {
+    const doc = iframe?.contentDocument;
+    const adapter = deps.getAdapter();
+    if (!doc || !adapter) return;
+    const els = parseTimelineFromDOM(doc, adapter.getDuration());
+    if (els.length > 0) deps.syncTimelineElements(els);
+  } catch {}
+}
+
+export function createPreviewMessageHandler(
+  deps: PreviewMessageRouterDeps,
+): (e: MessageEvent) => void {
+  return (e: MessageEvent) => {
+    const iframe = deps.iframeRef.current;
+    const data = acceptedPreviewMessage(e, iframe);
+    if (!data) return;
+    if (data.type === "group-levels") return handleGroupLevelsMessage(data);
+    if (data.type === "state") return handleStateMessage(deps, iframe);
+    if (data.type === "timeline" && Array.isArray(data.clips)) {
+      handleTimelineMessage(deps, iframe, data as unknown as ClipManifestMessage);
+    }
+  };
+}

package/src/player/hooks/useTimelinePlayer.ts

@@ -35,7 +35,6 @@ import {
 import {
   readTimelineDurationFromDocument,
   mergeTimelineElementsPreservingDowngrades,
-  parseTimelineFromDOM,
 } from "../lib/timelineDOM";
 import { normalizeToZones } from "../components/timelineZones";
 import {
@@ -48,7 +47,7 @@ import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFi
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
-import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
+import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
 
 export function useTimelinePlayer() {
@@ -488,51 +487,14 @@ export function useTimelinePlayer() {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
     const handleWindowKeyUp = (e: KeyboardEvent) => playbackKeyUpRef.current(e);
 
-    // Pre-existing message-router complexity — surfaced by line shifts, not new logic.
-    // fallow-ignore-next-line complexity
-    const handleMessage = (e: MessageEvent) => {
-      if (hasTimelinePerformanceFixtureLease()) return;
-      const data = e.data;
-      const ourIframe = iframeRef.current;
-      if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {
-        return;
-      }
-      if (data?.source === "hf-preview") {
-        if (!acceptStudioRuntimeMessage(data)) return;
-      }
-      if (data?.source === "hf-preview" && data?.type === "state") {
-        try {
-          if (usePlayerStore.getState().elements.length === 0) {
-            const iframeWin = ourIframe?.contentWindow as IframeWindow | null;
-            const manifest = iframeWin?.__clipManifest;
-            if (manifest && manifest.clips.length > 0) {
-              processTimelineMessageRef.current(manifest);
-            }
-          }
-          const msSinceTimeline = Date.now() - lastTimelineMessageRef.current;
-          if (msSinceTimeline > 500) {
-            enrichMissingCompositionsRef.current();
-          }
-        } catch {}
-      }
-      if (data?.source === "hf-preview" && data?.type === "timeline" && Array.isArray(data.clips)) {
-        lastTimelineMessageRef.current = Date.now();
-        processTimelineMessageRef.current(data);
-        enrichMissingCompositionsRef.current();
-        if (usePlayerStore.getState().elements.length === 0) {
-          try {
-            const doc = ourIframe?.contentDocument;
-            const adapter = getAdapter();
-            if (doc && adapter) {
-              const els = parseTimelineFromDOM(doc, adapter.getDuration());
-              if (els.length > 0) {
-                syncTimelineElements(els);
-              }
-            }
-          } catch {}
-        }
-      }
-    };
+    const handleMessage = createPreviewMessageHandler({
+      iframeRef,
+      processTimelineMessageRef,
+      enrichMissingCompositionsRef,
+      lastTimelineMessageRef,
+      getAdapter,
+      syncTimelineElements,
+    });
 
     const handleVisibilityChange = () => {
       if (document.hidden && usePlayerStore.getState().isPlaying) {

package/src/player/lib/timelineDOM.ts

@@ -12,6 +12,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
+import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -67,6 +68,37 @@ function resolveClipTag(clip: ClipManifestClip): string {
   return clip.tagName || clip.kind || "div";
 }
 
+// One `<hf-audio-group>` scan per document, not per clip — resolveAudioGroups
+// walks the whole tree, and a parse touches every clip in it.
+interface GroupInfo {
+  label: string;
+  volume: number;
+  hidden: boolean;
+  fxChain?: string;
+}
+
+const groupInfoCache = new WeakMap<Document, Map<string, GroupInfo>>();
+
+function groupInfoFor(doc: Document | null | undefined, groupId: string): GroupInfo {
+  if (!doc) return { label: groupId, volume: 1, hidden: false };
+  let info = groupInfoCache.get(doc);
+  if (!info) {
+    info = new Map(
+      resolveAudioGroups(doc).map((group) => [
+        group.id,
+        {
+          label: group.label,
+          volume: group.volume,
+          hidden: group.hidden,
+          ...(group.fxChain ? { fxChain: group.fxChain } : {}),
+        },
+      ]),
+    );
+    groupInfoCache.set(doc, info);
+  }
+  return info.get(groupId) ?? { label: groupId, volume: 1, hidden: false };
+}
+
 // fallow-ignore-next-line complexity
 export function createTimelineElementFromManifestClip(params: {
   clip: ClipManifestClip;
@@ -138,6 +170,15 @@ export function createTimelineElementFromManifestClip(params: {
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
+    const audioGroup = hostEl.getAttribute("data-audio-group");
+    if (audioGroup) {
+      entry.audioGroup = audioGroup;
+      const info = groupInfoFor(doc ?? hostEl.ownerDocument, audioGroup);
+      entry.audioGroupLabel = info.label;
+      entry.audioGroupVolume = info.volume;
+      entry.audioGroupHidden = info.hidden;
+      if (info.fxChain) entry.audioGroupFxChain = info.fxChain;
+    }
     const fxChain = hostEl.getAttribute("data-fx-chain");
     if (fxChain) entry.fxChain = fxChain;
     const automation = hostEl.getAttribute("data-automation");
@@ -356,6 +397,16 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     const timelineRole = el.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
 
+    const domAudioGroup = el.getAttribute("data-audio-group");
+    if (domAudioGroup) {
+      entry.audioGroup = domAudioGroup;
+      const domGroupInfo = groupInfoFor(doc, domAudioGroup);
+      entry.audioGroupLabel = domGroupInfo.label;
+      entry.audioGroupVolume = domGroupInfo.volume;
+      entry.audioGroupHidden = domGroupInfo.hidden;
+      if (domGroupInfo.fxChain) entry.audioGroupFxChain = domGroupInfo.fxChain;
+    }
+
     // Sub-compositions
     const compSrc =
       el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");

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