@hyperframes/studio 0.7.107 → 0.7.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.107",
+  "version": "0.7.108",
   "description": "",
   "repository": {
     "type": "git",
@@ -47,11 +47,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/player": "0.7.107",
-    "@hyperframes/parsers": "0.7.107",
-    "@hyperframes/studio-server": "0.7.107",
-    "@hyperframes/sdk": "0.7.107",
-    "@hyperframes/core": "0.7.107"
+    "@hyperframes/core": "0.7.108",
+    "@hyperframes/parsers": "0.7.108",
+    "@hyperframes/player": "0.7.108",
+    "@hyperframes/studio-server": "0.7.108",
+    "@hyperframes/sdk": "0.7.108"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -68,7 +68,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.107"
+    "@hyperframes/producer": "0.7.108"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/StudioRightPanel.tsx

@@ -124,6 +124,7 @@ export function StudioRightPanel({
     handleDomStyleCommit,
     handleDomAttributeCommit,
     handleDomAttributeLiveCommit,
+    handleDomAttributeQuietCommit,
     handleDomHtmlAttributeCommit,
     handleDomAttributesCommit,
     handleDomPathOffsetCommit,
@@ -326,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);
@@ -360,7 +376,8 @@ export function StudioRightPanel({
         onSetStyle={handleDomStyleCommit}
         onSetAttribute={handleDomAttributeCommit}
         onSetAttributes={handleDomAttributesCommit}
-        onSetAttributeLive={handleDomAttributeLiveCommit}
+        onSetAttributeLive={setAttributeWhileDragging}
+        onSetAttributeQuiet={handleDomAttributeQuietCommit}
         onApplyColorGradingScope={handleApplyColorGradingScope}
         onSetHtmlAttribute={handleDomHtmlAttributeCommit}
         onRemoveBackground={handleRemoveBackground}

package/src/components/TimelineToolbar.test.tsx

@@ -118,3 +118,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());
+  });
+});

package/src/components/TimelineToolbar.tsx

@@ -86,8 +86,22 @@ 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;
 
@@ -95,6 +109,9 @@ function useKeyframeToggle(session?: DomEditSessionSlice) {
     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 {

package/src/components/editor/PropertyPanel.test.tsx

@@ -238,7 +238,11 @@ async function renderPanel(
 // renderPanel resetModules()+dynamic-imports PropertyPanel (needed for a fresh
 // flag read); transforming the full section graph uncached can exceed the 5s
 // default under heavy parallel full-suite load, so give these a wider margin.
-const RENDER_TIMEOUT_MS = 20_000;
+// 20s itself has now been observed timing out in CI's full-monorepo run (the
+// same suite passes in well under 2s standalone) — widened again rather than
+// re-tuned down to a number that will just need doing again next time CI adds
+// load.
+const RENDER_TIMEOUT_MS = 45_000;
 
 // Find the collapsed accordion row whose title matches and click it open.
 function openFlatGroup(host: HTMLElement, title: string) {

package/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));
 

package/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";
@@ -13,6 +14,9 @@ import { FlatTextSection } from "./propertyPanelFlatTextSection";
 import { FlatStyleSection } from "./propertyPanelFlatStyleSections";
 import { FlatLayoutSection } from "./propertyPanelFlatLayoutSection";
 import { FlatMotionSection } from "./propertyPanelFlatMotionSection";
+import { isCanaryEnabled } from "../../telemetry/canary";
+import { AudioFxGroup } from "./propertyPanelAudioFxGroup.js";
+import { useVolumeAutomation } from "./useVolumeAutomation";
 import { FlatMediaSection } from "./propertyPanelFlatMediaSection";
 import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
 import { createGsapLivePreview } from "./gsapLivePreview";
@@ -64,6 +68,7 @@ export function PropertyPanelFlat({
   onSetAttribute,
   onSetAttributes,
   onSetAttributeLive,
+  onSetAttributeQuiet,
   onApplyColorGradingScope,
   onSetHtmlAttribute,
   onRemoveBackground,
@@ -252,6 +257,8 @@ export function PropertyPanelFlat({
   const showMotionEffects = gsapEffectHandlers !== null;
   const showMotionGroup = showMotionTiming || showMotionEffects;
 
+  const volumeAutomation = useVolumeAutomation(element, onSetAttributeQuiet ?? onSetAttributeLive);
+
   const groups: FlatGroupDescriptor[] = [];
   if (isTextEditable) {
     groups.push({
@@ -420,6 +427,23 @@ export function PropertyPanelFlat({
       });
     }
   }
+  // Behind `audio-fx-rack`, at 0%. Gates the AUTHORING surface only: the runtime
+  // and render still honour a `data-fx-chain` already on an element, so a
+  // composition written through the skill does not go silently dry off-cohort.
+  if (sections.audioFx && isCanaryEnabled("audio-fx-rack")) {
+    groups.push({
+      id: "audio-fx",
+      title: "Audio FX",
+      summary: audioFxSummary(element),
+      content: (
+        <AudioFxGroup
+          element={element}
+          onSetAttributeQuiet={onSetAttributeQuiet ?? onSetAttributeLive}
+          onSetAttributeLive={onSetAttributeLive}
+        />
+      ),
+    });
+  }
   if (sections.media) {
     groups.push({
       id: "media",
@@ -434,6 +458,7 @@ export function PropertyPanelFlat({
           onSetAttribute={onSetAttribute}
           onSetHtmlAttribute={onSetHtmlAttribute}
           onRemoveBackground={onRemoveBackground}
+          {...volumeAutomation}
         />
       ),
     });

package/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");
+  });
+});

package/src/components/editor/audioFxSummary.ts

@@ -0,0 +1,36 @@
+/**
+ * What the collapsed Audio FX group says it holds.
+ *
+ * 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 { HF_AUDIO_FX_DATA_KEY, parseAudioFxChain } from "@hyperframes/core/audio-fx";
+import type { DomEditSelection } from "./domEditingTypes";
+
+export function audioFxSummary(element: DomEditSelection): string {
+  const raw = element.dataAttributes?.[HF_AUDIO_FX_DATA_KEY];
+  const carveAttr = element.dataAttributes?.["fx-carve"];
+  let handBuilt = 0;
+  let carveNodes = 0;
+  if (raw) {
+    try {
+      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 (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";
+}

package/src/components/editor/audioFxTelemetry.test.ts

@@ -0,0 +1,129 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import type { HfAudioFxChain } from "@hyperframes/core/audio-fx";
+
+const trackStudioEvent = vi.fn();
+vi.mock("../../utils/studioTelemetry", () => ({
+  trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
+}));
+
+const { chainShape, nodeOrigin, trackChainObserved, trackParamCommitted, trackPresetApplied } =
+  await import("./audioFxTelemetry");
+
+beforeEach(() => trackStudioEvent.mockReset());
+
+const chainOf = (nodes: HfAudioFxChain["nodes"]): HfAudioFxChain => ({ version: 1, nodes });
+
+describe("what the rack reports", () => {
+  it("namespaces every event so the feature can be found as one thing", () => {
+    trackPresetApplied("voice-clean", "voice", 5, "append", { trackKind: "voice" });
+    expect(trackStudioEvent).toHaveBeenCalledWith("audio_fx_preset_applied", expect.anything());
+  });
+
+  it("carries what the track is, so a preset's use can be read per material", () => {
+    trackPresetApplied("telephone", "character", 7, "append", { trackKind: "music" });
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({
+      preset: "telephone",
+      family: "character",
+      track_kind: "music",
+    });
+  });
+
+  it("says 'unknown' rather than nothing when the track is unclassified", () => {
+    // Absent and "unclassified" are different facts; encoding them the same way
+    // is what makes a breakdown read as a gap that is not there.
+    trackPresetApplied("hall", "space", 1, "append", {});
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({ track_kind: "unknown" });
+  });
+
+  it("separates the two surfaces a parameter can be set from", () => {
+    // The whole one-knob design rests on which of these people use.
+    trackParamCommitted("compressor", "ratio", 4, "details", {});
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({
+      effect: "compressor",
+      param: "ratio",
+      value: 4,
+      surface: "details",
+    });
+  });
+});
+
+describe("a chain reduced to counts", () => {
+  it("names where each node came from", () => {
+    expect(nodeOrigin({ type: "peaking", fromPreset: "voice-clean" })).toBe("preset");
+    expect(nodeOrigin({ type: "peaking", fromCarve: true })).toBe("carve");
+    expect(nodeOrigin({ type: "gain", fromLeveller: true })).toBe("leveller");
+    expect(nodeOrigin({ type: "highpass" })).toBe("hand");
+  });
+
+  it("counts by origin, which is what separates hand-built from generated", () => {
+    const shape = chainShape(
+      chainOf([
+        { type: "highpass", fromPreset: "voice-clean" },
+        { type: "peaking", fromPreset: "voice-clean" },
+        { type: "peaking", fromCarve: true },
+        { type: "lowpass" },
+      ]),
+    );
+    expect(shape).toMatchObject({
+      node_count: 4,
+      nodes_from_preset: 2,
+      nodes_from_carve: 1,
+      nodes_by_hand: 1,
+      preset_count: 1,
+    });
+  });
+
+  it("counts distinct presets, not preset nodes — stacking is the question", () => {
+    const shape = chainShape(
+      chainOf([
+        { type: "highpass", fromPreset: "voice-clean" },
+        { type: "lowpass", fromPreset: "telephone" },
+        { type: "peaking", fromPreset: "telephone" },
+      ]),
+    );
+    expect(shape.preset_count).toBe(2);
+  });
+
+  it("survives an empty or absent chain", () => {
+    expect(chainShape(null)).toMatchObject({ node_count: 0, preset_count: 0 });
+  });
+
+  it("ships no chain contents — only counts and flags", () => {
+    // The standing rule: nothing user-authored leaves the browser. A parameter
+    // value or an element id in here would be the author's own data.
+    const shape = chainShape(chainOf([{ type: "peaking", id: "n1", params: { frequency: 3000 } }]));
+    const serialized = JSON.stringify(shape);
+    expect(serialized).not.toContain("3000");
+    expect(serialized).not.toContain("n1");
+  });
+});
+
+describe("effects this session did not apply", () => {
+  it("calls a chain with no panel edits behind it authored outside", () => {
+    // This is the agent signal. An agent edits the composition and the panel
+    // simply finds the work done — none of its own events ever fire.
+    trackChainObserved(
+      chainOf([{ type: "highpass", fromPreset: "voice-clean" }]),
+      { firstSight: true, panelEdits: 0, hasCarve: false, hasAutomation: false },
+      { trackKind: "voice" },
+    );
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "audio_fx_chain_observed",
+      expect.objectContaining({ authored_outside: true, first_sight: true }),
+    );
+  });
+
+  it("does not, when this session's own edits explain it", () => {
+    trackChainObserved(
+      chainOf([{ type: "highpass" }]),
+      { firstSight: false, panelEdits: 3, hasCarve: false, hasAutomation: false },
+      {},
+    );
+    expect(trackStudioEvent.mock.calls[0]?.[1]).toMatchObject({
+      authored_outside: false,
+      panel_edits: 3,
+    });
+  });
+});