feat(studio): show the Audio FX section on audio tracks

Adds `audioFx` to the editing-affordances contract and renders the FX panel in
the inspector when an `<audio>` element is selected.

The section is audio-only. A `<video>` carries its sound on a separate
`<audio>` element, so an FX chain on the video would have nothing to process.

Chain and carve settings are written straight back onto the element as
serialised attributes, the way colour grading carries its config, so
persistence is an ordinary attribute write and needs no new server route. A
chain that cannot be parsed renders as empty rather than breaking the panel,
and the attribute is left untouched until the user changes something.

The collapsed group summarises what is on the track ("2 effects + carve") so
the state is visible without expanding it.

Wired into PropertyPanelFlat rather than PropertyPanel: STUDIO_FLAT_INSPECTOR_ENABLED
defaults to true, so the flat inspector is what actually renders.

Author: vanceingalls

packages/core/src/editing/affordances.test.ts

@@ -198,3 +198,14 @@ describe("resolveEditingSections (sections-only export)", () => {
     expect(s).toMatchObject({ timing: true, animation: true });
   });
 });
+
+describe("audioFx section", () => {
+  it("applies to an audio element", () => {
+    expect(resolveEditingSections(baseFacts({ tag: "audio" })).audioFx).toBe(true);
+  });
+
+  it("does not apply to video, whose sound lives on a separate audio element", () => {
+    expect(resolveEditingSections(baseFacts({ tag: "video" })).audioFx).toBe(false);
+    expect(resolveEditingSections(baseFacts({ tag: "div" })).audioFx).toBe(false);
+  });
+});

packages/core/src/editing/affordances.ts

@@ -34,6 +34,9 @@ export interface EditingSectionApplicability {
   /** Position/size/rotation/stacking — meaningless on an element with no
    *  rendered box (e.g. `<audio>`, which never paints a visual frame). */
   layout: boolean;
+  /** Audio FX chain and voiceover carve — `<audio>` only. Video carries its
+   *  sound on a separate `<audio>` element, so this never applies to it. */
+  audioFx: boolean;
   /** Fill/radius/stroke/shadow/blend-mode/clip — same "no rendered box" gate
    *  as `layout`, kept separate since a future tag could need one without
    *  the other. */
@@ -207,6 +210,7 @@ export function resolveEditingSections(facts: EditableElementFacts): EditingSect
   return {
     text: facts.hasEditableText && !facts.isCompositionHost && !facts.isInsideLockedComposition,
     media: facts.tag === "video" || facts.tag === "audio" || facts.tag === "img",
+    audioFx: facts.tag === "audio",
     colorGrading: facts.tag === "video" || facts.tag === "img",
     timing: facts.hasTimingStart || facts.animationCount > 0,
     animation: facts.animationCount > 0,

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

@@ -13,7 +13,20 @@ import { FlatTextSection } from "./propertyPanelFlatTextSection";
 import { FlatStyleSection } from "./propertyPanelFlatStyleSections";
 import { FlatLayoutSection } from "./propertyPanelFlatLayoutSection";
 import { FlatMotionSection } from "./propertyPanelFlatMotionSection";
+import {
+  HF_AUDIO_FX_ATTR,
+  parseAudioFxChain,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import {
+  HF_AUDIO_CARVE_ATTR,
+  normalizeCarveSettings,
+  type HfCarveSettings,
+} from "@hyperframes/core/audio-carve";
 import { FlatMediaSection } from "./propertyPanelFlatMediaSection";
+import type { DomEditSelection } from "./domEditing";
+import { FxSection, type AudioTrackOption } from "./propertyPanelFxSection";
 import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
 import { createGsapLivePreview } from "./gsapLivePreview";
 import { formatTextFieldPreview } from "./propertyPanelSections";
@@ -420,6 +433,14 @@ export function PropertyPanelFlat({
       });
     }
   }
+  if (sections.audioFx) {
+    groups.push({
+      id: "audio-fx",
+      title: "Audio FX",
+      summary: audioFxSummary(element),
+      content: <AudioFxGroup element={element} onSetAttribute={onSetAttribute} />,
+    });
+  }
   if (sections.media) {
     groups.push({
       id: "media",
@@ -514,3 +535,78 @@ export function PropertyPanelFlat({
     </DesignPanelInputProvider>
   );
 }
+
+/** Chain length at a glance, so the collapsed group says whether anything is on. */
+function audioFxSummary(element: DomEditSelection): string {
+  const raw = element.dataAttributes?.["fx-chain"];
+  const carve = element.dataAttributes?.["fx-carve"];
+  let count = 0;
+  if (raw) {
+    try {
+      count = parseAudioFxChain(raw).nodes.filter((n) => n.enabled !== false).length;
+    } catch {
+      return "unreadable";
+    }
+  }
+  const parts: string[] = [];
+  if (count > 0) parts.push(`${count} effect${count === 1 ? "" : "s"}`);
+  if (carve) parts.push("carve");
+  return parts.length > 0 ? parts.join(" + ") : "none";
+}
+
+/**
+ * Bridges the FX panel to the element/attribute world. Chain and carve are
+ * serialised onto the element the way colour grading carries its config, so
+ * persistence is an ordinary attribute write with no new server route.
+ */
+function AudioFxGroup({
+  element,
+  onSetAttribute,
+}: {
+  element: DomEditSelection;
+  onSetAttribute: (attr: string, value: string) => void | Promise<void>;
+}) {
+  const chain = ((): HfAudioFxChain => {
+    const raw = element.dataAttributes?.["fx-chain"];
+    if (!raw) return { version: 1, nodes: [] };
+    try {
+      return parseAudioFxChain(raw);
+    } catch {
+      // Show an unreadable chain as empty rather than breaking the panel; the
+      // attribute is left untouched until the user changes something.
+      return { version: 1, nodes: [] };
+    }
+  })();
+
+  const carve = ((): HfCarveSettings | null => {
+    const raw = element.dataAttributes?.["fx-carve"];
+    if (!raw) return null;
+    try {
+      return normalizeCarveSettings(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  })();
+
+  const sourceOptions: AudioTrackOption[] = (() => {
+    const doc = element.element?.ownerDocument;
+    if (!doc) return [];
+    return Array.from(doc.querySelectorAll<HTMLAudioElement>("audio[id]"))
+      .filter((a) => a.id !== element.id)
+      .map((a) => ({ id: a.id, label: a.id }));
+  })();
+
+  return (
+    <FxSection
+      chain={chain}
+      onChainChange={(next) =>
+        onSetAttribute(HF_AUDIO_FX_ATTR, next.nodes.length ? serializeAudioFxChain(next) : "")
+      }
+      carve={carve}
+      onCarveChange={(next) =>
+        onSetAttribute(HF_AUDIO_CARVE_ATTR, next ? JSON.stringify(next) : "")
+      }
+      sourceOptions={sourceOptions}
+    />
+  );
+}