@hyperframes/studio 0.8.11 → 0.8.13

package/src/hooks/timelineTrackVisibility.ts

@@ -8,7 +8,6 @@ import {
 } from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { isAudioTimelineElement } from "../utils/timelineInspector";
-import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";
 import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
 import {
   applyPatchByTarget,
@@ -32,12 +31,8 @@ interface ToggleTimelineTrackHiddenInput {
   timelineElements: readonly TimelineElement[];
   track: number;
   hidden: boolean;
-  /**
-   * The display row the clicked control announced, when the caller has one.
-   * Absent (a keyboard path or a programmatic call), the row is derived here
-   * from ascending element-bearing keys — correct whenever no group has
-   * reordered the header.
-   */
+  /** The row the CLICKED control announced. Absent when the caller has no
+   *  rendered number to hand over, which falls back to deriving one. */
   displayNumber?: number | null;
   previewIframe: HTMLIFrameElement | null;
   writeProjectFile: (path: string, content: string) => Promise<void>;
@@ -110,7 +105,7 @@ function patchLiveHiddenState(
   }
 }
 
-function reseekPreviewRuntime(iframe: HTMLIFrameElement | null): void {
+export function reseekPreviewRuntime(iframe: HTMLIFrameElement | null): void {
   try {
     const win: (Window & { __player?: { seek?: (time: number) => void } }) | null =
       iframe?.contentWindow ?? null;
@@ -118,7 +113,7 @@ function reseekPreviewRuntime(iframe: HTMLIFrameElement | null): void {
   } catch {}
 }
 
-function groupElementsByTargetPath(
+export function groupElementsByTargetPath(
   elements: readonly TimelineElement[],
   activeCompPath: string | null,
 ): Map<string, TimelineElement[]> {
@@ -227,7 +222,8 @@ export async function toggleTimelineTrackHidden({
   // read by a human, so it gets the display row instead — the one the clicked
   // control announced, when the caller passed it. Deriving it again here would
   // use ascending element-bearing keys, which stop matching the header as soon
-  // as an audio group reorders the rows and inserts an anchor.
+  // as an audio group reorders the rows and inserts an anchor: the same click
+  // then said "Mute track 2" and recorded "Mute track 1".
   const suffix = trackDisplaySuffix(
     displayNumber ?? trackDisplayNumber(timelineTrackOrder(timelineElements), track),
   );
@@ -289,114 +285,6 @@ export async function toggleTimelineElementHidden({
   });
 }
 
-function patchLiveAudioGroupState(
-  iframe: HTMLIFrameElement | null,
-  elements: readonly TimelineElement[],
-  groupId: string | null,
-  activeCompPath: string | null,
-): void {
-  for (const element of elements) {
-    const target = findTimelineElementInIframe(iframe, element, activeCompPath);
-    if (!target) continue;
-    if (groupId) target.setAttribute(HF_AUDIO_GROUP_ATTR, groupId);
-    else target.removeAttribute(HF_AUDIO_GROUP_ATTR);
-  }
-}
-
-interface CreateAudioGroupAndAssignMembersInput {
-  projectId: string;
-  activeCompPath: string | null;
-  elements: readonly TimelineElement[];
-  groupId: 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. The group needs no `<hf-audio-group>`
- * element of its own to exist: `resolveAudioGroups` already degrades
- * gracefully to label = id when one is absent, and a naming dialog is out of
- * scope here — the id itself is the default name.
- */
-// fallow-ignore-next-line complexity
-export async function createAudioGroupAndAssignMembers({
-  projectId,
-  activeCompPath,
-  elements,
-  groupId,
-  previewIframe,
-  writeProjectFile,
-  recordEdit,
-  domEditSaveTimestampRef,
-  pendingTimelineEditPathRef,
-}: CreateAudioGroupAndAssignMembersInput): Promise<string[]> {
-  if (elements.length < 2) return [];
-
-  patchLiveAudioGroupState(previewIframe, elements, groupId, activeCompPath);
-  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);
-    }
-
-    domEditSaveTimestampRef.current = Date.now();
-    const changedPaths = await saveProjectFilesWithHistory({
-      projectId,
-      label: `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);
-    reseekPreviewRuntime(previewIframe);
-    throw error;
-  }
-}
-
 export function useTimelineTrackVisibilityEditing({
   projectIdRef,
   activeCompPath,
@@ -532,67 +420,3 @@ export function useTimelineElementVisibilityEditing({
     ],
   );
 }
-
-/**
- * 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,
-) => Promise<void> {
-  const expandedElements = useExpandedTimelineElements();
-  return useCallback(
-    async (clipIds: readonly string[], groupId: string) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) return;
-      const keys = new Set(clipIds);
-      const elements = expandedElements.filter((item) => keys.has(item.key ?? item.id));
-      try {
-        await createAudioGroupAndAssignMembers({
-          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);
-      }
-    },
-    [
-      activeCompPath,
-      expandedElements,
-      previewIframeRef,
-      writeProjectFile,
-      recordEdit,
-      domEditSaveTimestampRef,
-      pendingTimelineEditPathRef,
-      isRecordingRef,
-      showToast,
-      projectIdRef,
-    ],
-  );
-}

package/src/hooks/useAudioGroupCarveAssignment.test.tsx

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+
+/**
+ * The carve's auto-group write path, end to end from the ids its picker hands
+ * over. Both callers — the carve picker (`withAutoGroupedSources`) and the
+ * timeline's group-pointer button — name clips by DOM id, because that is the
+ * space `collectCarveCandidates` reads them out of and the space
+ * `resolveAudioGroups` reads them back in. Resolving against store keys here
+ * matched nothing, wrote nothing, threw nothing, and let the carve persist
+ * `sources: [<group>]` for a group that was never created — a carve silently
+ * not ducking.
+ */
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+  usePlayerStore.getState().reset();
+});
+
+const FILE = `<html><body>
+<audio id="voice-1" data-start="0" data-duration="5"></audio>
+<audio id="voice-2" data-start="5" data-duration="5"></audio>
+</body></html>`;
+
+function stubProjectFiles(files: Map<string, string>) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      const path = decodeURIComponent(url.slice(url.lastIndexOf("/") + 1));
+      const content = files.get(path);
+      return new Response(JSON.stringify({ content }), {
+        status: content === undefined ? 404 : 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }),
+  );
+}
+
+function audio(overrides: Partial<TimelineElement>): TimelineElement {
+  return {
+    id: overrides.domId ?? "clip",
+    // A store key that is NOT the DOM id — the shape every real row has.
+    key: `index.html#${overrides.domId ?? "clip"}`,
+    tag: "audio",
+    start: 0,
+    duration: 5,
+    track: 0,
+    ...overrides,
+  };
+}
+
+type Assign = (clipIds: readonly string[], groupId: string) => Promise<void>;
+
+function renderAssign(writeProjectFile: (path: string, content: string) => Promise<void>) {
+  const showToast = vi.fn();
+  // A holder, not a bare `let`: TS narrows a variable only assigned inside a
+  // component body to `never` at the call site.
+  const held: { assign: Assign | null } = { assign: null };
+  function Probe() {
+    held.assign = useAudioGroupCarveAssignment({
+      projectIdRef: { current: "project-1" },
+      activeCompPath: "index.html",
+      showToast,
+      writeProjectFile,
+      recordEdit: async () => {},
+      domEditSaveTimestampRef: { current: 0 },
+      pendingTimelineEditPathRef: { current: new Set() },
+      previewIframeRef: { current: null },
+    });
+    return null;
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => root.render(<Probe />));
+  const assign = held.assign;
+  expect(assign).not.toBeNull();
+  return { assign: assign as Assign, showToast, root };
+}
+
+describe("useAudioGroupCarveAssignment", () => {
+  it("resolves the picker's DOM ids and writes the group", async () => {
+    stubProjectFiles(new Map([["index.html", FILE]]));
+    usePlayerStore
+      .getState()
+      .setElements([audio({ domId: "voice-1" }), audio({ domId: "voice-2", track: 1 })]);
+
+    const writes = new Map<string, string>();
+    const { assign, showToast, root } = renderAssign(async (path, content) => {
+      writes.set(path, content);
+    });
+
+    await act(async () => {
+      await assign(["voice-1", "voice-2"], "voiceover");
+    });
+
+    const written = writes.get("index.html") ?? "";
+    expect(written).toContain(
+      'id="voice-1" data-start="0" data-duration="5" data-audio-group="voiceover"',
+    );
+    expect(written).toContain(
+      'id="voice-2" data-start="5" data-duration="5" data-audio-group="voiceover"',
+    );
+    expect(written).toContain('<hf-audio-group id="voiceover"></hf-audio-group>');
+    expect(showToast).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  // Loud AND rejecting: the carve chains `.then(() => ({...next, sources:
+  // [groupId]}))` off this promise, so a resolved-but-failed call let it
+  // persist a carve aimed at a group that was never written. Toasting alone
+  // was not enough — the promise has to carry the failure too.
+  it("rejects, and toasts, when an id resolves to no clip", async () => {
+    stubProjectFiles(new Map([["index.html", FILE]]));
+    usePlayerStore.getState().setElements([audio({ domId: "voice-1" })]);
+
+    const writes = new Map<string, string>();
+    const { assign, showToast, root } = renderAssign(async (path, content) => {
+      writes.set(path, content);
+    });
+
+    await act(async () => {
+      await expect(assign(["voice-1", "voice-gone"], "voiceover")).rejects.toThrow("voice-gone");
+    });
+
+    expect(writes.size).toBe(0);
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("voice-gone"));
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useBlockedTimelineEditToast.ts

@@ -0,0 +1,27 @@
+/**
+ * The "can't be moved from the timeline yet" toast, rate-limited.
+ *
+ * Its own hook so `useTimelineEditing.ts` stays under the studio's 600-line cap.
+ * The 1.5s gate matters: a blocked drag fires this per pointermove, and without
+ * it one gesture stacked dozens of identical toasts.
+ */
+
+import { useCallback, useRef } from "react";
+import type { TimelineElement } from "../player";
+
+const BLOCKED_TOAST_INTERVAL_MS = 1500;
+
+export function useBlockedTimelineEditToast(
+  showToast: (message: string, tone?: "info" | "error") => void,
+): (element: TimelineElement) => void {
+  const lastAtRef = useRef(0);
+  return useCallback(
+    (_element: TimelineElement) => {
+      const now = Date.now();
+      if (now - lastAtRef.current < BLOCKED_TOAST_INTERVAL_MS) return;
+      lastAtRef.current = now;
+      showToast("This clip can't be moved or resized from the timeline yet.", "info");
+    },
+    [showToast],
+  );
+}

package/src/hooks/useDomEditAttributeCommits.ts

@@ -9,6 +9,8 @@ import type { PersistDomEditOperations } from "./domEditCommitTypes";
 import { reportDomEditPersistFailure } from "./domEditPersistFailure";
 import { bumpDomEditCommitMapVersion, runDomEditCommit } from "./domEditCommitRunner";
 import { syncStoredAutomationFromPreview } from "../player/lib/automationStoreSync";
+import { HF_AUDIO_GROUP_ATTR, HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
+import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
 
 // ── Types ──
 
@@ -63,6 +65,17 @@ function setOrRemovePreviewAttribute(
   } else {
     el.setAttribute(fullAttr, value);
   }
+  // Every DOM-edit attribute write funnels through here, which is the only
+  // place that can catch a group edit made from the rack rather than from the
+  // group header — `openGroupFxRack` hands the `<hf-audio-group>` to the DOM
+  // editor, and that path never went near the timeline's own writers.
+  //
+  // The group element itself OR a member's membership attribute: writing
+  // `data-audio-group` onto an `<audio>` moves it between groups, which changes
+  // the answer just as much as editing the bus does.
+  if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG || fullAttr === HF_AUDIO_GROUP_ATTR) {
+    invalidateGroupInfoCache(el.ownerDocument);
+  }
 }
 
 function findPreviewAttributeElement(

package/src/hooks/useDomEditSession.test.tsx

@@ -58,6 +58,8 @@ const capturedOnReorderShadow: { fn: ((targets: string[]) => void) | undefined }
   fn: undefined,
 };
 const domEditSelectionRef: { current: DomEditSelection | null } = { current: null };
+const domEditGroupSelectionsRef: { current: DomEditSelection[] } = { current: [] };
+const groupSelectionSpy = vi.fn();
 const gsapCommitMutation = Object.assign(vi.fn(), { batch: vi.fn() });
 
 function createSessionParams(
@@ -131,7 +133,7 @@ vi.mock("./useDomSelection", () => ({
     domEditHoverSelection: null,
     activeGroupElement: null,
     domEditSelectionRef,
-    domEditGroupSelectionsRef: { current: [] },
+    domEditGroupSelectionsRef,
     setActiveGroupElement: vi.fn(),
     applyDomSelection: vi.fn(),
     clearDomSelection: vi.fn(),
@@ -190,7 +192,7 @@ vi.mock("./useGsapScriptCommits", () => ({
 }));
 vi.mock("./useGroupCommits", () => ({
   useGroupCommits: () => ({
-    groupSelection: vi.fn(),
+    groupSelection: (...args: unknown[]) => groupSelectionSpy(...args),
     ungroupSelection: vi.fn(),
   }),
 }));
@@ -407,3 +409,56 @@ describe("bulk segment ease commits", () => {
     }
   });
 });
+
+// ── Grouping refuses audio ───────────────────────────────────────────────────
+//
+// A layout group is a positioned wrapper: it takes the members' bounding box,
+// rebases each child's left/top against it and adopts the topmost z-index. An
+// <audio> clip has no box — offsetWidth/Height are 0 — so this produced a 0x0
+// div with inline left/top on elements that are never laid out. Enforced here
+// rather than only by hiding the button, because the G shortcut routes through
+// the same handler and no hidden button can gate a keystroke.
+
+describe("handleGroupSelection with audio in the selection", () => {
+  const sel = (tag: string): DomEditSelection =>
+    ({
+      id: tag,
+      element: document.createElement(tag),
+      sourceFile: "index.html",
+    }) as unknown as DomEditSelection;
+
+  async function group(members: DomEditSelection[]) {
+    const { useDomEditSession } = await import("./useDomEditSession");
+    groupSelectionSpy.mockClear();
+    domEditGroupSelectionsRef.current = members;
+    const showToast = vi.fn();
+    const captured: { fn?: () => void } = {};
+    function Probe() {
+      captured.fn = useDomEditSession(createSessionParams({ showToast })).handleGroupSelection;
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(<Probe />));
+    act(() => captured.fn?.());
+    act(() => root.unmount());
+    domEditGroupSelectionsRef.current = [];
+    return { showToast };
+  }
+
+  it("refuses a selection of audio clips, and says where grouping audio lives", async () => {
+    const { showToast } = await group([sel("audio"), sel("audio")]);
+    expect(groupSelectionSpy).not.toHaveBeenCalled();
+    expect(String(showToast.mock.calls[0]?.[0])).toContain("bus");
+  });
+
+  it("refuses a mixed selection, since the wrapper would take the audio in too", async () => {
+    const { showToast } = await group([sel("div"), sel("audio")]);
+    expect(groupSelectionSpy).not.toHaveBeenCalled();
+    expect(String(showToast.mock.calls[0]?.[0])).toContain("layout");
+  });
+
+  it("still groups a selection of layout elements", async () => {
+    await group([sel("div"), sel("span")]);
+    expect(groupSelectionSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useDomEditSession.ts

@@ -1,8 +1,8 @@
 import { useCallback } from "react";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { isAudioDomElement } from "../utils/timelineInspector";
 import type { SelectElementOptions, TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
-import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
 import type { PatchTarget } from "../utils/sourcePatcher";
 import type { SidebarTab } from "../components/sidebar/LeftSidebar";
@@ -21,13 +21,11 @@ import { useGsapAwareEditing } from "./useGsapAwareEditing";
 import { useStudioSelectionPublisher } from "./useStudioSelectionPublisher";
 import { useKeyframeEaseCommits } from "./useKeyframeEaseCommits";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-
-interface RecordEditInput {
-  label: string;
-  kind: EditHistoryKind;
-  coalesceKey?: string;
-  files: Record<string, { before: string; after: string }>;
-}
+import { membersForDelete } from "./domEditDeleteMembers";
+import type { RecordEditInput } from "./domEditDeleteMembers";
+// Re-exported: the delete rule lives in its own module now, and callers (and its
+// own test) have always imported it from here.
+export { membersForDelete };
 
 export interface UseDomEditSessionParams {
   projectId: string | null;
@@ -73,22 +71,6 @@ export interface UseDomEditSessionParams {
   forceReloadSdkSession?: () => void;
 }
 
-/**
- * Which elements a delete acts on. `expandGroup` widens the primary to the
- * whole marquee group, which is what the Delete key means.
- *
- * The caller chooses rather than the delete deciding for everyone: Cut copies
- * the primary alone, so expanding for it put one element on the clipboard and
- * removed every other member of the group with it.
- */
-export function membersForDelete(
-  selection: DomEditSelection,
-  group: DomEditSelection[],
-  options?: { expandGroup?: boolean },
-): DomEditSelection[] {
-  return options?.expandGroup && group.length > 0 ? group : [selection];
-}
-
 export function useDomEditSession({
   projectId,
   activeCompPath,
@@ -374,6 +356,23 @@ export function useDomEditSession({
       showToast("Select at least 2 elements to group", "info");
       return;
     }
+    // A layout group is a positioned wrapper: it takes the members' bounding
+    // box, rebases each child's left/top against it, and adopts the topmost
+    // z-index. An <audio> clip has no box — offsetWidth/Height are 0 — so
+    // grouping audio produced a 0x0 div with inline left/top written onto
+    // elements that have never been laid out, and the timeline gained a
+    // wrapper standing for nothing audible. The audio answer to "these clips
+    // belong together" is an <hf-audio-group> bus, which the timeline's own FX
+    // pointer creates, so the refusal names it rather than just declining.
+    if (members.some((m) => isAudioDomElement(m.element))) {
+      showToast(
+        members.every((m) => isAudioDomElement(m.element))
+          ? "Audio clips group into a bus — use FX on the track header"
+          : "Can't group audio clips with layout elements",
+        "info",
+      );
+      return;
+    }
     trackStudioEvent("group", { action: "create", count: members.length });
     void groupSelection(members);
   }, [domEditGroupSelectionsRef, domEditSelectionRef, groupSelection, showToast]);