@hyperframes/studio 0.8.10 → 0.8.12

package/src/hooks/timelineAudioGroupCreate.ts

@@ -0,0 +1,345 @@
+/**
+ * Creating an audio group: the member sweep, the group element, and the
+ * carve's auto-group write-back.
+ *
+ * Split out of `timelineTrackVisibility.ts`, which owns the hidden/mute writes
+ * these mirror and had reached the 600-line studio ceiling.
+ */
+
+import { useCallback } from "react";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { useExpandedTimelineElements } from "../player/hooks/useExpandedTimelineElements";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { HF_AUDIO_GROUP_ATTR, HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
+import { runtimeAudioId } from "../player/lib/timelineElementHelpers";
+import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
+import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
+import {
+  applyPatchByTarget,
+  buildPatchTarget,
+  findTimelineElementInIframe,
+  readFileContent,
+  type RecordEditInput,
+} from "./timelineEditingHelpers";
+import {
+  groupElementsByTargetPath,
+  reseekPreviewRuntime,
+  type MutableRef,
+  type UseTimelineElementVisibilityEditingInput,
+} from "./timelineTrackVisibility";
+
+/**
+ * Assign (or restore) `data-audio-group` across a set of members.
+ *
+ * `restore` carries each member's PRIOR value so the unwind can put back a
+ * membership that already existed, rather than removing the attribute outright.
+ * `setElementsHidden`, which this mirrors, gets away with a plain `!hidden`
+ * because hidden is boolean; group membership is an arbitrary id, and the carve
+ * path does not check whether a clip is already grouped — so a failed save
+ * could silently un-group clips that belonged to another group before it.
+ */
+function patchLiveAudioGroupState(
+  iframe: HTMLIFrameElement | null,
+  elements: readonly TimelineElement[],
+  groupId: string | null,
+  activeCompPath: string | null,
+  restore?: ReadonlyMap<TimelineElement, string | null>,
+): void {
+  for (const element of elements) {
+    const target = findTimelineElementInIframe(iframe, element, activeCompPath);
+    if (!target) continue;
+    const next = restore ? (restore.get(element) ?? null) : groupId;
+    if (next) target.setAttribute(HF_AUDIO_GROUP_ATTR, next);
+    else target.removeAttribute(HF_AUDIO_GROUP_ATTR);
+  }
+  invalidateGroupInfoCache(iframe?.contentDocument);
+}
+
+/** Each member's `data-audio-group` before this write, for the unwind. */
+function captureAudioGroupState(
+  iframe: HTMLIFrameElement | null,
+  elements: readonly TimelineElement[],
+  activeCompPath: string | null,
+): Map<TimelineElement, string | null> {
+  const prior = new Map<TimelineElement, string | null>();
+  for (const element of elements) {
+    const target = findTimelineElementInIframe(iframe, element, activeCompPath);
+    prior.set(element, target?.getAttribute(HF_AUDIO_GROUP_ATTR) ?? null);
+  }
+  return prior;
+}
+
+/** Group ids are interpolated into markup and into a render-side filename, so
+ *  they stay in the character set an HTML id and a path can both carry. */
+const GROUP_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * The group's own `<hf-audio-group>` element, appended before `</body>` when it
+ * is not already in the file.
+ *
+ * Membership alone is enough for `resolveAudioGroups` to see the group, but
+ * every group-level WRITE — mute, the bus fader's `data-volume`, an FX preset —
+ * addresses the group by its DOM id (`setAudioGroupAttribute` →
+ * `buildPatchTarget({ domId: groupId })`), so without an element of its own a
+ * group is created and then cannot be edited at all.
+ *
+ * Written to the active composition file rather than beside the members, which
+ * can live in a sub-composition: that is the file the group's later writes
+ * target, and `resolveAudioGroups` reads the flattened document, so co-location
+ * buys nothing.
+ */
+/** Attribute-safe, for a name the author typed. */
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+function insertGroupElement(html: string, groupId: string, label?: string): string {
+  const existing = readTagSnippetByTarget(html, { id: groupId });
+  if (existing !== undefined) {
+    // Only OUR tag counts as "already there". The id was minted against the
+    // live preview document, which does not contain markup that is on disk but
+    // not rendered (inside a `<template>`, or an unloaded sub-composition) — so
+    // an unrelated element can already own it. Writing nothing there would aim
+    // every later group write (`buildPatchTarget({ domId })`) at that element,
+    // stamping data-volume / data-hidden / data-fx-chain onto it.
+    if (new RegExp(`^<\\s*${HF_AUDIO_GROUP_TAG}\\b`, "i").test(existing)) return html;
+    throw new Error(`Cannot create audio group: id ${groupId} is already used in this file`);
+  }
+  // The author's name for the group, from the naming dialog (groups doc §5).
+  // Without it the timeline falls back to the minted id, which is the one thing
+  // the dialog exists to stop an author having to read.
+  const labelAttr = label ? ` data-label="${escapeAttr(label)}"` : "";
+  const tag = `<${HF_AUDIO_GROUP_TAG} id="${groupId}"${labelAttr}></${HF_AUDIO_GROUP_TAG}>`;
+  const closeBody = html.lastIndexOf("</body>");
+  if (closeBody < 0) return `${html}\n${tag}\n`;
+  return `${html.slice(0, closeBody)}  ${tag}\n  ${html.slice(closeBody)}`;
+}
+
+/** The same element in the live preview, so the group is editable before the
+ *  next reload. Returns true when it created one (only then may the unwind
+ *  remove it — a pre-existing group element is not ours to delete). */
+function patchLiveGroupElement(
+  iframe: HTMLIFrameElement | null,
+  groupId: string,
+  label?: string,
+): boolean {
+  const doc = iframe?.contentDocument;
+  if (!doc?.body || doc.getElementById(groupId)) return false;
+  const el = doc.createElement(HF_AUDIO_GROUP_TAG);
+  el.id = groupId;
+  if (label) el.setAttribute("data-label", label);
+  doc.body.appendChild(el);
+  invalidateGroupInfoCache(doc);
+  return true;
+}
+
+interface CreateAudioGroupAndAssignMembersInput {
+  projectId: string;
+  activeCompPath: string | null;
+  elements: readonly TimelineElement[];
+  groupId: string;
+  /** The author's name for it, from the naming dialog (groups doc §5). */
+  groupLabel?: string;
+  previewIframe: HTMLIFrameElement | null;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRef<number>;
+  pendingTimelineEditPathRef: MutableRef<Set<string>>;
+}
+
+/**
+ * Group two or more voice clips: write `data-audio-group="<groupId>"` on
+ * every one of them, atomically, one undo entry — the same multi-target shape
+ * `setElementsHidden` uses for mute — plus the group's own `<hf-audio-group>`
+ * element, which every later group-level write addresses by DOM id. No naming
+ * dialog: the id is the default name, the way `resolveAudioGroups` reads it.
+ */
+// fallow-ignore-next-line complexity
+export async function createAudioGroupAndAssignMembers({
+  projectId,
+  activeCompPath,
+  elements,
+  groupId,
+  groupLabel,
+  previewIframe,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  pendingTimelineEditPathRef,
+}: CreateAudioGroupAndAssignMembersInput): Promise<string[]> {
+  // Throws rather than returning empty: the carve's auto-group awaits this and
+  // then persists `sources: [groupId]` on success, so a quiet no-op leaves the
+  // carve aimed at a group that does not exist.
+  if (elements.length < 2) {
+    throw new Error(`Cannot group ${elements.length} clip(s) — a group needs at least two`);
+  }
+  if (!GROUP_ID_PATTERN.test(groupId)) {
+    throw new Error(`Invalid audio group id ${JSON.stringify(groupId)}`);
+  }
+
+  const priorGroups = captureAudioGroupState(previewIframe, elements, activeCompPath);
+  patchLiveAudioGroupState(previewIframe, elements, groupId, activeCompPath);
+  const createdLiveGroupElement = patchLiveGroupElement(previewIframe, groupId, groupLabel);
+  reseekPreviewRuntime(previewIframe);
+
+  const groupOperation: PatchOperation = {
+    type: "attribute",
+    property: HF_AUDIO_GROUP_ATTR,
+    value: groupId,
+  };
+  const originalByPath = new Map<string, string>();
+  const files: Record<string, string> = {};
+
+  try {
+    for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
+      let patchedContent = await readFileContent(projectId, targetPath);
+      originalByPath.set(targetPath, patchedContent);
+
+      for (const element of fileElements) {
+        const patchTarget = buildPatchTarget(element);
+        if (!patchTarget) {
+          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
+        }
+        if (readTagSnippetByTarget(patchedContent, patchTarget) === undefined) {
+          throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
+        }
+        patchedContent = applyPatchByTarget(patchedContent, patchTarget, groupOperation);
+      }
+
+      files[targetPath] = patchedContent;
+      pendingTimelineEditPathRef.current.add(targetPath);
+    }
+
+    const groupPath = activeCompPath || "index.html";
+    let groupContent = files[groupPath];
+    if (groupContent === undefined) {
+      groupContent = await readFileContent(projectId, groupPath);
+      originalByPath.set(groupPath, groupContent);
+    }
+    const withGroupElement = insertGroupElement(groupContent, groupId, groupLabel);
+    if (withGroupElement !== groupContent) {
+      files[groupPath] = withGroupElement;
+      pendingTimelineEditPathRef.current.add(groupPath);
+    }
+
+    domEditSaveTimestampRef.current = Date.now();
+    const changedPaths = await saveProjectFilesWithHistory({
+      projectId,
+      label: groupLabel
+        ? `Group ${elements.length} clips as ${groupLabel}`
+        : `Group ${elements.length} voice clips`,
+      kind: "timeline",
+      files,
+      readFile: async (path) => {
+        const original = originalByPath.get(path);
+        if (original !== undefined) return original;
+        return readFileContent(projectId, path);
+      },
+      writeFile: writeProjectFile,
+      recordEdit,
+    });
+    domEditSaveTimestampRef.current = Date.now();
+    for (const element of elements) {
+      usePlayerStore.getState().updateElement(element.key ?? element.id, { audioGroup: groupId });
+    }
+    return changedPaths;
+  } catch (error) {
+    // Mirrors setElementsHidden's failure path: the optimistic live patch
+    // already ran, so a save failure has to be unwound or the preview shows a
+    // grouping that never made it to disk.
+    patchLiveAudioGroupState(previewIframe, elements, null, activeCompPath, priorGroups);
+    if (createdLiveGroupElement) {
+      previewIframe?.contentDocument?.getElementById(groupId)?.remove();
+    }
+    reseekPreviewRuntime(previewIframe);
+    throw error;
+  }
+}
+
+/**
+ * The write behind B6's auto-group: pick two or more voice clips in the carve
+ * picker and they land in a group instead of naming each other by id. Same
+ * expanded-rows resolution as element-visibility, for the same reason — a
+ * nested sub-composition child has no entry in the raw store list.
+ */
+export function useAudioGroupCarveAssignment({
+  projectIdRef,
+  activeCompPath,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  previewIframeRef,
+  pendingTimelineEditPathRef,
+  isRecordingRef,
+}: UseTimelineElementVisibilityEditingInput): (
+  clipIds: readonly string[],
+  groupId: string,
+  groupLabel?: string,
+) => Promise<void> {
+  const expandedElements = useExpandedTimelineElements();
+  return useCallback(
+    async (clipIds: readonly string[], groupId: string, groupLabel?: string) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      // DOM ids, not store keys: both callers (the carve picker and the
+      // timeline's group-pointer button) name clips the way the document does,
+      // because that is the only space `resolveAudioGroups` reads back.
+      const wanted = new Set(clipIds);
+      const elements = expandedElements.filter((item) => {
+        const domId = runtimeAudioId(item);
+        return domId !== null && wanted.has(domId);
+      });
+      try {
+        // Loud, not silent: an unresolved id used to leave `elements` short,
+        // `createAudioGroupAndAssignMembers` returning early with no write, and
+        // the carve still persisting `sources: [groupId]` for a group that was
+        // never created — a carve pointing at nothing, silently not ducking.
+        if (elements.length !== wanted.size) {
+          const missing = [...wanted].filter(
+            (id) => !elements.some((item) => runtimeAudioId(item) === id),
+          );
+          throw new Error(`Cannot group: no timeline clip for ${missing.join(", ")}`);
+        }
+        await createAudioGroupAndAssignMembers({
+          groupLabel,
+          projectId: pid,
+          activeCompPath,
+          elements,
+          groupId,
+          previewIframe: previewIframeRef.current,
+          writeProjectFile,
+          recordEdit,
+          domEditSaveTimestampRef,
+          pendingTimelineEditPathRef,
+        });
+      } catch (error) {
+        console.error("[Timeline] Failed to group voice clips", error);
+        const message = error instanceof Error ? error.message : "Failed to group voice clips";
+        showToast(message);
+        // Rethrown, not just reported: the carve's auto-group chains
+        // `.then(() => ({ ...next, sources: [groupId] }))` off this promise, so
+        // swallowing here let it persist a carve pointing at a group that was
+        // never written — the exact silent no-op the throw inside
+        // `createAudioGroupAndAssignMembers` exists to prevent.
+        throw error;
+      }
+    },
+    [
+      activeCompPath,
+      expandedElements,
+      previewIframeRef,
+      writeProjectFile,
+      recordEdit,
+      domEditSaveTimestampRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+      showToast,
+      projectIdRef,
+    ],
+  );
+}

package/src/hooks/timelineAudioGroupVolume.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment jsdom
+
+/**
+ * A group write has to reach the STORE, not just the file and the live DOM.
+ *
+ * The timeline derives a group row's label, fader, mute and chain from the
+ * `audioGroup*` fields mirrored onto its members — so a write that lands
+ * everywhere except there leaves the header rendering whatever it parsed at
+ * load. Observed in the studio: muting a group wrote `data-hidden` to disk and
+ * to the preview, and the button stayed "Mute group Voiceover", re-writing the
+ * same attribute on every click with no way to unmute.
+ *
+ * Invalidating the parse cache is necessary but not sufficient — it only makes
+ * the NEXT parse honest, and a live attribute patch never triggers one.
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { resolveGroupSourceFile, useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+});
+
+function member(domId: string, track: number): TimelineElement {
+  return {
+    id: domId,
+    key: `index.html#${domId}`,
+    domId,
+    tag: "audio",
+    start: 0,
+    duration: 5,
+    track,
+    audioGroup: "voiceover",
+    audioGroupHidden: false,
+    audioGroupVolume: 1,
+  };
+}
+
+/** The hook without React — it only closes over refs and callbacks. */
+function makeSetter() {
+  const input = {
+    projectIdRef: { current: "project-1" },
+    activeCompPath: "index.html",
+    showToast: () => {},
+    writeProjectFile: async () => {},
+    recordEdit: async () => {},
+    domEditSaveTimestampRef: { current: 0 },
+    pendingTimelineEditPathRef: { current: new Set<string>() },
+    previewIframeRef: { current: null },
+  };
+  // `setLive` takes no async path and touches only the preview DOM + store, so
+  // it can be exercised directly; `setQuiet` additionally persists, which this
+  // test deliberately does not cover (that is timelineTrackVisibility's job).
+  let setter: ReturnType<typeof useSetAudioGroupAttribute> | null = null;
+  const Probe = () => {
+    setter = useSetAudioGroupAttribute(input as never);
+    return null;
+  };
+  // Minimal hook harness: call the component function directly. It uses only
+  // useCallback, which React allows outside a renderer when the result is used
+  // immediately and never re-rendered.
+  return { Probe, get: () => setter };
+}
+
+describe("group attribute writes reach the store", () => {
+  it("mirrors data-hidden onto every member so the header can flip", async () => {
+    const react = await import("react");
+    const { renderToStaticMarkup } = await import("react-dom/server");
+    const harness = makeSetter();
+    renderToStaticMarkup(react.createElement(harness.Probe));
+    const setter = harness.get();
+    expect(setter).not.toBeNull();
+
+    usePlayerStore.getState().setElements([member("voice-1", 0), member("voice-2", 1)]);
+
+    setter?.setLive("voiceover", "data-hidden", "");
+    expect(usePlayerStore.getState().elements.every((el) => el.audioGroupHidden === true)).toBe(
+      true,
+    );
+
+    setter?.setLive("voiceover", "data-hidden", null);
+    expect(usePlayerStore.getState().elements.every((el) => el.audioGroupHidden === false)).toBe(
+      true,
+    );
+  });
+
+  // `Number(null)` and `Number("")` are both 0 AND finite, so the obvious
+  // isFinite check mirrored "silent" for a removed attribute while core's
+  // `readAudioGroupVolume` reads the same absence as unity — a parse divergence
+  // inside the mirror whose entire job is to prevent one.
+  it("reads a removed data-volume as unity, the way core does", async () => {
+    const react = await import("react");
+    const { renderToStaticMarkup } = await import("react-dom/server");
+    const harness = makeSetter();
+    renderToStaticMarkup(react.createElement(harness.Probe));
+    const setter = harness.get();
+
+    usePlayerStore.getState().setElements([member("voice-1", 0)]);
+
+    setter?.setLive("voiceover", "data-volume", "0.3");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBeCloseTo(0.3, 6);
+
+    setter?.setLive("voiceover", "data-volume", null);
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(1);
+
+    setter?.setLive("voiceover", "data-volume", "");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(1);
+
+    setter?.setLive("voiceover", "data-volume", "nonsense");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(1);
+  });
+
+  it("mirrors data-volume, and leaves other groups alone", async () => {
+    const react = await import("react");
+    const { renderToStaticMarkup } = await import("react-dom/server");
+    const harness = makeSetter();
+    renderToStaticMarkup(react.createElement(harness.Probe));
+    const setter = harness.get();
+
+    const other: TimelineElement = { ...member("sfx", 2), audioGroup: "effects" };
+    usePlayerStore.getState().setElements([member("voice-1", 0), other]);
+
+    setter?.setLive("voiceover", "data-volume", "0.4");
+
+    const byId = new Map(usePlayerStore.getState().elements.map((el) => [el.id, el]));
+    expect(byId.get("voice-1")?.audioGroupVolume).toBeCloseTo(0.4, 6);
+    expect(byId.get("sfx")?.audioGroupVolume).toBe(1);
+  });
+});
+
+/**
+ * The ancestor shape here is COPIED FROM A LIVE PREVIEW, not imagined.
+ *
+ * The first attempt at this fix used `getTimelineElementSourceFile` and a
+ * fixture in which the sub-composition root carried `data-composition-file`.
+ * The test passed; the studio still threw "Unable to patch element in
+ * index.html", because the runtime inlines a sub-comp as its own root element
+ * that carries only the composition ID — the FILE is on the host above it.
+ */
+describe("the mirror reaches sub-composition members", () => {
+  /**
+   * A group declared inside a sub-composition has no FLAT member to mirror onto
+   * — `childGroupState` keeps those members out of `elements` — so mirroring
+   * only `elements` made this whole function a no-op for it: the header kept the
+   * pre-write chain and `laneCount` stayed 0, so the lane disclosure never
+   * appeared for automation that now existed.
+   */
+  it("mirrors a group write onto DomClipChild members as well as flat ones", async () => {
+    const react = await import("react");
+    const { renderToStaticMarkup } = await import("react-dom/server");
+    const harness = makeSetter();
+    renderToStaticMarkup(react.createElement(harness.Probe));
+    const setter = harness.get();
+    usePlayerStore.getState().setElements([member("flat-1", 0)]);
+    usePlayerStore.getState().setDomClipChildren([
+      { id: "sub-1", parentId: "host", hostId: "host", label: "Sub 1", audioGroup: "voiceover" },
+      { id: "other", parentId: "host", hostId: "host", label: "Other", audioGroup: "sfx" },
+    ]);
+
+    setter?.setLive("voiceover", "data-label", "Voices");
+
+    const children = usePlayerStore.getState().domClipChildren;
+    expect(children.find((c) => c.id === "sub-1")?.audioGroupLabel).toBe("Voices");
+    // A member of another group is untouched.
+    expect(children.find((c) => c.id === "other")?.audioGroupLabel).toBeUndefined();
+  });
+});
+
+describe("resolveGroupSourceFile", () => {
+  function livePreviewShape(): Document {
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.setAttribute("data-composition-id", "subcomp-group-qa");
+    doc.body.innerHTML = `
+      <div id="voices-host" data-composition-id="voices-host" data-composition-file="compositions/voices.html">
+        <section id="voices-root" data-composition-id="voices">
+          <hf-audio-group id="voiceover"></hf-audio-group>
+        </section>
+      </div>
+      <hf-audio-group id="root-group"></hf-audio-group>
+    `;
+    return doc;
+  }
+
+  it("climbs past the sub-comp root to the host that names the file", () => {
+    const doc = livePreviewShape();
+    expect(resolveGroupSourceFile(doc.getElementById("voiceover"))).toBe(
+      "compositions/voices.html",
+    );
+  });
+
+  // A group in the root composition: body names an id but no file, so the
+  // caller falls back to activeCompPath. Returning body's id here would route
+  // every root-composition group write at a path that does not exist.
+  it("returns undefined for a group in the root composition", () => {
+    const doc = livePreviewShape();
+    expect(resolveGroupSourceFile(doc.getElementById("root-group"))).toBeUndefined();
+  });
+
+  it("is safe on a detached or missing element", () => {
+    expect(resolveGroupSourceFile(null)).toBeUndefined();
+    expect(resolveGroupSourceFile(document.createElement("hf-audio-group"))).toBeUndefined();
+  });
+});