@hyperframes/studio 0.8.108 → 0.8.110

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

@@ -0,0 +1,334 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import {
+  canDetachAudio,
+  canLinkPair,
+  detachAudioInSource,
+  linkInSource,
+  findMergePair,
+  mergeAudioInSource,
+  pickDetachedAudioTrack,
+  removeElementInSource,
+  setLinkInSource,
+  sharesSourceFile,
+} from "./mediaLinkEdits";
+
+const automation = JSON.stringify({
+  version: 1,
+  lanes: [
+    { target: "volume", points: [{ t: 0, v: 1 }] },
+    { target: "rate", points: [{ t: 0, v: 2 }] },
+  ],
+}).replaceAll('"', """);
+
+const VIDEO_TAG =
+  '<video id="talk" class="clip" src="assets/talk.mp4" data-start="2" data-duration="6" data-media-start="1" data-playback-rate="1" data-track-index="0" data-has-audio="true" data-volume="0.5" data-fade-in="0.3" data-fade-out="0.2" data-fx-chain="eq" data-fx-carve="carve" data-audio-group="voiceover" data-automation="' +
+  automation +
+  '"></video>';
+
+const SOURCE = [
+  '<div data-composition-id="main" data-duration="10">',
+  `  ${VIDEO_TAG}`,
+  '  <audio id="music" class="clip" src="assets/bgm.mp3" data-start="0" data-duration="10" data-track-index="1"></audio>',
+  "</div>",
+].join("\n");
+
+const video = { id: "talk" };
+
+function attrsOf(source: string, selector: string): Record<string, string> {
+  const el = new DOMParser().parseFromString(source, "text/html").querySelector(selector);
+  if (!el) throw new Error(`missing ${selector}`);
+  return Object.fromEntries(Array.from(el.attributes, (a) => [a.name, a.value]));
+}
+
+describe("detachAudioInSource", () => {
+  const result = detachAudioInSource(SOURCE, { target: video, videoId: "talk", track: 2 });
+
+  it("inserts a linked audio with the video's file, window and sound", () => {
+    expect(result).not.toBeNull();
+    const audio = attrsOf(result?.html ?? "", "audio#talk-audio");
+    expect(audio).toMatchObject({
+      src: "assets/talk.mp4",
+      "data-start": "2",
+      "data-duration": "6",
+      "data-media-start": "1",
+      "data-playback-rate": "1",
+      "data-track-index": "2",
+      "data-link": result?.linkId,
+      "data-sync-origin": result?.linkId,
+      "data-volume": "0.5",
+      "data-fade-in": "0.3",
+      "data-fade-out": "0.2",
+      "data-fx-chain": "eq",
+      "data-fx-carve": "carve",
+      "data-audio-group": "voiceover",
+    });
+    expect(audio["data-automation"]).toContain("volume");
+  });
+
+  it("mutes the video, strips its sound attributes and links it", () => {
+    const after = attrsOf(result?.html ?? "", "video#talk");
+    expect(after).toHaveProperty("muted");
+    expect(after["data-link"]).toBe(result?.linkId);
+    expect(after["data-sync-origin"]).toBe(result?.linkId);
+    for (const gone of [
+      "data-has-audio",
+      "data-volume",
+      "data-fade-in",
+      "data-fade-out",
+      "data-fx-chain",
+      "data-fx-carve",
+      "data-audio-group",
+    ]) {
+      expect(after).not.toHaveProperty(gone);
+    }
+    expect(after["data-automation"]).toContain("rate");
+    expect(after["data-automation"]).not.toContain("volume");
+  });
+
+  it("suffixes the audio id when taken", () => {
+    const taken = SOURCE.replace('id="music"', 'id="talk-audio"');
+    expect(detachAudioInSource(taken, { target: video, videoId: "talk", track: 2 })?.audioId).toBe(
+      "talk-audio-2",
+    );
+  });
+});
+
+describe("mergeAudioInSource", () => {
+  it("round-trips detach back to the original attributes", () => {
+    const detached = detachAudioInSource(SOURCE, { target: video, videoId: "talk", track: 2 });
+    const merged = mergeAudioInSource(detached?.html ?? "", {
+      videoTarget: video,
+      audioTarget: { id: "talk-audio" },
+    });
+    const original = attrsOf(SOURCE, "video#talk");
+    const roundTrip = attrsOf(merged ?? "", "video#talk");
+    const lanes = (raw: string | undefined) =>
+      JSON.parse(raw ?? "{}").lanes.map((lane: { target: string }) => lane.target);
+    expect(lanes(roundTrip["data-automation"]).sort()).toEqual(
+      lanes(original["data-automation"]).sort(),
+    );
+    delete original["data-automation"];
+    delete roundTrip["data-automation"];
+    expect(roundTrip).toEqual(original);
+    expect(merged).not.toContain('<audio id="talk-audio"');
+    expect(merged).toContain('id="music"');
+  });
+
+  it("converts a legacy a-roll + a-roll-audio pair into one video", () => {
+    const legacy = [
+      "<div>",
+      '  <video id="a-roll" src="a.mp4" muted data-start="0" data-duration="4"></video>',
+      '  <audio id="a-roll-audio" src="a.mp4" data-start="0" data-duration="4" data-volume="0.8"></audio>',
+      "</div>",
+    ].join("\n");
+    const merged = mergeAudioInSource(legacy, {
+      videoTarget: { id: "a-roll" },
+      audioTarget: { id: "a-roll-audio" },
+    });
+    expect(merged).toBe(
+      [
+        "<div>",
+        '  <video id="a-roll" src="a.mp4" data-start="0" data-duration="4" data-volume="0.8" data-has-audio="true"></video>',
+        "</div>",
+      ].join("\n"),
+    );
+  });
+});
+
+describe("mergeAudioInSource refusals", () => {
+  const pair = (videoAttrs: string, audioAttrs: string) =>
+    [
+      "<div>",
+      `  <video id="v" src="assets/one/talk.mp4" muted data-start="0" data-duration="4"${videoAttrs}></video>`,
+      `  <audio id="a" src="assets/one/talk.mp4" data-start="0" data-duration="4"${audioAttrs}></audio>`,
+      "</div>",
+    ].join("\n");
+  const merge = (source: string) =>
+    mergeAudioInSource(source, { videoTarget: { id: "v" }, audioTarget: { id: "a" } });
+
+  it("refuses an audio of a different file with the same name", () => {
+    expect(
+      merge(
+        pair("", "").replace('<audio id="a" src="assets/one/', '<audio id="a" src="assets/two/'),
+      ),
+    ).toBeNull();
+  });
+
+  it("refuses when only one member is hidden, which would change what is heard", () => {
+    expect(merge(pair("", " data-hidden"))).toBeNull();
+    expect(merge(pair(" data-hidden", ""))).toBeNull();
+    expect(merge(pair(" data-hidden", " data-hidden"))).not.toBeNull();
+  });
+});
+
+describe("detachAudioInSource on a hidden video", () => {
+  it("keeps the detached sound silent", () => {
+    const hidden = SOURCE.replace('<video id="talk"', '<video id="talk" data-hidden');
+    const result = detachAudioInSource(hidden, { target: video, videoId: "talk", track: 2 });
+    expect(attrsOf(result?.html ?? "", "audio#talk-audio")).toHaveProperty("data-hidden");
+    expect(attrsOf(result?.html ?? "", "video#talk")).toHaveProperty("data-hidden");
+  });
+});
+
+describe("removeElementInSource", () => {
+  it("removes the element and its whole line", () => {
+    expect(removeElementInSource('<div>\n  <audio id="a"></audio>\n</div>', { id: "a" })).toBe(
+      "<div>\n</div>",
+    );
+  });
+});
+
+describe("linkInSource", () => {
+  it("mints an id no element or link already uses", () => {
+    const src = '<video id="lk-1" data-link="lk-2"></video><audio id="a"></audio>';
+    expect(linkInSource(src, [{ id: "a" }])).toContain(
+      '<audio id="a" data-link="lk-3" data-sync-origin="lk-3">',
+    );
+  });
+
+  it("skips ids already used as a sync origin", () => {
+    const src = '<video id="v" data-sync-origin="lk-1"></video><audio id="a"></audio>';
+    expect(linkInSource(src, [{ id: "a" }])).toContain('data-link="lk-2"');
+  });
+});
+
+describe("linkInSource without a sync origin", () => {
+  it("writes only data-link", () => {
+    const src = '<video id="v"></video><audio id="a"></audio>';
+    expect(linkInSource(src, [{ id: "v" }, { id: "a" }], { syncOrigin: false })).toBe(
+      '<video id="v" data-link="lk-1"></video><audio id="a" data-link="lk-1"></audio>',
+    );
+  });
+});
+
+describe("setLinkInSource", () => {
+  it("writes and removes data-link on every target", () => {
+    const src = '<video id="v"></video><audio id="a"></audio>';
+    const linked = setLinkInSource(src, [{ id: "v" }, { id: "a" }], "lk-1");
+    expect(linked).toBe(
+      '<video id="v" data-link="lk-1"></video><audio id="a" data-link="lk-1"></audio>',
+    );
+    expect(setLinkInSource(linked, [{ id: "v" }, { id: "a" }], null)).toBe(src);
+  });
+
+  it("keeps the sync origin when unlinking", () => {
+    const linked = linkInSource('<video id="v"></video><audio id="a"></audio>', [
+      { id: "v" },
+      { id: "a" },
+    ]);
+    const unlinked = setLinkInSource(linked, [{ id: "v" }, { id: "a" }], null);
+    expect(unlinked).toBe(
+      '<video id="v" data-sync-origin="lk-1"></video><audio id="a" data-sync-origin="lk-1"></audio>',
+    );
+  });
+});
+
+const el = (id: string, tag: string, extra: Record<string, unknown> = {}) => ({
+  id,
+  tag,
+  src: "assets/talk.mp4",
+  start: 2,
+  duration: 6,
+  track: 0,
+  ...extra,
+});
+
+describe("predicates", () => {
+  it("detaches only an unmuted video with declared audio", () => {
+    expect(canDetachAudio(el("v", "video", { hasAudio: true }))).toBe(true);
+    expect(canDetachAudio(el("v", "video", { hasAudio: true, muted: true }))).toBe(false);
+    expect(canDetachAudio(el("v", "video"))).toBe(false);
+    expect(canDetachAudio(el("a", "audio", { hasAudio: true }))).toBe(false);
+  });
+
+  it("finds the merge pair from either member, linked or identically timed", () => {
+    const v = el("v", "video", { muted: true });
+    const a = el("a", "audio");
+    expect(findMergePair(v, [v, a])).toEqual({ video: v, audio: a });
+    expect(findMergePair(a, [v, a])).toEqual({ video: v, audio: a });
+    const drifted = el("a", "audio", { start: 3 });
+    expect(findMergePair(v, [v, drifted])).toBeNull();
+    const linked = [
+      el("v", "video", { muted: true, link: "lk-1" }),
+      el("a", "audio", { start: 3, link: "lk-1" }),
+    ];
+    expect(findMergePair(linked[0] ?? v, linked)?.audio.id).toBe("a");
+    expect(findMergePair(el("v", "video"), [el("v", "video"), a])).toBeNull();
+    expect(findMergePair(v, [v, el("a", "audio", { src: "other.mp4" })])).toBeNull();
+  });
+
+  it("links exactly one unlinked video and one audio, whatever their timing or file", () => {
+    expect(canLinkPair([el("v", "video"), el("a", "audio")])).toBe(true);
+    expect(canLinkPair([el("v", "video"), el("a", "audio", { start: 3, duration: 2 })])).toBe(true);
+    expect(canLinkPair([el("v", "video"), el("a", "audio", { src: "other.mp3" })])).toBe(true);
+    expect(canLinkPair([el("v", "video", { link: "x" }), el("a", "audio")])).toBe(false);
+    expect(canLinkPair([el("v", "video"), el("a", "audio", { link: "y" })])).toBe(false);
+    expect(canLinkPair([el("v", "video"), el("w", "video")])).toBe(false);
+    expect(canLinkPair([el("v", "video", { link: "x" }), el("a", "audio", { link: "x" })])).toBe(
+      false,
+    );
+  });
+});
+
+describe("predicates compare the whole asset path", () => {
+  const one = { src: "assets/one/talk.mp4" };
+  const two = { src: "assets/two/talk.mp4" };
+
+  it("does not pair same-named files in different folders", () => {
+    const v = el("v", "video", { muted: true, ...one });
+    const a = el("a", "audio", two);
+    expect(findMergePair(v, [v, a])).toBeNull();
+    expect(sharesSourceFile([el("v", "video", one), el("a", "audio", two)])).toBe(false);
+  });
+
+  it("resolves each src against its own source file, and links only inside one", () => {
+    const v = el("v", "video", { src: "../assets/talk.mp4", sourceFile: "scenes/a.html" });
+    const a = el("a", "audio", { src: "./assets/talk.mp4", sourceFile: "index.html" });
+    expect(canLinkPair([v, a])).toBe(false);
+    expect(sharesSourceFile([v, a])).toBe(false);
+    const sameFileAudio = { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" };
+    expect(sharesSourceFile([v, sameFileAudio])).toBe(true);
+  });
+
+  it("does not take a same-id link from another source file as the merge partner", () => {
+    const v = el("v", "video", { muted: true, link: "lk-1", sourceFile: "index.html" });
+    const a = el("a", "audio", { start: 3, link: "lk-1", sourceFile: "child.html" });
+    expect(findMergePair(v, [v, a])).toBeNull();
+  });
+
+  it("does not link or merge a pair split across inline compositions", () => {
+    const v = el("v", "video", { muted: true, compositionScope: "main" });
+    const a = el("a", "audio", { compositionScope: "child" });
+    expect(canLinkPair([v, a])).toBe(false);
+    expect(findMergePair(v, [v, a])).toBeNull();
+  });
+
+  it("does not merge a hidden audio back into a visible video", () => {
+    const v = el("v", "video", { muted: true });
+    expect(findMergePair(v, [v, el("a", "audio", { hidden: true })])).toBeNull();
+  });
+});
+
+describe("pickDetachedAudioTrack", () => {
+  it("uses the first free audio track below the visual tracks", () => {
+    const elements = [el("v", "video", { track: 0 }), el("t", "div", { track: 1 })];
+    expect(pickDetachedAudioTrack(elements, { start: 2, duration: 6 })).toBe(2);
+  });
+
+  it("reuses an audio track that is free in the clip's window", () => {
+    const elements = [
+      el("v", "video", { track: 0 }),
+      el("m", "audio", { track: 1, start: 0, duration: 2 }),
+    ];
+    expect(pickDetachedAudioTrack(elements, { start: 2, duration: 6 })).toBe(1);
+  });
+
+  it("opens a new bottom track when every audio track is busy", () => {
+    const elements = [
+      el("v", "video", { track: 0 }),
+      el("m", "audio", { track: 1, start: 0, duration: 10 }),
+    ];
+    expect(pickDetachedAudioTrack(elements, { start: 2, duration: 6 })).toBe(2);
+  });
+});

package/src/components/editor/mediaLinkEdits.ts

@@ -0,0 +1,303 @@
+import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
+import {
+  MEDIA_LINK_ATTR,
+  SYNC_ORIGIN_ATTR,
+  mintLinkId,
+  sourceZeroTime,
+} from "@hyperframes/core/media-link";
+import { sameCompositionScope, type TimelineElement } from "../../player/store/timelineElement";
+import { mediaAssetIdentity, sharesLinkGroup } from "../../player/components/audioClipLink";
+import {
+  applyPatchByTarget,
+  findTagByTarget,
+  readAttributeByTarget,
+  type PatchOperation,
+  type PatchTarget,
+} from "../../utils/sourcePatcher";
+import { collectHtmlIds } from "../../utils/studioHelpers";
+import { generateId } from "../../utils/generateId";
+import {
+  COPIED_TIMING_ATTRS,
+  MOVED_SOUND_ATTRS,
+  firstFreeName,
+  formatAttrs,
+  insertBeforeTarget,
+  readAuthoredSrc,
+  splitAutomation,
+} from "./mediaAudioEdits";
+
+const LINK_PROPERTY = MEDIA_LINK_ATTR.slice("data-".length);
+const HIDDEN_ATTR = "data-hidden";
+const SYNC_ORIGIN_PROPERTY = SYNC_ORIGIN_ATTR.slice("data-".length);
+const SYNC_TOLERANCE_S = 1e-3;
+
+const dataOp = (property: string, value: string | null): PatchOperation => ({
+  type: "attribute",
+  property: property.startsWith("data-") ? property.slice("data-".length) : property,
+  value,
+});
+
+const htmlOp = (property: string, value: string | null): PatchOperation => ({
+  type: "html-attribute",
+  property,
+  value,
+});
+
+function applyOps(source: string, target: PatchTarget, ops: readonly PatchOperation[]): string {
+  return ops.reduce((html, op) => applyPatchByTarget(html, target, op), source);
+}
+
+function mintLinkIdForSource(source: string): string {
+  const links = Array.from(
+    source.matchAll(/\bdata-(?:link|sync-origin)=["']([^"']+)["']/g),
+    (match) => match[1] ?? "",
+  );
+  return mintLinkId([...collectHtmlIds(source), ...links]);
+}
+
+/** Write (or with `null`, remove) `data-link` on every target. */
+export function setLinkInSource(
+  source: string,
+  targets: readonly PatchTarget[],
+  linkId: string | null,
+): string {
+  return targets.reduce(
+    (html, target) => applyPatchByTarget(html, target, dataOp(LINK_PROPERTY, linkId)),
+    source,
+  );
+}
+
+/** Link the targets under one fresh id, also their sync origin when they share a source file. */
+export function linkInSource(
+  source: string,
+  targets: readonly PatchTarget[],
+  options: { syncOrigin: boolean } = { syncOrigin: true },
+): string {
+  const linkId = mintLinkIdForSource(source);
+  const ops = options.syncOrigin
+    ? [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]
+    : [dataOp(LINK_PROPERTY, linkId)];
+  return targets.reduce((html, target) => applyOps(html, target, ops), source);
+}
+
+/** Remove one element (open tag through its matching close tag) and its line's indentation. */
+export function removeElementInSource(source: string, target: PatchTarget): string {
+  const match = findTagByTarget(source, target);
+  if (!match) return source;
+  const tagName = /^<([a-zA-Z][\w-]*)/.exec(match.tag)?.[1]?.toLowerCase() ?? "";
+  const closing = `</${tagName}>`;
+  const closeAt = match.tag.endsWith("/>")
+    ? -1
+    : source.toLowerCase().indexOf(closing, match.end + 1);
+  let end = closeAt >= 0 ? closeAt + closing.length : match.end + 1;
+  let start = match.start;
+  const lineStart = source.lastIndexOf("\n", start) + 1;
+  if (/^[ \t]*$/.test(source.slice(lineStart, start)) && source[end] === "\n") {
+    start = lineStart;
+    end += 1;
+  }
+  return source.slice(0, start) + source.slice(end);
+}
+
+function hasBooleanAttr(source: string, target: PatchTarget, name: string): boolean {
+  const tag = findTagByTarget(source, target)?.tag ?? "";
+  return new RegExp(`\\s${name}(?=[\\s=/>]|$)`, "i").test(tag);
+}
+
+export interface DetachAudioResult {
+  html: string;
+  audioId: string;
+  linkId: string;
+}
+
+/**
+ * Detach audio: insert a linked `<audio>` over the same file and window, move the
+ * sound attributes onto it, and mute the video. Renders identically.
+ */
+export function detachAudioInSource(
+  source: string,
+  input: { target: PatchTarget; videoId: string | null; track: number },
+): DetachAudioResult | null {
+  const { target } = input;
+  if (!findTagByTarget(source, target)) return null;
+  const linkId = mintLinkIdForSource(source);
+  const audioId = firstFreeName(
+    `${input.videoId || "video"}-audio`,
+    new Set(collectHtmlIds(source)),
+  );
+
+  const moved: Array<[string, string]> = [];
+  const videoOps: PatchOperation[] = [htmlOp("muted", "true"), dataOp("has-audio", null)];
+  for (const name of MOVED_SOUND_ATTRS) {
+    const value = readAttributeByTarget(source, target, name);
+    if (value === undefined) continue;
+    moved.push([name, value]);
+    videoOps.push(dataOp(name, null));
+  }
+  const automation = readAttributeByTarget(source, target, HF_AUDIO_AUTOMATION_ATTR);
+  if (automation !== undefined) {
+    const { videoKeeps, audioTakes } = splitAutomation(automation);
+    moved.push([HF_AUDIO_AUTOMATION_ATTR, audioTakes]);
+    videoOps.push(dataOp(HF_AUDIO_AUTOMATION_ATTR, videoKeeps));
+  }
+  videoOps.push(dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId));
+
+  const timing: Array<[string, string]> = [];
+  for (const name of COPIED_TIMING_ATTRS) {
+    const value = readAttributeByTarget(source, target, name);
+    if (value !== undefined) timing.push([`data-${name}`, value]);
+  }
+  const attrs: Array<[string, string]> = [
+    ["id", audioId],
+    ["data-hf-id", `hf-${generateId()}`],
+    ["class", "clip"],
+    ["src", readAuthoredSrc(source, target)],
+    ...timing,
+    ["data-track-index", String(input.track)],
+    [MEDIA_LINK_ATTR, linkId],
+    [SYNC_ORIGIN_ATTR, linkId],
+    ...moved,
+  ];
+  if (hasBooleanAttr(source, target, "loop")) attrs.push(["loop", ""]);
+  if (hasBooleanAttr(source, target, HIDDEN_ATTR)) attrs.push([HIDDEN_ATTR, ""]);
+  const inserted = insertBeforeTarget(source, target, `<audio ${formatAttrs(attrs)}></audio>`);
+  return { html: applyOps(inserted, target, videoOps), audioId, linkId };
+}
+
+/**
+ * Merge back: move the audio's sound attributes onto its video, unmute the
+ * video, drop the link, and delete the audio. The inverse of detach.
+ */
+export function mergeAudioInSource(
+  source: string,
+  input: { videoTarget: PatchTarget; audioTarget: PatchTarget },
+): string | null {
+  const { videoTarget, audioTarget } = input;
+  if (!findTagByTarget(source, videoTarget) || !findTagByTarget(source, audioTarget)) return null;
+  const assetOf = (target: PatchTarget) =>
+    mediaAssetIdentity({ src: readAuthoredSrc(source, target) });
+  const videoAsset = assetOf(videoTarget);
+  if (!videoAsset || videoAsset !== assetOf(audioTarget)) return null;
+  const hiddenOf = (target: PatchTarget) => hasBooleanAttr(source, target, HIDDEN_ATTR);
+  if (hiddenOf(videoTarget) !== hiddenOf(audioTarget)) return null;
+  const videoOps: PatchOperation[] = [];
+  for (const name of MOVED_SOUND_ATTRS) {
+    const value = readAttributeByTarget(source, audioTarget, name);
+    videoOps.push(dataOp(name, value ?? null));
+  }
+  const automation = readAttributeByTarget(source, audioTarget, HF_AUDIO_AUTOMATION_ATTR);
+  if (automation !== undefined) videoOps.push(dataOp(HF_AUDIO_AUTOMATION_ATTR, automation));
+  videoOps.push(
+    htmlOp("muted", null),
+    dataOp(LINK_PROPERTY, null),
+    dataOp(SYNC_ORIGIN_PROPERTY, null),
+    dataOp("has-audio", "true"),
+  );
+  return applyOps(removeElementInSource(source, audioTarget), videoTarget, videoOps);
+}
+
+type TimedElement = Pick<
+  TimelineElement,
+  "id" | "key" | "tag" | "src" | "start" | "duration" | "playbackStart" | "playbackRate" | "link"
+> &
+  Pick<TimelineElement, "muted" | "hasAudio" | "hidden" | "sourceFile" | "compositionScope">;
+
+const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();
+const keyOf = (el: Pick<TimelineElement, "id" | "key">) => el.key ?? el.id;
+const near = (a: number, b: number) => Math.abs(a - b) <= SYNC_TOLERANCE_S;
+
+function hasIdenticalTiming(a: TimedElement, b: TimedElement): boolean {
+  return (
+    near(a.start, b.start) &&
+    near(a.duration, b.duration) &&
+    near(a.playbackStart ?? 0, b.playbackStart ?? 0) &&
+    near(a.playbackRate ?? 1, b.playbackRate ?? 1)
+  );
+}
+
+const sameAssetInScope = (a: TimedElement, b: TimedElement) => {
+  const asset = mediaAssetIdentity(a);
+  return asset !== null && asset === mediaAssetIdentity(b) && sameCompositionScope(a, b);
+};
+
+/** A video whose sound is on the video itself: what Detach audio acts on. */
+export function canDetachAudio(el: TimedElement): boolean {
+  return tagOf(el) === "video" && el.muted !== true && el.hasAudio === true;
+}
+
+/**
+ * The (muted video, audio) pair Merge back acts on, found from either member:
+ * same file, and linked to each other or with identical timing.
+ */
+export function findMergePair<T extends TimedElement>(
+  element: T,
+  elements: readonly T[],
+): { video: T; audio: T } | null {
+  const isVideo = tagOf(element) === "video";
+  if (!isVideo && tagOf(element) !== "audio") return null;
+  const partnerTag = isVideo ? "audio" : "video";
+  const candidates = elements.filter(
+    (el) =>
+      keyOf(el) !== keyOf(element) && tagOf(el) === partnerTag && sameAssetInScope(el, element),
+  );
+  const partner =
+    candidates.find((el) => sharesLinkGroup(el, element)) ??
+    candidates.find((el) => hasIdenticalTiming(el, element));
+  if (!partner) return null;
+  const video = isVideo ? element : partner;
+  const audio = isVideo ? partner : element;
+  if ((video.hidden === true) !== (audio.hidden === true)) return null;
+  return video.muted === true ? { video, audio } : null;
+}
+
+/** One video and one audio in one composition, neither linked: timing and file don't matter. */
+export function canLinkPair(selected: readonly TimedElement[]): boolean {
+  if (selected.length !== 2) return false;
+  const [a, b] = selected;
+  if (!a || !b || a.link || b.link) return false;
+  const tags = new Set([tagOf(a), tagOf(b)]);
+  return tags.has("video") && tags.has("audio") && sameCompositionScope(a, b);
+}
+
+export function sharesSourceFile(selected: readonly TimedElement[]): boolean {
+  const [a, b] = selected;
+  return selected.length === 2 && !!a && !!b && sameAssetInScope(a, b);
+}
+
+export function isPairInSync(a: TimedElement, b: TimedElement): boolean {
+  const timing = (el: TimedElement) => ({
+    start: el.start,
+    mediaStart: el.playbackStart ?? 0,
+    playbackRate: el.playbackRate ?? 1,
+  });
+  const [x, y] = [timing(a), timing(b)];
+  return near(x.playbackRate, y.playbackRate) && near(sourceZeroTime(x), sourceZeroTime(y));
+}
+
+type TrackedElement = Pick<TimelineElement, "tag" | "track" | "start" | "duration"> & {
+  authoredTrack?: number;
+};
+
+/**
+ * The detached audio's track: the first audio-only track below every visual
+ * track that is free for the clip's window, else a new track at the bottom.
+ */
+export function pickDetachedAudioTrack(
+  elements: readonly TrackedElement[],
+  window: { start: number; duration: number },
+): number {
+  const trackOf = (el: TrackedElement) => el.authoredTrack ?? el.track;
+  const visualTracks = elements.filter((el) => tagOf(el) !== "audio").map(trackOf);
+  const lowestAudio = Math.max(-1, ...visualTracks) + 1;
+  const end = window.start + window.duration;
+  const allTracks = elements.map(trackOf);
+  const bottom = Math.max(lowestAudio - 1, ...allTracks) + 1;
+  for (let track = lowestAudio; track < bottom; track += 1) {
+    const occupants = elements.filter((el) => trackOf(el) === track);
+    const free = occupants.every(
+      (el) => tagOf(el) === "audio" && (el.start >= end || el.start + el.duration <= window.start),
+    );
+    if (free) return track;
+  }
+  return bottom;
+}

package/src/components/editor/previewReadOnly.overlay.test.tsx

@@ -105,7 +105,14 @@ function fixture(
 }
 
 const fire = (target: Element, type: string, init: MouseEventInit = {}) => {
-  const event = new MouseEvent(type, { bubbles: true, cancelable: true, button: 0, ...init });
+  const buttons = type === "pointerdown" || type === "pointermove" ? 1 : 0;
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    button: 0,
+    buttons,
+    ...init,
+  });
   act(() => {
     target.dispatchEvent(event);
   });

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

@@ -879,10 +879,11 @@ describe.each<PanelKind>(["flat", "design"])("%s panel — cutout keeps the soun
       htmlOp("muted", "true"),
       dataOp("has-audio", null),
       dataOp("volume", null),
-      dataOp("link", "link"),
+      dataOp("link", "lk-1"),
+      dataOp("sync-origin", "lk-1"),
     ]);
     const source =
-      '<div data-composition-id="main"><video id="s1-bg" src="assets/intro-loop.mp4" muted data-start="2" data-duration="3" data-track-index="0" data-link="link"></video></div>';
+      '<div data-composition-id="main"><video id="s1-bg" src="assets/intro-loop.mp4" muted data-start="2" data-duration="3" data-track-index="0" data-link="lk-1"></video></div>';
     const prepared = options?.prepareContent?.(source) ?? "";
     const audio = new DOMParser()
       .parseFromString(prepared, "text/html")
@@ -890,7 +891,7 @@ describe.each<PanelKind>(["flat", "design"])("%s panel — cutout keeps the soun
     expect(audio?.getAttribute("src")).toBe("assets/intro-loop.mp4");
     expect(audio?.getAttribute("data-start")).toBe("2");
     expect(audio?.getAttribute("data-duration")).toBe("3");
-    expect(audio?.getAttribute("data-link")).toBe("link");
+    expect(audio?.getAttribute("data-link")).toBe("lk-1");
     expect(audio?.getAttribute("data-volume")).toBe("0.5");
     expect(text).toContain("Background removed. Sound kept on a linked audio track.");
   });