@hyperframes/studio 0.8.6 → 0.8.7

package/src/player/components/useTimelineTrackLayout.ts

@@ -7,12 +7,14 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { DraggedClipState } from "./timelineClipDragTypes";
 import { useTimelineTrackDerivations } from "./useTimelineTrackDerivations";
 import {
+  STRIP_H,
   TRACK_H,
   createTimelineRowGeometry,
   type TimelineRowGeometry,
   trackHeights,
   type TimelineTrackHeightClip,
 } from "./timelineLayout";
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
 
 export { getTrackStyle } from "./timelineIcons";
 
@@ -127,13 +129,35 @@ function computeLaneCounts(
   return laneCounts;
 }
 
+/** Group anchor rows have no elements of their own (`groupTimelineTracks`
+ *  pushes them as `[anchorKey, []]`), so `trackHeights` — which only ever
+ *  looks at a row's clips — always gives them TRACK_H. Override those
+ *  specific rows post-hoc: TRACK_H while collapsed, +STRIP_H once the
+ *  group's own `∿` (bus strip) is open. */
+function applyGroupStripHeights(
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[],
+  rowHeights: number[],
+  groups: readonly TimelineTrackGroupInfo[],
+  expandedLaneOwnerIds: ReadonlySet<string>,
+): number[] {
+  if (groups.length === 0) return rowHeights;
+  const groupByAnchor = new Map(groups.map((group) => [group.anchorKey, group]));
+  return tracks.map(([track], index) => {
+    const group = groupByAnchor.get(track);
+    if (!group || !expandedLaneOwnerIds.has(group.id)) return rowHeights[index] ?? TRACK_H;
+    return TRACK_H + STRIP_H;
+  });
+}
+
 function useTimelineRowHeights(
   tracks: [number, TimelineElement[]][],
   gsapAnimations: Map<string, GsapAnimation[]>,
   selectedElementId: string | null,
   selectedElementIds: ReadonlySet<string>,
+  groups: readonly TimelineTrackGroupInfo[],
 ) {
   const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
+  const expandedLaneOwnerIds = usePlayerStore((s) => s.expandedLaneOwnerIds);
   const { laneCounts, rowGeometry } = useMemo(() => {
     const laneCounts = computeLaneCounts(tracks, gsapAnimations);
     // Keyframe lanes follow only the active clip, so a track with several
@@ -163,7 +187,12 @@ function useTimelineRowHeights(
         },
       ];
     });
-    const rowHeights = trackHeights(heightTracks, expandedClipIds);
+    const rowHeights = applyGroupStripHeights(
+      tracks,
+      trackHeights(heightTracks, expandedClipIds),
+      groups,
+      expandedLaneOwnerIds,
+    );
     return {
       laneCounts,
       rowGeometry: createTimelineRowGeometry(
@@ -171,7 +200,15 @@ function useTimelineRowHeights(
         rowHeights,
       ),
     };
-  }, [expandedClipIds, gsapAnimations, tracks, selectedElementId, selectedElementIds]);
+  }, [
+    expandedClipIds,
+    expandedLaneOwnerIds,
+    gsapAnimations,
+    groups,
+    tracks,
+    selectedElementId,
+    selectedElementIds,
+  ]);
   const rowGeometryRef = useRef<TimelineRowGeometry>(rowGeometry);
   rowGeometryRef.current = rowGeometry;
   return {
@@ -188,7 +225,8 @@ export function useTimelineTrackLayout(
   selectedElementId: string | null,
   selectedElementIds: ReadonlySet<string>,
 ) {
-  const { tracks, trackStyles, trackOrder } = useTimelineTrackDerivations(expandedElements);
+  const { tracks, trackStyles, trackOrder, groups, trackGroupOf } =
+    useTimelineTrackDerivations(expandedElements);
   const trackOrderRef = useRef(trackOrder);
   trackOrderRef.current = trackOrder;
   const { laneCounts, rowGeometry, rowGeometryRef, rowHeights } = useTimelineRowHeights(
@@ -196,6 +234,7 @@ export function useTimelineTrackLayout(
     gsapAnimations,
     selectedElementId,
     selectedElementIds,
+    groups,
   );
 
   return {
@@ -207,6 +246,8 @@ export function useTimelineTrackLayout(
     rowGeometry,
     rowGeometryRef,
     rowHeights,
+    groups,
+    trackGroupOf,
   };
 }
 
@@ -227,7 +268,23 @@ function useDisplayRowHeights(
 function useDisplayTrackOrder(draggedClip: DraggedClipState | null, trackOrder: number[]) {
   return useMemo(() => {
     if (!draggedClip?.started || trackOrder.includes(draggedClip.previewTrack)) return trackOrder;
-    return [...trackOrder, draggedClip.previewTrack].sort((a, b) => a - b);
+    // A group's members sit out of raw numeric order (pulled under their
+    // anchor row), so a plain numeric sort here would undo that grouping the
+    // moment a clip drags onto a brand-new track. Insert the new preview
+    // track only relative to other REAL (integer) tracks, leaving any
+    // fractional group-anchor keys exactly where grouping placed them.
+    const preview = draggedClip.previewTrack;
+    const result: number[] = [];
+    let inserted = false;
+    for (const key of trackOrder) {
+      if (!inserted && Number.isInteger(key) && key > preview) {
+        result.push(preview);
+        inserted = true;
+      }
+      result.push(key);
+    }
+    if (!inserted) result.push(preview);
+    return result;
   }, [draggedClip, trackOrder]);
 }
 

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 },
+    ]),
+  );
+}