feat(studio): show every automated knob at the playhead, and carve as one module

An automated parameter has two values: the number sitting in the chain, which is
only the seed a lane replaced, and the number the envelope is on right now. The
second is the true one, so the panel shows it — on the carve rack's readouts and
on every effect's own fader and number field. A rack that showed the seed stood
still while the carve was audibly working.

Off the clip it keeps sampling rather than falling back to the stored number: a
lane holds its first value backwards and its last forwards, so before the clip
starts it already knows what it will open on, and the stored seed is a value
nothing will ever play. Showing it made the fader jump the moment the clip came
under the playhead.

The playhead comes off the liveTime channel, throttled to 30 Hz — the RAF loop
deliberately keeps frames out of the store, so a panel watching only the store
would sit still for a whole take. PropertyPanel had that subscription inline;
it is now one shared hook with two callers.

Readouts reserve the width their parameter can need rather than what its current
value takes, because an updating value one character narrower shunted everything
after it sideways 30 times a second.

The carve's effects are presented as one module: an author switched on a carve,
and the peaking filters plus the level stage are how it is built, not six things
to remove one at a time. Opening it lists every member's settings as readouts,
since strength is what sets them. No carve control is offered on a track another
track already carves against — that track is the voice, not the bed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: vanceingalls

packages/studio/src/components/StudioRightPanel.tsx

@@ -327,6 +327,21 @@ export function StudioRightPanel({
     },
     [projectId, refreshFileTree, showToast],
   );
+
+  /**
+   * A dial being dragged writes to the preview and stops there.
+   *
+   * Every one of these panels previews on each pointermove and commits on
+   * release. Persisting the moves too put a fragment of the drag in the undo
+   * stack — and since those writes race, history could not coalesce them
+   * reliably, so undo took back a sliver of the gesture rather than the gesture.
+   * The release's own commit is what reaches the file and the undo stack.
+   */
+  const setAttributeWhileDragging = useCallback(
+    (attr: string, value: string | null) =>
+      handleDomAttributeLiveCommit(attr, value, undefined, { previewOnly: true }),
+    [handleDomAttributeLiveCommit],
+  );
   const handleHideAllSelected = () => {
     const { elements } = usePlayerStore.getState();
     const keys = timelineKeysForSelections(domEditGroupSelections, elements, activeCompPath);
@@ -361,7 +376,7 @@ export function StudioRightPanel({
         onSetStyle={handleDomStyleCommit}
         onSetAttribute={handleDomAttributeCommit}
         onSetAttributes={handleDomAttributesCommit}
-        onSetAttributeLive={handleDomAttributeLiveCommit}
+        onSetAttributeLive={setAttributeWhileDragging}
         onSetAttributeQuiet={handleDomAttributeQuietCommit}
         onApplyColorGradingScope={handleApplyColorGradingScope}
         onSetHtmlAttribute={handleDomHtmlAttributeCommit}

packages/studio/src/components/TimelineToolbar.test.tsx

@@ -99,3 +99,49 @@ describe("TimelineToolbar — motion path endpoints", () => {
     act(() => root.unmount());
   });
 });
+
+describe("TimelineToolbar — keyframes on audio tracks", () => {
+  const clip = (tag: string) => ({
+    id: "bgm",
+    key: "bgm",
+    tag,
+    start: 0,
+    duration: 10,
+    track: 1,
+  });
+
+  /** A session whose selection would otherwise offer the keyframe toggle. */
+  function sessionFor(tag: string) {
+    usePlayerStore.setState({ elements: [clip(tag)], selectedElementId: "bgm", currentTime: 1 });
+    const element = document.createElement(tag);
+    element.id = "bgm";
+    return {
+      domEditSelection: makeSelection("Element", element),
+      selectedGsapAnimations: [],
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapConvertToKeyframes: vi.fn(),
+      handleGsapRemoveKeyframe: vi.fn(),
+    } satisfies NonNullable<React.ComponentProps<typeof TimelineToolbar>["domEditSession"]>;
+  }
+
+  it("offers no keyframe toggle for an audio clip", () => {
+    // An audio clip has no box on the canvas, so there is nothing to move or fade —
+    // and pressing this seeded a tween from the position properties, which put a
+    // position lane on a track that has no position. Audio is automated instead.
+    const { host, root } = renderToolbar(sessionFor("audio"));
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Add keyframe at playhead"]',
+    );
+    expect(button?.disabled).toBe(true);
+    act(() => root.unmount());
+  });
+
+  it("still offers it for a visual clip", () => {
+    const { host, root } = renderToolbar(sessionFor("div"));
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Add keyframe at playhead"]',
+    );
+    expect(button?.disabled).toBe(false);
+    act(() => root.unmount());
+  });
+});

packages/studio/src/components/TimelineToolbar.tsx

@@ -86,15 +86,32 @@ function resolveKeyframeToggleState(
   };
 }
 
+/**
+ * Can this element be keyframed at all?
+ *
+ * An audio clip cannot. It has no box on the canvas, so there is nothing to move,
+ * scale or fade — and "add a keyframe" on one seeds a tween from the position
+ * properties, which produced a position lane on a track that has no position. Audio
+ * is automated instead: volume and effect parameters, on their own lanes.
+ */
+function isKeyframeable(element: TimelineElement | undefined): boolean {
+  return element?.tag !== "audio";
+}
+
 function useKeyframeToggle(session?: DomEditSessionSlice) {
   const currentTime = usePlayerStore((s) => s.currentTime);
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+  const elements = usePlayerStore((s) => s.elements);
   const sessionRef = useRef(session);
   sessionRef.current = session;
 
   const onToggle = useEnableKeyframes(
     sessionRef as React.RefObject<EnableKeyframesSession | undefined>,
   );
 
+  const selected = elements.find((element) => (element.key ?? element.id) === selectedElementId);
+  if (!isKeyframeable(selected)) return { ...NO_KEYFRAME_TOGGLE, onToggle: undefined };
+
   const toggleState = resolveKeyframeToggleState(session, currentTime);
 
   return {

packages/studio/src/components/editor/PropertyPanel.tsx

@@ -1,5 +1,5 @@
 import { scopedElementKey } from "../../hooks/gsapKeyframeCacheHelpers";
-import { memo, useEffect, useMemo, useRef, useState } from "react";
+import { memo, useMemo, useRef, useState } from "react";
 import { Move } from "../../icons/SystemIcons";
 import { InspectorHeaderActions } from "./InspectorHeaderActions";
 import { useStudioShellContext } from "../../contexts/StudioContext";
@@ -29,7 +29,8 @@ import { KeyframeNavigation } from "./KeyframeNavigation";
 import { STUDIO_FLAT_INSPECTOR_ENABLED } from "./manualEditingAvailability";
 import { PropertyPanelFlat } from "./PropertyPanelFlat";
 import { createGsapLivePreview } from "./gsapLivePreview";
-import { usePlayerStore, liveTime } from "../../player";
+import { usePlayerStore } from "../../player";
+import { useLivePlayheadTime } from "../../hooks/useLivePlayheadTime";
 import { TimingSection } from "./propertyPanelTimingSection";
 import { type PropertyPanelProps } from "./propertyPanelHelpers";
 import { GestureRecordPanelButton } from "./GestureRecordControl";
@@ -114,31 +115,14 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
   const { showToast } = useStudioShellContext();
   const [clipboardCopied, setClipboardCopied] = useState(false);
   const clipboardTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
-  const storeTime = usePlayerStore((s) => s.currentTime);
-  const isPlaying = usePlayerStore((s) => s.isPlaying);
   const timelineElements = usePlayerStore((s) => s.elements);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const selectedElementHidden = isSelectedElementHidden(timelineElements, selectedElementId);
   const visibilityToggleLabel = selectedElementHidden ? "Show element" : "Hide element";
-  const liveTimeRef = useRef(storeTime);
-  const [, forceRender] = useState(0);
-  useEffect(() => {
-    if (!isPlaying) return;
-    let timerId: ReturnType<typeof setTimeout> | 0 = 0;
-    const unsub = liveTime.subscribe((t) => {
-      liveTimeRef.current = t;
-      if (!timerId)
-        timerId = setTimeout(() => {
-          timerId = 0;
-          forceRender((v) => v + 1);
-        }, 33);
-    });
-    return () => {
-      unsub();
-      if (timerId) clearTimeout(timerId);
-    };
-  }, [isPlaying]);
-  const currentTime = isPlaying ? liveTimeRef.current : storeTime;
+  // Live during playback, the store's when paused — see the hook. Shared with the
+  // audio FX panel, which follows the playhead for the same reason: a value the
+  // timeline drives has to be shown moving, not frozen at what the attribute says.
+  const currentTime = useLivePlayheadTime();
   const cacheElementKey = element?.id ?? element?.selector ?? "";
   const cacheEntry = usePlayerStore((s) => s.keyframeCache.get(cacheElementKey));
 

packages/studio/src/components/editor/PropertyPanelFlat.tsx

@@ -6,6 +6,7 @@ import { slugifyDesignInput } from "../../utils/designInputTracking";
 import { isTextEditableSelection } from "./domEditing";
 import type { PropertyPanelFlatProps } from "./propertyPanelFlatProps";
 import { formatPxMetricValue } from "./propertyPanelHelpers";
+import { audioFxSummary } from "./audioFxSummary";
 import { PropertyPanelFlatHeader } from "./PropertyPanelFlatHeader";
 import { PropertyPanelFlatFooter } from "./PropertyPanelFlatFooter";
 import { FlatGroupHeader } from "./propertyPanelFlatPrimitives";
@@ -14,8 +15,7 @@ import { FlatStyleSection } from "./propertyPanelFlatStyleSections";
 import { FlatLayoutSection } from "./propertyPanelFlatLayoutSection";
 import { FlatMotionSection } from "./propertyPanelFlatMotionSection";
 import { isCanaryEnabled } from "../../telemetry/canary";
-import { audioFxSummary } from "./audioFxSummary";
-import { AudioFxGroup } from "./propertyPanelAudioFxGroup";
+import { AudioFxGroup } from "./propertyPanelAudioFxGroup.js";
 import { useVolumeAutomation } from "./useVolumeAutomation";
 import { FlatMediaSection } from "./propertyPanelFlatMediaSection";
 import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";

packages/studio/src/components/editor/audioFxSummary.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { audioFxSummary } from "./audioFxSummary";
+import type { DomEditSelection } from "./domEditingTypes";
+
+const el = (dataAttributes: Record<string, string>): DomEditSelection =>
+  ({ dataAttributes }) as unknown as DomEditSelection;
+
+const chain = (nodes: unknown[]) => JSON.stringify({ version: 1, nodes });
+
+describe("audioFxSummary", () => {
+  it("counts a carve as one module, not as the filters behind it", () => {
+    // Six bands and a level stage reading "7 effects" is the misreading the
+    // grouping exists to prevent.
+    const summary = audioFxSummary(
+      el({
+        "fx-chain": chain([
+          { type: "peaking", id: "n1", fromCarve: true, params: { frequency: 400 } },
+          { type: "peaking", id: "n2", fromCarve: true, params: { frequency: 1600 } },
+          { type: "gain", id: "n3", fromCarve: true, params: { gain: -6 } },
+        ]),
+        "fx-carve": JSON.stringify({ source: "vo", strength: 0.25 }),
+      }),
+    );
+    expect(summary).toBe("carve");
+  });
+
+  it("counts hand-built effects alongside the module", () => {
+    expect(
+      audioFxSummary(
+        el({
+          "fx-chain": chain([
+            { type: "peaking", id: "n1", fromCarve: true, params: { frequency: 400 } },
+            { type: "lowpass", id: "n2", params: { frequency: 8000 } },
+            { type: "delay", id: "n3", params: { time: 200 } },
+          ]),
+        }),
+      ),
+    ).toBe("2 effects + carve");
+  });
+
+  it("says how many when there is no carve", () => {
+    expect(audioFxSummary(el({ "fx-chain": chain([{ type: "lowpass", id: "n1" }]) }))).toBe(
+      "1 effect",
+    );
+  });
+
+  it("names a carve that is on but has not compiled to filters yet", () => {
+    // Switching it on with no voice chosen leaves the control in this section with
+    // nothing behind it; the summary should still say the section holds one.
+    expect(audioFxSummary(el({ "fx-carve": JSON.stringify({ source: "", strength: 0.25 }) }))).toBe(
+      "carve",
+    );
+  });
+
+  it("ignores bypassed effects, as it always did", () => {
+    expect(
+      audioFxSummary(
+        el({
+          "fx-chain": chain([
+            { type: "lowpass", id: "n1", enabled: false },
+            { type: "delay", id: "n2" },
+          ]),
+        }),
+      ),
+    ).toBe("1 effect");
+  });
+
+  it("says none for a track with neither", () => {
+    expect(audioFxSummary(el({}))).toBe("none");
+  });
+
+  it("says so when the chain cannot be read", () => {
+    expect(audioFxSummary(el({ "fx-chain": "{not json" }))).toBe("unreadable");
+  });
+});

packages/studio/src/components/editor/audioFxSummary.ts

@@ -1,27 +1,36 @@
 /**
  * What the collapsed Audio FX group says it holds.
  *
- * Its own module because `PropertyPanelFlat.tsx` is at the repo's 600-line
- * budget, and this is the piece with no dependency on the panel around it.
+ * It has to describe the rack the author would see on opening it, which counts a
+ * carve as one module rather than as the filters it compiles to. Six peaking
+ * bands and a level stage reading "7 effects" invited exactly the misreading the
+ * grouping exists to prevent — that they are seven things to manage.
  */
 
 import { parseAudioFxChain } from "@hyperframes/core/audio-fx";
-import type { DomEditSelection } from "./domEditing";
+import type { DomEditSelection } from "./domEditingTypes";
 
-/** Chain length at a glance, so the collapsed group says whether anything is on. */
 export function audioFxSummary(element: DomEditSelection): string {
   const raw = element.dataAttributes?.["fx-chain"];
-  const carve = element.dataAttributes?.["fx-carve"];
-  let count = 0;
+  const carveAttr = element.dataAttributes?.["fx-carve"];
+  let handBuilt = 0;
+  let carveNodes = 0;
   if (raw) {
     try {
-      count = parseAudioFxChain(raw).nodes.filter((n) => n.enabled !== false).length;
+      for (const node of parseAudioFxChain(raw).nodes) {
+        if (node.enabled === false) continue;
+        if (node.fromCarve) carveNodes += 1;
+        else handBuilt += 1;
+      }
     } catch {
       return "unreadable";
     }
   }
   const parts: string[] = [];
-  if (count > 0) parts.push(`${count} effect${count === 1 ? "" : "s"}`);
-  if (carve) parts.push("carve");
+  if (handBuilt > 0) parts.push(`${handBuilt} effect${handBuilt === 1 ? "" : "s"}`);
+  // One name for the module however many filters are behind it. Named when the
+  // carve is switched on at all, because the control is in this section whether or
+  // not it has compiled to anything yet.
+  if (carveNodes > 0 || carveAttr) parts.push("carve");
   return parts.length > 0 ? parts.join(" + ") : "none";
 }