@hyperframes/studio 0.8.10 → 0.8.12

package/src/hooks/timelineAudioGroupVolume.ts

@@ -1,4 +1,9 @@
 import { useCallback } from "react";
+import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
+import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
+import { usePlayerStore } from "../player";
+import type { TimelineElementPatch } from "../player/store/timelineElement";
+import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
 import {
   buildPatchTarget,
   persistElementAttribute,
@@ -21,6 +26,111 @@ function patchLiveGroupAttribute(
   if (!target) return;
   if (value === null) target.removeAttribute(attr);
   else target.setAttribute(attr, value);
+  invalidateGroupInfoCache(iframe?.contentDocument);
+}
+
+/**
+ * `data-volume` exactly as core reads it (`readAudioGroupVolume`): an absent or
+ * empty attribute is UNITY, not zero.
+ *
+ * `Number(null)` and `Number("")` are both 0 and both finite, so the obvious
+ * `Number.isFinite(Number(value))` mirrored "silent" into the store for a
+ * removed attribute while the DOM, the preview bus and the render all read 1 —
+ * exactly the parse divergence this mirror exists to eliminate.
+ */
+function mirroredGroupVolume(value: string | null): number {
+  if (!value) return 1;
+  const parsed = parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : 1;
+}
+
+/** Which store field each writable group attribute mirrors into. */
+const GROUP_ATTR_TO_MIRROR: Record<
+  string,
+  (value: string | null, groupId: string) => TimelineElementPatch
+> = {
+  "data-hidden": (value) => ({ audioGroupHidden: value !== null }),
+  "data-volume": (value) => ({ audioGroupVolume: mirroredGroupVolume(value) }),
+  "data-label": (value, groupId) => ({ audioGroupLabel: value ?? groupId }),
+  [HF_AUDIO_FX_ATTR]: (value) => ({ audioGroupFxChain: value ?? undefined }),
+  [HF_AUDIO_AUTOMATION_ATTR]: (value) => ({ audioGroupAutomation: value ?? undefined }),
+};
+
+/**
+ * Mirror a group attribute onto the store copy every member carries.
+ *
+ * The timeline derives a group's label / volume / mute / chain from these
+ * mirrored `audioGroup*` fields on its MEMBERS, not from the group element —
+ * and a group write only ever touched the file and the live preview DOM.
+ * Nothing re-parsed, so the header went on reading the old value: the observed
+ * symptom was a muted group whose button stayed "Mute group", re-writing
+ * `data-hidden` on every click and never offering to unmute.
+ *
+ * Invalidating the parse cache is necessary but not sufficient — it only
+ * ensures the NEXT parse is honest, and a live attribute patch does not cause
+ * one. Same reason `commitDataAttribute` carries `syncStoredAutomationFromPreview`.
+ */
+function syncStoredGroupAttribute(groupId: string, attr: string, value: string | null): void {
+  const toPatch = GROUP_ATTR_TO_MIRROR[attr];
+  if (!toPatch) return;
+  const patch = toPatch(value, groupId);
+  // ONE pass and one notification, rather than `updateElement` per member.
+  // That helper maps the whole `elements` array per call, so a 3-member group on
+  // a 500-clip composition was 1500 object spreads and 3 store notifications per
+  // drag frame — at ~60/s, with every `elements`-keyed memo downstream
+  // recomputing each time.
+  // BOTH stores, because a group declared inside a sub-composition has no flat
+  // member to mirror onto: `childGroupState` keeps those members out of
+  // `elements` entirely, so their `audioGroup*` fields come from the
+  // `DomClipChild` record instead. Mirroring only `elements` made this whole
+  // function a no-op for such a group — the header kept the pre-write chain, its
+  // FX button showed the old count, and `laneCount` stayed 0 so the lane
+  // disclosure never appeared for automation that now existed. Verbatim the
+  // symptom this docblock claims to have fixed, fixed only for flat members.
+  //
+  // `setDomClipChildren` has one other writer, inside `processTimelineMessage`,
+  // which a live attribute patch does not trigger.
+  usePlayerStore.setState((state) => {
+    const next: Partial<typeof state> = {
+      elements: state.elements.map((el) => (el.audioGroup === groupId ? { ...el, ...patch } : el)),
+    };
+    if (state.domClipChildren.some((child) => child.audioGroup === groupId)) {
+      next.domClipChildren = state.domClipChildren.map((child) =>
+        child.audioGroup === groupId ? { ...child, ...patch } : child,
+      );
+    }
+    return next;
+  });
+}
+
+/**
+ * The composition FILE that contains a group element, walking up through
+ * composition ancestors until one names a file.
+ *
+ * `getTimelineElementSourceFile` stops at the nearest `[data-composition-id]`,
+ * which for an inlined sub-composition is its own ROOT element — that carries
+ * the composition id but not the file. The file is on the HOST one level above
+ * it. Measured on a live preview:
+ *
+ *   hf-audio-group#voiceover        (no composition attrs)
+ *   section#voices-root             data-composition-id="voices"          <- stops here
+ *   div#voices-host                 data-composition-file="…/voices.html" <- file is here
+ *   body                            data-composition-id="<root>"
+ *
+ * Returns undefined for a group in the root composition (body names an id but
+ * no file), which is exactly when the caller should fall back to activeCompPath.
+ */
+export function resolveGroupSourceFile(groupEl: Element | null): string | undefined {
+  let node: Element | null = groupEl?.parentElement ?? null;
+  while (node) {
+    const owner: Element | null = node.closest("[data-composition-id]");
+    if (!owner) return undefined;
+    const file =
+      owner.getAttribute("data-composition-file") ?? owner.getAttribute("data-composition-src");
+    if (file) return file;
+    node = owner.parentElement;
+  }
+  return undefined;
 }
 
 interface SetAudioGroupAttributeInput {
@@ -56,7 +166,16 @@ async function setAudioGroupAttribute({
   domEditSaveTimestampRef,
   pendingTimelineEditPathRef,
 }: SetAudioGroupAttributeInput): Promise<string[]> {
-  const targetPath = activeCompPath || "index.html";
+  // The file that actually CONTAINS the group element, not just the active
+  // composition. A hand-authored sub-composition can declare both the members
+  // and their `<hf-audio-group>`, and until sub-comp children inherited
+  // `audioGroup*` no group row existed for that case so nothing could reach
+  // here. Now the row appears, and routing its writes at `activeCompPath`
+  // means `readTagSnippetByTarget` finds nothing and every mute, fader move and
+  // FX preset throws "Unable to patch element in index.html". Every sibling
+  // timeline writer already routes `element.sourceFile || activeCompPath`.
+  const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
+  const targetPath = resolveGroupSourceFile(groupEl) || activeCompPath || "index.html";
   const patchTarget = buildPatchTarget({ domId: groupId });
   if (!patchTarget) return [];
 
@@ -72,8 +191,6 @@ async function setAudioGroupAttribute({
     domEditSaveTimestampRef,
     pendingTimelineEditPathRef,
     patchLive: (v) => patchLiveGroupAttribute(previewIframe, groupId, attr, v),
-    readLive: () =>
-      previewIframe?.contentDocument?.getElementById(groupId)?.getAttribute(attr) ?? null,
   });
 }
 
@@ -101,6 +218,10 @@ export function useSetAudioGroupAttribute({
   const setLive = useCallback(
     (groupId: string, attr: string, value: string | null) => {
       patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
+      // Live too, not just on commit: a fader drag is `setLive` per frame and
+      // `setQuiet` once on release, so without this the strip's own readout
+      // fights the drag.
+      syncStoredGroupAttribute(groupId, attr, value);
     },
     [previewIframeRef],
   );
@@ -126,7 +247,18 @@ export function useSetAudioGroupAttribute({
           domEditSaveTimestampRef,
           pendingTimelineEditPathRef,
         });
+        syncStoredGroupAttribute(groupId, attr, value);
       } catch (error) {
+        // `persistElementAttribute` leaves the live DOM at the previous value
+        // however it failed — it unwinds a failed save, and an unresolvable
+        // target now throws before patching at all. But `setLive` mirrored the
+        // in-progress value into the store on every drag frame — so without
+        // this the fader reads 0.4 while
+        // the preview and the file are both back at 1.0, and nothing re-parses
+        // to correct it (a live patch causing no parse is this mirror's whole
+        // premise). Re-mirror from the DOM, which is now authoritative again.
+        const live = previewIframeRef.current?.contentDocument?.getElementById(groupId);
+        syncStoredGroupAttribute(groupId, attr, live?.getAttribute(attr) ?? null);
         console.error("[Timeline] Failed to set group attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update group";
         showToast(message);

package/src/hooks/timelineEditingHelpers.test.ts

@@ -6,6 +6,7 @@ import {
   deleteSelectedKeyframes,
   extendRootDurationIfNeeded,
   patchIframeDomTiming,
+  persistElementAttribute,
   persistTimelineBatchEdit,
   type PersistTimelineBatchChange,
 } from "./timelineEditingHelpers";
@@ -423,3 +424,88 @@ describe("deleteSelectedKeyframes", () => {
     expect(handleGsapRemoveKeyframe.mock.calls[0]?.[1]).toBe(20);
   });
 });
+
+describe("persistElementAttribute", () => {
+  /**
+   * The optimistic live patch used to run BEFORE the target was resolved, and
+   * only the save was wrapped in the unwind. So an unresolvable target threw
+   * with the preview holding a value that never reached disk — and the group
+   * writer's catch mirrors the live DOM into the store, so the UI reported the
+   * write as applied until a reload dropped it.
+   */
+  it("does not patch the live DOM when the target resolves to nothing", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(
+        new Response(JSON.stringify({ content: '<body><audio id="other"></audio></body>' })),
+      );
+    const patchLive = vi.fn();
+    const writeProjectFile = vi.fn();
+
+    await expect(
+      persistElementAttribute({
+        projectId: "p",
+        targetPath: "index.html",
+        patchTarget: { id: "missing" },
+        attr: "data-volume",
+        value: "0.4",
+        label: "Set volume",
+        writeProjectFile,
+        recordEdit: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        pendingTimelineEditPathRef: { current: new Set() },
+        patchLive,
+      }),
+    ).rejects.toThrow("Unable to patch element in index.html");
+
+    expect(patchLive).not.toHaveBeenCalled();
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    fetchSpy.mockRestore();
+  });
+});
+
+describe("persistElementAttribute — unwind value", () => {
+  /**
+   * The unwind has to restore the value on DISK, not the one in the preview.
+   *
+   * Every live-write caller patches the DOM before committing (a fader drag is
+   * `setLive` per frame; hovering a preset auditions the whole chain), so by
+   * commit time the live DOM already holds the in-progress value. Reading it as
+   * `previousValue` made the unwind a no-op, and the group writer's catch —
+   * which deliberately re-mirrors the store off the live DOM — then mirrored the
+   * never-saved value: the panel agreed with the preview, and a reload dropped it.
+   */
+  it("restores the file's value, not the audition already in the live DOM", async () => {
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(
+        new Response(
+          JSON.stringify({ content: `<body><audio id="bgm" data-volume="0.25"></audio></body>` }),
+        ),
+      );
+    const patched: Array<string | null> = [];
+    const writeProjectFile = vi.fn(() => Promise.reject(new Error("save failed")));
+
+    await expect(
+      persistElementAttribute({
+        projectId: "p",
+        targetPath: "index.html",
+        patchTarget: { id: "bgm" },
+        attr: "data-volume",
+        value: "0.9",
+        label: "Set volume",
+        writeProjectFile,
+        recordEdit: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        pendingTimelineEditPathRef: { current: new Set() },
+        // The live DOM is ALREADY at the new value when the commit runs — that
+        // is what `setLive` does on every drag frame.
+        patchLive: (v) => patched.push(v),
+      }),
+    ).rejects.toThrow("save failed");
+
+    // First the optimistic write, then the unwind — back to what the FILE said.
+    expect(patched).toEqual(["0.9", "0.25"]);
+    fetchSpy.mockRestore();
+  });
+});

package/src/hooks/timelineEditingHelpers.ts

@@ -410,8 +410,6 @@ export interface PersistElementAttributeInput {
   pendingTimelineEditPathRef: { current: Set<string> };
   /** Write the attribute directly on the live preview DOM node. */
   patchLive: (value: string | null) => void;
-  /** Read the attribute's current value off the live preview DOM node. */
-  readLive: () => string | null;
 }
 
 /**
@@ -420,7 +418,7 @@ export interface PersistElementAttributeInput {
  * `setAudioGroupAttribute` (a group id addressed by its own DOM id) and
  * `useSetElementAttribute` (an arbitrary timeline clip) — same shape, only
  * how the live node is found and where the patch target resolves to differs,
- * which is exactly what `patchLive`/`readLive`/`patchTarget` parameterize.
+ * which is exactly what `patchLive`/`patchTarget` parameterize.
  */
 export async function persistElementAttribute({
   projectId,
@@ -434,15 +432,29 @@ export async function persistElementAttribute({
   domEditSaveTimestampRef,
   pendingTimelineEditPathRef,
   patchLive,
-  readLive,
 }: PersistElementAttributeInput): Promise<string[]> {
-  const previousValue = readLive();
-  patchLive(value);
-
+  // Resolve the target BEFORE patching the live DOM. The optimistic patch used
+  // to run first, and only the save was wrapped in the unwind — so an
+  // unresolvable target threw with the live preview (and, through the callers'
+  // catch, the store mirrored off it) holding a value that never reached disk.
+  // The write then read as successful until a reload dropped it.
   const before = await readFileContent(projectId, targetPath);
   if (readTagSnippetByTarget(before, patchTarget) === undefined) {
     throw new Error(`Unable to patch element in ${targetPath}`);
   }
+  // The unwind value comes from the FILE, not from `readLive()`.
+  //
+  // Every live-write caller patches the DOM before committing — a fader drag is
+  // `setLive` per frame, hovering a preset auditions the whole chain — so by the
+  // time this runs the live DOM already holds the in-progress value. Reading it
+  // here made `previousValue === value`, so the unwind below was a no-op, and
+  // `setQuiet`'s catch (which deliberately re-mirrors the store from the live
+  // DOM) then mirrored that same never-saved value. The group audibly had the
+  // preset, the panel agreed, and a reload dropped it — the failure class the
+  // target check above was added to close, still open on the live-write path.
+  const previousValue = readAttributeByTarget(before, patchTarget, attr) ?? null;
+  patchLive(value);
+
   const operation: PatchOperation = { type: "attribute", property: attr, value };
   const patched = applyPatchByTarget(before, patchTarget, operation);
 

package/src/hooks/timelineElementFxAttribute.ts

@@ -75,9 +75,6 @@ async function setElementAttribute({
     domEditSaveTimestampRef,
     pendingTimelineEditPathRef,
     patchLive: (v) => patchLiveElementAttribute(previewIframe, element, attr, v, activeCompPath),
-    readLive: () =>
-      findTimelineElementInIframe(previewIframe, element, activeCompPath)?.getAttribute(attr) ??
-      null,
   });
 }
 

package/src/hooks/timelineTrackVisibility.test.ts

@@ -2,11 +2,10 @@
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore, type TimelineElement } from "../player";
-import {
-  createAudioGroupAndAssignMembers,
-  toggleTimelineElementHidden,
-  toggleTimelineTrackHidden,
-} from "./timelineTrackVisibility";
+import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
+import { readTagSnippetByTarget } from "../utils/sourcePatcher";
+import { createAudioGroupAndAssignMembers } from "./timelineAudioGroupCreate";
+import { toggleTimelineElementHidden, toggleTimelineTrackHidden } from "./timelineTrackVisibility";
 
 afterEach(() => {
   document.body.innerHTML = "";
@@ -513,23 +512,106 @@ describe("createAudioGroupAndAssignMembers", () => {
     ).toBe("voiceover");
   });
 
-  it("does nothing for fewer than two elements — grouping is a plural concept", async () => {
-    const recordEdit = vi.fn();
-    const changedPaths = await createAudioGroupAndAssignMembers({
+  // The group element is what every LATER group write addresses — mute, the bus
+  // fader's data-volume, an FX preset all go through
+  // `buildPatchTarget({ domId: groupId })`. Membership alone parses, but leaves
+  // a group nothing can edit.
+  it("emits the group's own <hf-audio-group> element, patchable by its DOM id", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    if (iframe.contentDocument) {
+      iframe.contentDocument.body.innerHTML = `
+        <audio id="narration"></audio>
+        <audio id="interview-guest"></audio>
+      `;
+    }
+    const files = new Map([
+      [
+        "index.html",
+        `<html><body>
+<audio id="narration" data-start="0" data-duration="5"></audio>
+<audio id="interview-guest" data-start="10" data-duration="5"></audio>
+</body></html>`,
+      ],
+    ]);
+    stubProjectFiles(files);
+
+    const narration = element({ id: "narration", domId: "narration", track: 0 });
+    const guest = element({ id: "interview-guest", domId: "interview-guest", track: 1 });
+    usePlayerStore.getState().setElements([narration, guest]);
+
+    const writes = new Map<string, string>();
+    await createAudioGroupAndAssignMembers({
       projectId: "project-1",
       activeCompPath: "index.html",
-      elements: [element({ id: "narration", domId: "narration" })],
+      elements: [narration, guest],
       groupId: "voiceover",
-      previewIframe: null,
-      writeProjectFile: async () => {},
-      recordEdit,
+      previewIframe: iframe,
+      writeProjectFile: async (path, content) => {
+        writes.set(path, content);
+      },
+      recordEdit: vi.fn(),
       domEditSaveTimestampRef: { current: 0 },
       pendingTimelineEditPathRef: { current: new Set() },
     });
-    expect(changedPaths).toEqual([]);
+
+    const written = writes.get("index.html") ?? "";
+    expect(written).toContain('<hf-audio-group id="voiceover"></hf-audio-group>');
+    // The actual contract: the group-attribute writer can now find a target.
+    // This is the read that threw "Unable to patch element in index.html".
+    expect(readTagSnippetByTarget(written, { id: "voiceover" })).toBeDefined();
+    // ...and in the live preview, which is what patchLiveGroupAttribute reads
+    // before the next reload.
+    expect(iframe.contentDocument?.getElementById("voiceover")?.tagName.toLowerCase()).toBe(
+      "hf-audio-group",
+    );
+    // Both members still resolve into it.
+    expect(resolveAudioGroups(iframe.contentDocument as Document)[0]).toMatchObject({
+      id: "voiceover",
+      memberIds: ["narration", "interview-guest"],
+    });
+  });
+
+  // Rejects rather than resolving empty: the carve's auto-group persists
+  // `sources: [groupId]` once this resolves, so a silent no-op leaves the carve
+  // pointing at a group that was never written — and stops ducking.
+  it("rejects for fewer than two elements — grouping is a plural concept", async () => {
+    const recordEdit = vi.fn();
+    await expect(
+      createAudioGroupAndAssignMembers({
+        projectId: "project-1",
+        activeCompPath: "index.html",
+        elements: [element({ id: "narration", domId: "narration" })],
+        groupId: "voiceover",
+        previewIframe: null,
+        writeProjectFile: async () => {},
+        recordEdit,
+        domEditSaveTimestampRef: { current: 0 },
+        pendingTimelineEditPathRef: { current: new Set() },
+      }),
+    ).rejects.toThrow("a group needs at least two");
     expect(recordEdit).not.toHaveBeenCalled();
   });
 
+  it("rejects a group id that is not safe to interpolate into markup or a path", async () => {
+    await expect(
+      createAudioGroupAndAssignMembers({
+        projectId: "project-1",
+        activeCompPath: "index.html",
+        elements: [
+          element({ id: "narration", domId: "narration" }),
+          element({ id: "guest", domId: "guest" }),
+        ],
+        groupId: '../x"><script>',
+        previewIframe: null,
+        writeProjectFile: async () => {},
+        recordEdit: vi.fn(),
+        domEditSaveTimestampRef: { current: 0 },
+        pendingTimelineEditPathRef: { current: new Set() },
+      }),
+    ).rejects.toThrow("Invalid audio group id");
+  });
+
   it("reverts the optimistic live patch when the save fails", async () => {
     const iframe = document.createElement("iframe");
     document.body.append(iframe);