Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(studio): link a video and its audio with data-link (6/8) (#4818)
Vance Ingalls0559be0b1398
diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.jsonindex f2626dd280..da3dfb8adf 100644--- a/packages/core/package-subpaths.json+++ b/packages/core/package-subpaths.json@@ -200,6 +200,12 @@"types": "./dist/audioCarve.d.ts","environments": ["browser", "bun", "node"]},+ "./media-link": {+ "source": "./src/mediaLink.ts",+ "runtime": "./dist/mediaLink.js",+ "types": "./dist/mediaLink.d.ts",+ "environments": ["browser", "bun", "node"]+ },"./audio-groups": {"source": "./src/audioGroups.ts","runtime": "./dist/audioGroups.js",diff --git a/packages/core/package.json b/packages/core/package.jsonindex a1d2c9a5ad..1cafeb7c65 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -214,6 +214,12 @@"import": "./src/audioCarve.ts","types": "./src/audioCarve.ts"},+ "./media-link": {+ "bun": "./src/mediaLink.ts",+ "node": "./dist/mediaLink.js",+ "import": "./src/mediaLink.ts",+ "types": "./src/mediaLink.ts"+ },"./audio-groups": {"bun": "./src/audioGroups.ts","node": "./dist/audioGroups.js",@@ -608,6 +614,10 @@"import": "./dist/audioCarve.js","types": "./dist/audioCarve.d.ts"},+ "./media-link": {+ "import": "./dist/mediaLink.js",+ "types": "./dist/mediaLink.d.ts"+ },"./audio-groups": {"import": "./dist/audioGroups.js","types": "./dist/audioGroups.d.ts"diff --git a/packages/core/src/mediaLink.test.ts b/packages/core/src/mediaLink.test.tsnew file mode 100644index 0000000000..568c7f930d--- /dev/null+++ b/packages/core/src/mediaLink.test.ts@@ -0,0 +1,99 @@+import { describe, expect, it } from "vitest";+import {+ MEDIA_LINK_ATTR,+ linkTimingMismatches,+ mintLinkId,+ readLinkTiming,+ relinkSplitHalves,+} from "./mediaLink";++const attrs = (values: Record<string, string>) => ({+ getAttribute: (name: string) => values[name] ?? null,+});++describe("readLinkTiming", () => {+ it("defaults media-start to 0 and playback-rate to 1", () => {+ expect(readLinkTiming(attrs({ "data-start": "2", "data-duration": "6" }))).toEqual({+ start: 2,+ duration: 6,+ mediaStart: 0,+ playbackRate: 1,+ });+ });++ it("reads data-playback-start as the media-start alias", () => {+ expect(readLinkTiming(attrs({ "data-playback-start": "1.5" })).mediaStart).toBe(1.5);+ });+});++describe("linkTimingMismatches", () => {+ const base = {+ "data-start": "2",+ "data-duration": "6",+ "data-media-start": "1",+ "data-playback-rate": "1",+ };++ it("is empty for members in sync, treating absent defaults as equal", () => {+ expect(+ linkTimingMismatches([+ attrs(base),+ attrs({ "data-start": "2", "data-duration": "6", "data-media-start": "1" }),+ ]),+ ).toEqual([]);+ });++ it.each([+ ["data-start", "start"],+ ["data-duration", "duration"],+ ["data-media-start", "media-start"],+ ["data-playback-rate", "playback-rate"],+ ])("names %s when it drifts", (attr, field) => {+ expect(linkTimingMismatches([attrs(base), attrs({ ...base, [attr]: "3" })])).toEqual([field]);+ });++ it("ignores sub-millisecond float noise", () => {+ expect(linkTimingMismatches([attrs(base), attrs({ ...base, "data-start": "2.0004" })])).toEqual(+ [],+ );+ });+});++describe("mintLinkId", () => {+ it("returns the first lk-N not already taken", () => {+ expect(mintLinkId([])).toBe("lk-1");+ expect(mintLinkId(["lk-1", "lk-2", "lk-4"])).toBe("lk-3");+ });+});++describe("relinkSplitHalves", () => {+ function doc(html: string): Document {+ document.body.innerHTML = html;+ return document;+ }++ it("gives each linked group's right halves one fresh shared id", () => {+ const d = doc(`+ <video id="v" data-link="lk-1"></video><video id="v-split" data-link="lk-1"></video>+ <audio id="a" data-link="lk-1"></audio><audio id="a-split" data-link="lk-1"></audio>+ <img id="i" /><img id="i-split" />`);+ relinkSplitHalves(d, ["v-split", "a-split", "i-split"]);+ const link = (id: string) => d.getElementById(id)?.getAttribute(MEDIA_LINK_ATTR) ?? null;+ expect(link("v")).toBe("lk-1");+ expect(link("a")).toBe("lk-1");+ expect(link("v-split")).toBe("lk-2");+ expect(link("a-split")).toBe("lk-2");+ expect(link("i-split")).toBeNull();+ });++ it("mints distinct ids for distinct groups", () => {+ const d = doc(`+ <video id="v" data-link="lk-1"></video><video id="v2" data-link="lk-1"></video>+ <video id="w" data-link="lk-7"></video><video id="w2" data-link="lk-7"></video>`);+ relinkSplitHalves(d, ["v2", "w2"]);+ const ids = ["v2", "w2"].map((id) => d.getElementById(id)?.getAttribute(MEDIA_LINK_ATTR));+ expect(new Set(ids).size).toBe(2);+ expect(ids).not.toContain("lk-1");+ expect(ids).not.toContain("lk-7");+ });+});diff --git a/packages/core/src/mediaLink.ts b/packages/core/src/mediaLink.tsnew file mode 100644index 0000000000..a74e24b224--- /dev/null+++ b/packages/core/src/mediaLink.ts@@ -0,0 +1,95 @@+/**+ * Linked clips: members sharing a `data-link` id are edited as one (a detached+ * video + its audio). An editing contract only; playback and render ignore it.+ */+export const MEDIA_LINK_ATTR = "data-link";++interface AttributeReader {+ getAttribute(name: string): string | null;+}++export interface LinkTiming {+ start: number;+ duration: number;+ mediaStart: number;+ playbackRate: number;+}++const LINK_TIMING_FIELDS: ReadonlyArray<[keyof LinkTiming, string]> = [+ ["start", "start"],+ ["duration", "duration"],+ ["mediaStart", "media-start"],+ ["playbackRate", "playback-rate"],+];++const SYNC_TOLERANCE_S = 1e-3;++function readNumber(el: AttributeReader, names: string[], fallback: number): number {+ for (const name of names) {+ const raw = el.getAttribute(name);+ if (raw === null || raw.trim() === "") continue;+ const value = Number(raw);+ if (Number.isFinite(value)) return value;+ }+ return fallback;+}++export function readLinkTiming(el: AttributeReader): LinkTiming {+ return {+ start: readNumber(el, ["data-start"], 0),+ duration: readNumber(el, ["data-duration"], 0),+ mediaStart: readNumber(el, ["data-media-start", "data-playback-start"], 0),+ playbackRate: readNumber(el, ["data-playback-rate"], 1),+ };+}++/** The timing fields (`start`, `duration`, `media-start`, `playback-rate`) on which members disagree. */+export function linkTimingMismatches(members: readonly AttributeReader[]): string[] {+ const timings = members.map(readLinkTiming);+ const first = timings[0];+ if (!first) return [];+ return LINK_TIMING_FIELDS.filter(([key]) =>+ timings.some((timing) => Math.abs(timing[key] - first[key]) > SYNC_TOLERANCE_S),+ ).map(([, field]) => field);+}++/** The composition a link group stays inside: the nearest inline composition or file host. */+export function linkScopeOf(el: Element): Element | null {+ return el.parentElement?.closest("[data-composition-id], [data-composition-file]") ?? null;+}++export function mintLinkId(taken: Iterable<string>): string {+ const used = new Set(taken);+ let n = 1;+ while (used.has(`lk-${n}`)) n += 1;+ return `lk-${n}`;+}++function takenLinkIds(doc: Document): string[] {+ return Array.from(doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}]`)).flatMap((el) => [+ el.id,+ el.getAttribute(MEDIA_LINK_ATTR) ?? "",+ ]);+}++/**+ * After a split, the right halves are clones still carrying the left halves'+ * link id. Give each group's right halves one fresh shared id, so each half of+ * a linked pair is its own pair.+ */+export function relinkSplitHalves(doc: Document, rightHalfIds: readonly string[]): void {+ const taken = new Set(takenLinkIds(doc));+ const renamed = new Map<string, string>();+ for (const id of rightHalfIds) {+ const el = doc.getElementById(id);+ const oldLink = el?.getAttribute(MEDIA_LINK_ATTR);+ if (!el || !oldLink) continue;+ let fresh = renamed.get(oldLink);+ if (!fresh) {+ fresh = mintLinkId(taken);+ taken.add(fresh);+ renamed.set(oldLink, fresh);+ }+ el.setAttribute(MEDIA_LINK_ATTR, fresh);+ }+}diff --git a/packages/lint/src/rules/linkedClips.test.ts b/packages/lint/src/rules/linkedClips.test.tsnew file mode 100644index 0000000000..c5f0977c78--- /dev/null+++ b/packages/lint/src/rules/linkedClips.test.ts@@ -0,0 +1,83 @@+import { describe, expect, it } from "vitest";+import { lintHyperframeHtml } from "../hyperframeLinter.js";++const VIDEO =+ 'id="talk" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-media-start="1" data-track-index="0"';+const AUDIO =+ 'id="talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-media-start="1" data-track-index="2"';++function composition(body: string): string {+ return `+<html><body>+ <div id="root" data-composition-id="c1" data-width="1920" data-height="1080">+ ${body}+ </div>+ <script>window.__timelines = {};</script>+</body></html>`;+}++async function linkFindings(body: string) {+ const result = await lintHyperframeHtml(composition(body));+ return result.findings.filter((f) => f.code.startsWith("linked_clip"));+}++describe("linked clip rules", () => {+ it("an in-sync pair is clean", async () => {+ expect(await linkFindings(`<video ${VIDEO}></video><audio ${AUDIO}></audio>`)).toEqual([]);+ });++ it("absent media-start and playback-rate equal their defaults", async () => {+ const video = VIDEO.replace(' data-media-start="1"', ' data-media-start="0"');+ const audio = AUDIO.replace(' data-media-start="1"', ' data-playback-rate="1"');+ expect(await linkFindings(`<video ${video}></video><audio ${audio}></audio>`)).toEqual([]);+ });++ it.each([+ ['data-start="2"', 'data-start="2.5"', "start"],+ ['data-duration="6"', 'data-duration="5"', "duration"],+ ['data-media-start="1"', 'data-media-start="0"', "media-start"],+ ['data-media-start="1"', 'data-media-start="1" data-playback-rate="2"', "playback-rate"],+ ])("warns when %s drifts to %s", async (from, to, field) => {+ const findings = await linkFindings(+ `<video ${VIDEO}></video><audio ${AUDIO.replace(from, to)}></audio>`,+ );+ expect(findings).toHaveLength(1);+ expect(findings[0]?.code).toBe("linked_clips_out_of_sync");+ expect(findings[0]?.severity).toBe("warning");+ expect(findings[0]?.message).toContain(field);+ expect(findings[0]?.message).toContain("lk-1");+ });++ it("warns on a link id with one member", async () => {+ const findings = await linkFindings(`<video ${VIDEO}></video>`);+ expect(findings).toHaveLength(1);+ expect(findings[0]?.code).toBe("linked_clip_orphan");+ expect(findings[0]?.severity).toBe("warning");+ expect(findings[0]?.elementId).toBe("talk");+ });++ it("track index, volume and fades may differ freely", async () => {+ const audio = `${AUDIO} data-volume="0.5" data-fade-in="1"`;+ expect(await linkFindings(`<video ${VIDEO}></video><audio ${audio}></audio>`)).toEqual([]);+ });++ it("groups links per composition, so a nested composition may reuse an id", async () => {+ const nested = `<div id="child" data-composition-id="child" data-start="0" data-duration="10">+ <video ${VIDEO.replace('id="talk"', 'id="c-talk"').replace('data-start="2"', 'data-start="5"')}></video>+ <audio ${AUDIO.replace('id="talk-audio"', 'id="c-audio"').replace('data-start="2"', 'data-start="5"')}></audio>+ </div>`;+ expect(await linkFindings(`<video ${VIDEO}></video><audio ${AUDIO}></audio>${nested}`)).toEqual(+ [],+ );+ });++ it("treats an inlined file host as its own composition too", async () => {+ const hosted = `<div id="host" data-composition-file="child.html" data-start="0">+ <video ${VIDEO.replace('id="talk"', 'id="h-talk"').replace('data-start="2"', 'data-start="5"')}></video>+ </div>`;+ const findings = await linkFindings(+ `<video ${VIDEO}></video><audio ${AUDIO}></audio>${hosted}`,+ );+ expect(findings.map((f) => [f.code, f.elementId])).toEqual([["linked_clip_orphan", "h-talk"]]);+ });+});diff --git a/packages/lint/src/rules/linkedClips.ts b/packages/lint/src/rules/linkedClips.tsnew file mode 100644index 0000000000..90c5a57c23--- /dev/null+++ b/packages/lint/src/rules/linkedClips.ts@@ -0,0 +1,94 @@+import type { LintContext, HyperframeLintFinding, OpenTag } from "../context";+import { readAttr, truncateSnippet } from "../utils";++const SYNC_TOLERANCE_S = 1e-3;++const LINKED_TIMING_FIELDS: ReadonlyArray<{ field: string; attrs: string[]; fallback: number }> = [+ { field: "start", attrs: ["data-start"], fallback: 0 },+ { field: "duration", attrs: ["data-duration"], fallback: 0 },+ { field: "media-start", attrs: ["data-media-start", "data-playback-start"], fallback: 0 },+ { field: "playback-rate", attrs: ["data-playback-rate"], fallback: 1 },+];++function readTimingField(tag: OpenTag, attrs: string[], fallback: number): number {+ for (const attr of attrs) {+ const raw = readAttr(tag.raw, attr);+ if (raw === null || raw.trim() === "") continue;+ const value = Number(raw);+ if (Number.isFinite(value)) return value;+ }+ return fallback;+}++function driftingFields(members: readonly OpenTag[]): string[] {+ return LINKED_TIMING_FIELDS.filter(({ attrs, fallback }) => {+ const values = members.map((tag) => readTimingField(tag, attrs, fallback));+ const first = values[0] ?? fallback;+ return values.some((value) => Math.abs(value - first) > SYNC_TOLERANCE_S);+ }).map(({ field }) => field);+}++function compositionScopeOf(tag: OpenTag, compositions: readonly OpenTag[]): number {+ let scope = -1;+ for (const composition of compositions) {+ const end = composition.endIndex ?? composition.closeIndex ?? Number.POSITIVE_INFINITY;+ const encloses = composition.index < tag.index && tag.index < end;+ if (composition !== tag && encloses && composition.index > scope) scope = composition.index;+ }+ return scope;+}++function groupByLink(tags: readonly OpenTag[]): Map<string, { link: string; members: OpenTag[] }> {+ const compositions = tags.filter((tag) =>+ ["data-composition-id", "data-composition-file"].some(+ (name) => readAttr(tag.raw, name) !== null,+ ),+ );+ const groups = new Map<string, { link: string; members: OpenTag[] }>();+ for (const tag of tags) {+ const link = readAttr(tag.raw, "data-link");+ if (!link) continue;+ const key = `${compositionScopeOf(tag, compositions)}\u0000${link}`;+ const group = groups.get(key) ?? { link, members: [] };+ group.members.push(tag);+ groups.set(key, group);+ }+ return groups;+}++const memberLabel = (tag: OpenTag) => {+ const id = readAttr(tag.raw, "id");+ return id ? `#${id}` : `<${tag.name}>`;+};++export function findLinkedClipFindings(ctx: LintContext): HyperframeLintFinding[] {+ const findings: HyperframeLintFinding[] = [];+ for (const { link, members } of groupByLink(ctx.tags).values()) {+ const first = members[0];+ if (!first) continue;+ const elementId = readAttr(first.raw, "id") || undefined;+ if (members.length === 1) {+ findings.push({+ code: "linked_clip_orphan",+ severity: "warning",+ message: `${memberLabel(first)} is the only clip with data-link="${link}"; its linked partner is gone.`,+ elementId,+ fixHint: `Remove data-link="${link}" from ${memberLabel(first)}, or restore the partner clip.`,+ snippet: truncateSnippet(first.raw),+ });+ continue;+ }+ const drift = driftingFields(members);+ if (drift.length === 0) continue;+ findings.push({+ code: "linked_clips_out_of_sync",+ severity: "warning",+ message: `Linked clips ${members.map(memberLabel).join(", ")} (data-link="${link}") differ in ${drift.join(", ")}.`,+ elementId,+ fixHint:+ "Linked clips are edited as one: give every member the same data-start, data-duration, data-media-start and data-playback-rate, or remove data-link from all of them to unlink.",+ snippet: truncateSnippet(first.raw),+ });+ }+ return findings;+}diff --git a/packages/lint/src/rules/media.ts b/packages/lint/src/rules/media.tsindex 695705b63d..3515e88a07 100644--- a/packages/lint/src/rules/media.ts+++ b/packages/lint/src/rules/media.ts@@ -13,6 +13,7 @@ import {import { validateColorGradingContract } from "@hyperframes/parsers/color-grading-contract";import { extractMediaSrcMutations } from "@hyperframes/parsers/composition";import { parseHTML } from "linkedom";+import { findLinkedClipFindings } from "./linkedClips";/*** Does the GSAP call that names `#id` also set `volume` in the same call?@@ -831,6 +832,7 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =// audio_group_carve_attrfindAudioGroupCarveAttrFindings,+ findLinkedClipFindings,];/**diff --git a/packages/sdk/src/engine/linkedTiming.ts b/packages/sdk/src/engine/linkedTiming.tsnew file mode 100644index 0000000000..cd4265ca13--- /dev/null+++ b/packages/sdk/src/engine/linkedTiming.ts@@ -0,0 +1,68 @@+import { MEDIA_LINK_ATTR, linkScopeOf } from "@hyperframes/core/media-link";+import type { HfId } from "../types.js";+import { escapeHfId, querySelectorAllDeep, resolveScoped } from "./model.js";++interface LinkMember {+ id: HfId;+ link: string;+}++function scopePrefix(id: HfId): string {+ const cut = id.lastIndexOf("/");+ return cut < 0 ? "" : id.slice(0, cut + 1);+}++/**+ * Every element sharing `id`'s link, addressed in `id`'s scope, `id` included.+ * Throws when a member's address resolves to a different element (a duplicate+ * id elsewhere), since editing that address would change the wrong clip.+ */+function linkGroup(document: Document, id: HfId): LinkMember[] {+ const el = resolveScoped(document, id);+ const link = el?.getAttribute(MEDIA_LINK_ATTR);+ if (!el || !link) return [];+ const scope = linkScopeOf(el);+ const prefix = scopePrefix(id);+ const members: LinkMember[] = [];+ for (const member of querySelectorAllDeep(+ scope ?? document,+ `[${MEDIA_LINK_ATTR}="${escapeHfId(link)}"]`,+ )) {+ const hfId = member.getAttribute("data-hf-id");+ if (!hfId || linkScopeOf(member) !== scope) continue;+ const memberId = `${prefix}${hfId}`;+ if (resolveScoped(document, memberId) !== member) {+ throw new Error(+ `Link partner "${memberId}" of "${id}" is not uniquely addressable; give it a unique data-hf-id.`,+ );+ }+ members.push({ id: memberId, link });+ }+ return members;+}++/** Link partners of `ids` that are not themselves in `ids`. */+export function linkedPartnerIds(document: Document, ids: readonly HfId[]): HfId[] {+ const own = new Set(ids);+ const partners = new Set<HfId>();+ for (const id of ids) {+ for (const member of linkGroup(document, id)) {+ if (!own.has(member.id)) partners.add(member.id);+ }+ }+ return [...partners];+}++/** `ids` leaving their link groups: themselves, plus any partner left alone. */+export function idsToUnlink(document: Document, ids: readonly HfId[]): HfId[] {+ const leaving = new Set(ids);+ const result = new Set<HfId>();+ for (const id of ids) {+ const group = linkGroup(document, id);+ if (group.length === 0) continue;+ result.add(id);+ const survivors = group.filter((member) => !leaving.has(member.id));+ if (survivors.length === 1 && survivors[0]) result.add(survivors[0].id);+ }+ return [...result];+}diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.tsindex 8b18eb5b32..4d5cc7f74d 100644--- a/packages/sdk/src/engine/mutate.ts+++ b/packages/sdk/src/engine/mutate.ts@@ -17,6 +17,8 @@ import type {JsonPatchOp,} from "../types.js";import type { ParsedDocument } from "./model.js";+import { MEDIA_LINK_ATTR } from "@hyperframes/core/media-link";+import { idsToUnlink, linkedPartnerIds } from "./linkedTiming.js";import {resolveScoped,escapeHfId,@@ -276,6 +278,38 @@ function applyGsapOp(parsed: ParsedDocument, op: EditOp): MutationResult | undef}}+const concatResults = (a: MutationResult, b: MutationResult): MutationResult => ({+ forward: [...a.forward, ...b.forward],+ inverse: [...a.inverse, ...b.inverse],+});++/**+ * Timing edits apply to link partners too (start/duration; each keeps its own+ * track). `linked: false` edits the targets alone and unlinks them.+ */+function applySetTiming(+ parsed: ParsedDocument,+ op: Extract<EditOp, { type: "setTiming" }>,+): MutationResult {+ const ids = targets(op.target);+ const timing = { start: op.start, duration: op.duration, trackIndex: op.trackIndex };+ if (op.linked === false) {+ const unlink = idsToUnlink(parsed.document, ids);+ const own = handleSetTiming(parsed, ids, timing);+ return concatResults(own, handleSetAttribute(parsed, unlink, MEDIA_LINK_ATTR, null));+ }+ const partners =+ op.start === undefined && op.duration === undefined+ ? []+ : linkedPartnerIds(parsed.document, ids);+ const own = handleSetTiming(parsed, ids, timing);+ if (partners.length === 0) return own;+ return concatResults(+ own,+ handleSetTiming(parsed, partners, { start: op.start, duration: op.duration }),+ );+}+export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {const gsap = applyGsapOp(parsed, op);if (gsap !== undefined) return gsap;@@ -287,11 +321,7 @@ export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {case "setAttribute":return handleSetAttribute(parsed, targets(op.target), op.name, op.value);case "setTiming":- return handleSetTiming(parsed, targets(op.target), {- start: op.start,- duration: op.duration,- trackIndex: op.trackIndex,- });+ return applySetTiming(parsed, op);case "setHold":return handleSetHold(parsed, targets(op.target), op.hold);case "moveElement":diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.tsnew file mode 100644index 0000000000..4baac66e70--- /dev/null+++ b/packages/sdk/src/session.linked.test.ts@@ -0,0 +1,130 @@+import { describe, expect, it } from "vitest";+import { openComposition } from "./session.js";++const LINKED_HTML = `+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">+ <video data-hf-id="hf-talk" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>+ <audio data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-track-index="2"></audio>+ <audio data-hf-id="hf-music" src="bgm.mp3" data-start="0" data-duration="10" data-track-index="3"></audio>+</div>+`.trim();++function attr(html: string, hfId: string, name: string): string | null {+ const tag = new RegExp(`<[^>]*data-hf-id="${hfId}"[^>]*>`).exec(html)?.[0] ?? "";+ return new RegExp(`\\b${name}="([^"]*)"`).exec(tag)?.[1] ?? null;+}++describe("setTiming on linked clips", () => {+ it("moves link partners by default, each keeping its own track", async () => {+ const comp = await openComposition(LINKED_HTML);+ comp.setTiming("hf-talk", { start: 3, trackIndex: 1 });+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-start")).toBe("3");+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("3");+ expect(attr(html, "hf-talk", "data-track-index")).toBe("1");+ expect(attr(html, "hf-talk-audio", "data-track-index")).toBe("2");+ expect(attr(html, "hf-music", "data-start")).toBe("0");+ });++ it("trims partners to the same duration, and one undo reverts both", async () => {+ const comp = await openComposition(LINKED_HTML);+ comp.setTiming("hf-talk-audio", { duration: 4 });+ expect(attr(comp.serialize(), "hf-talk", "data-duration")).toBe("4");+ comp.undo();+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-duration")).toBe("6");+ expect(attr(html, "hf-talk-audio", "data-duration")).toBe("6");+ });++ it("{ linked: false } edits one member and unlinks the pair", async () => {+ const comp = await openComposition(LINKED_HTML);+ comp.setTiming("hf-talk", { start: 5 }, { linked: false });+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-start")).toBe("5");+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("2");+ expect(attr(html, "hf-talk", "data-link")).toBeNull();+ expect(attr(html, "hf-talk-audio", "data-link")).toBeNull();+ comp.undo();+ expect(attr(comp.serialize(), "hf-talk", "data-link")).toBe("lk-1");+ });++ it("a batch naming both members stays in sync", async () => {+ const comp = await openComposition(LINKED_HTML);+ comp.setElementTiming({ "hf-talk": { start: 4 }, "hf-talk-audio": { start: 4 } });+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-start")).toBe("4");+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("4");+ });++ it.each([+ 'data-composition-id="child" data-composition-file="child.html"',+ 'data-composition-file="child.html"',+ ])("keeps a link group inside its own composition (host %s)", async (host) => {+ const comp = await openComposition(+ `+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">+ <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>+ <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>+ <div data-hf-id="hf-host" ${host} data-start="0" data-duration="10" data-track-index="2">+ <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>+ <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>+ </div>+</div>`.trim(),+ );+ comp.setTiming("hf-v", { start: 2 });+ let html = comp.serialize();+ expect(attr(html, "hf-a", "data-start")).toBe("2");+ expect(attr(html, "hf-cv", "data-start")).toBe("0");+ expect(attr(html, "hf-ca", "data-start")).toBe("0");+ comp.setTiming("hf-host/hf-cv", { start: 1 });+ html = comp.serialize();+ expect(attr(html, "hf-ca", "data-start")).toBe("1");+ expect(attr(html, "hf-v", "data-start")).toBe("2");+ expect(attr(html, "hf-a", "data-start")).toBe("2");+ });++ it("keeps a link group inside an inline composition that reuses the id", async () => {+ const comp = await openComposition(+ `+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">+ <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>+ <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>+ <div data-hf-id="hf-child" data-composition-id="child" data-start="0" data-duration="10" data-track-index="2">+ <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="5" data-duration="4" data-track-index="0"></video>+ <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="5" data-duration="4" data-track-index="1"></audio>+ </div>+</div>`.trim(),+ );+ comp.setTiming("hf-v", { start: 2 });+ let html = comp.serialize();+ expect(attr(html, "hf-a", "data-start")).toBe("2");+ expect(attr(html, "hf-cv", "data-start")).toBe("5");+ expect(attr(html, "hf-ca", "data-start")).toBe("5");+ comp.setTiming("hf-cv", { start: 6 });+ html = comp.serialize();+ expect(attr(html, "hf-ca", "data-start")).toBe("6");+ expect(attr(html, "hf-v", "data-start")).toBe("2");+ comp.setTiming("hf-ca", { start: 7 }, { linked: false });+ html = comp.serialize();+ expect(attr(html, "hf-cv", "data-link")).toBeNull();+ expect(attr(html, "hf-v", "data-link")).toBe("lk-1");+ expect(attr(html, "hf-a", "data-link")).toBe("lk-1");+ });++ it("refuses to edit a link partner whose id also names a root clip", async () => {+ const html = `+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">+ <audio data-hf-id="hf-a" src="bgm.mp3" data-start="0" data-duration="10" data-track-index="1"></audio>+ <div data-hf-id="hf-child" data-composition-id="child" data-start="0" data-duration="10" data-track-index="2">+ <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="5" data-duration="4" data-track-index="0"></video>+ <audio data-hf-id="hf-a" src="b.mp4" data-link="lk-1" data-start="5" data-duration="4" data-track-index="1"></audio>+ </div>+</div>`.trim();+ const comp = await openComposition(html);+ expect(() => comp.setTiming("hf-cv", { start: 2 })).toThrow(/not uniquely addressable/);+ expect(() => comp.setTiming("hf-cv", { start: 2 }, { linked: false })).toThrow(+ /not uniquely addressable/,+ );+ expect(comp.serialize()).toBe((await openComposition(html)).serialize());+ });+});diff --git a/packages/sdk/src/session.ts b/packages/sdk/src/session.tsindex 29ca50f951..1a77c7cc7e 100644--- a/packages/sdk/src/session.ts+++ b/packages/sdk/src/session.ts@@ -161,8 +161,12 @@ class CompositionImpl implements Composition {this.dispatch({ type: "setAttribute", target: id, name, value });}- setTiming(id: HfId, timing: { start?: number; duration?: number; trackIndex?: number }): void {- this.dispatch({ type: "setTiming", target: id, ...timing });+ setTiming(+ id: HfId,+ timing: { start?: number; duration?: number; trackIndex?: number },+ opts?: { linked?: boolean },+ ): void {+ this.dispatch({ type: "setTiming", target: id, ...timing, ...opts });}removeElement(id: HfId): void {@@ -563,7 +567,8 @@ class CompositionImpl implements Composition {setText: (value) => this.dispatch({ type: "setText", target: ids, value }),setAttribute: (name, value) =>this.dispatch({ type: "setAttribute", target: ids, name, value }),- setTiming: (timing) => this.dispatch({ type: "setTiming", target: ids, ...timing }),+ setTiming: (timing, opts) =>+ this.dispatch({ type: "setTiming", target: ids, ...timing, ...opts }),removeElement: () => this.dispatch({ type: "removeElement", target: ids }),};}@@ -575,7 +580,8 @@ class CompositionImpl implements Composition {setText: (value) => this.dispatch({ type: "setText", target: id, value }),setAttribute: (name, value) =>this.dispatch({ type: "setAttribute", target: id, name, value }),- setTiming: (timing) => this.dispatch({ type: "setTiming", target: id, ...timing }),+ setTiming: (timing, opts) =>+ this.dispatch({ type: "setTiming", target: id, ...timing, ...opts }),removeElement: () => this.dispatch({ type: "removeElement", target: id }),};}diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.tsindex ba902e7d07..d4599cabc9 100644--- a/packages/sdk/src/types.ts+++ b/packages/sdk/src/types.ts@@ -111,6 +111,8 @@ export type EditOp =start?: number;duration?: number;trackIndex?: number;+ /** Default true: start/duration also apply to `data-link` partners. `false` edits the target alone and unlinks it. */+ linked?: boolean;}| { type: "setHold"; target: HfId | HfId[]; hold: ElasticHold }| { type: "moveElement"; target: HfId | HfId[]; x: number; y: number }@@ -378,7 +380,10 @@ export interface SelectionProxy {setStyle(styles: Record<string, string | null>): void;setText(value: string): void;setAttribute(name: string, value: string | null): void;- setTiming(timing: { start?: number; duration?: number; trackIndex?: number }): void;+ setTiming(+ timing: { start?: number; duration?: number; trackIndex?: number },+ opts?: { linked?: boolean },+ ): void;removeElement(): void;}@@ -391,7 +396,10 @@ export interface ElementHandle {setStyle(styles: Record<string, string | null>): void;setText(value: string): void;setAttribute(name: string, value: string | null): void;- setTiming(timing: { start?: number; duration?: number; trackIndex?: number }): void;+ setTiming(+ timing: { start?: number; duration?: number; trackIndex?: number },+ opts?: { linked?: boolean },+ ): void;removeElement(): void;}@@ -421,7 +429,12 @@ export interface Composition {setStyle(id: HfId, styles: Record<string, string | null>): void;setText(id: HfId, value: string): void;setAttribute(id: HfId, name: string, value: string | null): void;- setTiming(id: HfId, timing: { start?: number; duration?: number; trackIndex?: number }): void;+ /** Also moves `data-link` partners unless `{ linked: false }`, which edits `id` alone and unlinks it. */+ setTiming(+ id: HfId,+ timing: { start?: number; duration?: number; trackIndex?: number },+ opts?: { linked?: boolean },+ ): void;removeElement(id: HfId): void;/*** Insert an HTML fragment as a child of `parent` at `index` (WS-D).diff --git a/packages/studio-server/src/helpers/sourceMutation.ts b/packages/studio-server/src/helpers/sourceMutation.tsindex 164a88824f..66873d43bc 100644--- a/packages/studio-server/src/helpers/sourceMutation.ts+++ b/packages/studio-server/src/helpers/sourceMutation.ts@@ -12,6 +12,7 @@ import {walkCompositionDescendants,} from "@hyperframes/parsers/hf-ids";import { readClipTiming, writeClipTiming } from "@hyperframes/core/composition-contract";+import { relinkSplitHalves } from "@hyperframes/core/media-link";import { parseStyleDecls, patchStyleAttrString } from "./sourceStyleMutation.js";export interface SourceMutationTarget {@@ -700,3 +701,13 @@ export function unwrapElementsFromHtml(groupCenter,};}++/** After a cut, give each linked group's right halves their own shared `data-link`. */+export function relinkSplitHalvesInHtml(source: string, rightHalfIds: readonly string[]): string {+ const { document, wrappedFragment } = parseSourceDocument(source);+ if (!rightHalfIds.some((id) => document.getElementById(id)?.hasAttribute("data-link"))) {+ return source;+ }+ relinkSplitHalves(document, rightHalfIds);+ return wrappedFragment ? document.body.innerHTML || "" : document.toString();+}diff --git a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.tsindex 8585d06a79..2ed4297a8d 100644--- a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts+++ b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts@@ -4,6 +4,7 @@ import { describe, expect, it } from "vitest";import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";import {splitElementInHtml,+ relinkSplitHalvesInHtml,unwrapElementsFromHtml,wrapElementsInHtml,} from "./sourceMutation.js";@@ -395,3 +396,23 @@ describe("wrapElementsInHtml / unwrapElementsFromHtml", () => {expect(result.html).toBe(html);});});++describe("relinkSplitHalvesInHtml", () => {+ it("makes each half of a split linked pair its own pair", () => {+ const source =+ '<div data-composition-id="c"><video id="v" src="t.mp4" muted data-link="lk-1" data-start="0" data-duration="4"></video><audio id="a" src="t.mp4" data-link="lk-1" data-start="0" data-duration="4"></audio></div>';+ const first = splitElementInHtml(source, { id: "v" }, 2, "v-split");+ const second = splitElementInHtml(first.html, { id: "a" }, 2, "a-split");+ const html = relinkSplitHalvesInHtml(second.html, ["v-split", "a-split"]);+ const link = (id: string) => new RegExp(`id="${id}"[^>]*data-link="([^"]+)"`).exec(html)?.[1];+ expect(link("v")).toBe("lk-1");+ expect(link("a")).toBe("lk-1");+ expect(link("v-split")).toBe("lk-2");+ expect(link("a-split")).toBe("lk-2");+ });++ it("leaves unlinked splits byte-identical", () => {+ const source = '<div><img id="i" data-start="0" data-duration="4"></div>';+ expect(relinkSplitHalvesInHtml(source, ["i"])).toBe(source);+ });+});diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.tsindex 9fe116873f..585bb38e23 100644--- a/packages/studio-server/src/routes/files.ts+++ b/packages/studio-server/src/routes/files.ts@@ -83,6 +83,7 @@ import {patchElementInHtml,probeElementInSource,splitElementInHtml,+ relinkSplitHalvesInHtml,wrapElementsInHtml,unwrapElementsFromHtml,isHTMLElement,@@ -2163,6 +2164,7 @@ async function foldAtomicCutFile(let after = before;let splitCount = 0;const skippedSelectors = new Set<string>();+ const rightHalfIds: string[] = [];const respond = (data: unknown, status?: number) =>status ? c.json(data, status) : c.json(data);@@ -2204,6 +2206,7 @@ async function foldAtomicCutFile(}after = split.html;splitCount++;+ rightHalfIds.push(split.newId);if (!cut.originalId) continue;const block = extractGsapScriptBlock(after);@@ -2235,6 +2238,7 @@ async function foldAtomicCutFile(}}+ after = relinkSplitHalvesInHtml(after, rightHalfIds);return {path: file.path,absPath,diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsxindex 2aeb005dbd..316a4e5acc 100644--- a/packages/studio/src/App.tsx+++ b/packages/studio/src/App.tsx@@ -17,11 +17,7 @@ import { useFileManager } from "./hooks/useFileManager";import { usePreviewPersistence } from "./hooks/usePreviewPersistence";import { usePreviewDocumentVersion } from "./hooks/usePreviewDocumentVersion";import { useTimelineEditing } from "./hooks/useTimelineEditing";-import {- persistTimelineMoveEditsAtomically,- type TimelineMoveEditsHandler,- type TimelineMoveOperation,-} from "./hooks/timelineMoveAdapter";+import { useTimelineMoveEditsHandler } from "./hooks/timelineMoveAdapter";import type { TimelineZIndexReorderCommit } from "./hooks/useTimelineEditingTypes";import type { BlockPreviewInfo } from "./components/sidebar/BlocksTab";import { useDomEditSession } from "./hooks/useDomEditSession";@@ -179,12 +175,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: StinvalidateGsapCache,handleDomZIndexReorderCommitRef,});- const handleTimelineElementsMove: TimelineMoveEditsHandler = useCallback(- async (edits, coalesceKey, operation: TimelineMoveOperation = "timing", coalesceMs) => {- const deps = { handleTimelineGroupMove: timelineEditing.handleTimelineGroupMove };- await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);- },- [timelineEditing.handleTimelineGroupMove],+ const handleTimelineElementsMove = useTimelineMoveEditsHandler(+ timelineEditing.handleTimelineGroupMove,);const {addAssetAtPlayhead: handleAddAssetAtPlayhead,@@ -246,6 +238,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St});const appHotkeys = useAppHotkeys({handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,+ handleLinkEdit: timelineEditing.handleLinkEdit,+ handleTimelineElementDeleteOnly: timelineEditing.handleTimelineElementDeleteOnly,handleTimelineElementSplit: timelineEditing.handleTimelineElementSplit,handleDomEditElementDelete: domEditDeleteBridge,domEditSelectionRef: domEditSelectionBridgeRef,@@ -553,6 +547,8 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: SthandleRazorSplit={timelineEditing.handleRazorSplit}handleRazorSplitAll={timelineEditing.handleRazorSplitAll}handleFreezeFrame={timelineEditing.handleFreezeFrame}+ handleLinkEdit={timelineEditing.handleLinkEdit}+ handleTimelineElementDeleteOnly={timelineEditing.handleTimelineElementDeleteOnly}onCopyClip={handleCopy}onPasteClip={handlePaste}onDuplicateClip={handleDuplicate}diff --git a/packages/studio/src/components/EditorShell.tsx b/packages/studio/src/components/EditorShell.tsxindex 1bd2e60d38..ce0250769c 100644--- a/packages/studio/src/components/EditorShell.tsx+++ b/packages/studio/src/components/EditorShell.tsx@@ -104,6 +104,8 @@ export function EditorShell({handleRazorSplit,handleRazorSplitAll,handleFreezeFrame,+ handleLinkEdit,+ handleTimelineElementDeleteOnly,onCopyClip,onPasteClip,onDuplicateClip,@@ -165,6 +167,8 @@ export function EditorShell({handleRazorSplit,handleRazorSplitAll,handleFreezeFrame,+ handleLinkEdit,+ handleTimelineElementDeleteOnly,});return (diff --git a/packages/studio/src/components/editor/mediaAudioEdits.test.ts b/packages/studio/src/components/editor/mediaAudioEdits.test.tsindex 9f2e0203b1..199d0f49ac 100644--- a/packages/studio/src/components/editor/mediaAudioEdits.test.ts+++ b/packages/studio/src/components/editor/mediaAudioEdits.test.ts@@ -88,9 +88,9 @@ describe("cutoutOps", () => {describe("mintLinkId", () => {it("dedupes against element ids and existing links", () => {const doc = document.implementation.createHTMLDocument("t");- expect(mintLinkId(doc)).toBe("link");- doc.body.innerHTML = '<div id="link"></div><video data-link="link-2"></video>';- expect(mintLinkId(doc)).toBe("link-3");+ expect(mintLinkId(doc)).toBe("lk-1");+ doc.body.innerHTML = '<div id="lk-1"></div><video data-link="lk-2"></video>';+ expect(mintLinkId(doc)).toBe("lk-3");});});@@ -176,10 +176,24 @@ describe("buildKeepSoundCutoutEdit", () => {{ target: "rate", points: [{ t: 0, v: 2 }] },]);expect(audio.getAttribute("data-link")).toBe(video.getAttribute("data-link"));- expect(video.getAttribute("data-link")).toBe("link");+ expect(video.getAttribute("data-link")).toBe("lk-1");expect(audio.parentElement).toBe(video.parentElement);});+ it("keeps a hidden video's sound silent on the linked audio", () => {+ const video = liveVideo();+ video.setAttribute("data-hidden", "");+ const edit = buildKeepSoundCutoutEdit({+ video,+ videoId: "clip",+ target: { id: "clip" },+ cutoutSrc: "assets/talk-cutout.webm",+ });+ const hidden = source.replace('<video id="clip"', '<video id="clip" data-hidden');+ const doc = parse(applyEdit(hidden, edit));+ expect(doc.getElementById("clip-audio")?.hasAttribute("data-hidden")).toBe(true);+ });+it("drops the video's automation attribute when it held no rate lane", () => {const video = makeVideo({id: "clip",diff --git a/packages/studio/src/components/editor/mediaAudioEdits.ts b/packages/studio/src/components/editor/mediaAudioEdits.tsindex 48f9371633..7b22ce7bb6 100644--- a/packages/studio/src/components/editor/mediaAudioEdits.ts+++ b/packages/studio/src/components/editor/mediaAudioEdits.ts@@ -23,13 +23,13 @@ import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";import { buildDomEditPatchTarget, type DomEditSelection } from "./domEditing";import { generateId } from "../../utils/generateId";-const MEDIA_LINK_ATTR = "data-link";+import { MEDIA_LINK_ATTR, mintLinkId as mintLinkIdFrom } from "@hyperframes/core/media-link";const SOUND_KEPT_ON_LINKED_AUDIO_STAGE = "Background removed. Sound kept on a linked audio track.";const SOUND_NOT_KEPT_MESSAGE ="Background removed, but the sound could not be kept on a linked audio track. Undo to restore the original clip.";-const MOVED_SOUND_ATTRS = [+export const MOVED_SOUND_ATTRS = ["data-volume",HF_AUDIO_FADE_IN_ATTR,HF_AUDIO_FADE_OUT_ATTR,@@ -38,7 +38,7 @@ const MOVED_SOUND_ATTRS = [HF_AUDIO_GROUP_ATTR,];-const COPIED_TIMING_ATTRS = [+export const COPIED_TIMING_ATTRS = ["start","end","duration",@@ -91,7 +91,7 @@ export function cutoutOps(input: { isVideo: boolean; cutoutSrc: string }): Patchreturn input.isVideo ? [src, htmlAttr("muted", "true"), dataAttr("has-audio", null)] : [src];}-function firstFreeName(base: string, taken: Set<string>): string {+export function firstFreeName(base: string, taken: Set<string>): string {if (!taken.has(base)) return base;let n = 2;while (taken.has(`${base}-${n}`)) n += 1;@@ -105,7 +105,7 @@ export function mintLinkId(doc: Document): string {const link = el.getAttribute(MEDIA_LINK_ATTR);if (link) taken.add(link);}- return firstFreeName("link", taken);+ return mintLinkIdFrom(taken);}function firstFreeTrackIndex(source: string): number {@@ -117,7 +117,7 @@ function firstFreeTrackIndex(source: string): number {return track;}-function splitAutomation(raw: string): { videoKeeps: string | null; audioTakes: string } {+export function splitAutomation(raw: string): { videoKeeps: string | null; audioTakes: string } {let lanes: HfAutomationLane[];try {lanes = parseAutomation(raw).lanes;@@ -132,11 +132,11 @@ function splitAutomation(raw: string): { videoKeeps: string | null; audioTakes:};}-function formatAttrs(attrs: Array<[string, string]>): string {+export function formatAttrs(attrs: Array<[string, string]>): string {return attrs.map(([name, value]) => `${name}="${escapeHtmlAttribute(value)}"`).join(" ");}-function readAuthoredSrc(source: string, target: PatchTarget): string {+export function readAuthoredSrc(source: string, target: PatchTarget): string {const tag = findTagByTarget(source, target);if (!tag) return "";const own = /\bsrc=(["'])([^"']*)\1/.exec(tag.tag);@@ -145,7 +145,7 @@ function readAuthoredSrc(source: string, target: PatchTarget): string {return firstSource?.[2] ? unescapeHtmlAttribute(firstSource[2]) : "";}-function insertBeforeTarget(source: string, target: PatchTarget, markup: string): string {+export function insertBeforeTarget(source: string, target: PatchTarget, markup: string): string {const match = findTagByTarget(source, target);if (!match) return source;const lineStart = source.lastIndexOf("\n", match.start) + 1;@@ -211,6 +211,7 @@ export function buildKeepSoundCutoutEdit(input: {...movedSound,];if (video.hasAttribute("loop")) attrs.push(["loop", ""]);+ if (video.hasAttribute("data-hidden")) attrs.push(["data-hidden", ""]);const cut = applyPatchByTarget(source, target, cutoutSrcOp);const inserted = insertBeforeTarget(cut, target, `<audio ${formatAttrs(attrs)}></audio>`);audioInserted = inserted !== cut;diff --git a/packages/studio/src/components/editor/mediaLinkEdits.test.ts b/packages/studio/src/components/editor/mediaLinkEdits.test.tsnew file mode 100644index 0000000000..70c7fbb017--- /dev/null+++ b/packages/studio/src/components/editor/mediaLinkEdits.test.ts@@ -0,0 +1,301 @@+// @vitest-environment happy-dom+import { describe, expect, it } from "vitest";+import {+ canDetachAudio,+ canLinkPair,+ detachAudioInSource,+ linkInSource,+ findMergePair,+ mergeAudioInSource,+ pickDetachedAudioTrack,+ removeElementInSource,+ setLinkInSource,+} 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-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);+ 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">');+ });+});++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);+ });+});++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 video and one audio of the same file and timing", () => {+ expect(canLinkPair([el("v", "video"), el("a", "audio")])).toBe(true);+ expect(canLinkPair([el("v", "video"), el("a", "audio", { start: 3 })])).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(canLinkPair([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(+ canLinkPair([v, { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" }]),+ ).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);+ });+});diff --git a/packages/studio/src/components/editor/mediaLinkEdits.ts b/packages/studio/src/components/editor/mediaLinkEdits.tsnew file mode 100644index 0000000000..f98c26c87a--- /dev/null+++ b/packages/studio/src/components/editor/mediaLinkEdits.ts@@ -0,0 +1,270 @@+import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";+import { MEDIA_LINK_ATTR, mintLinkId } 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_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=["']([^"']+)["']/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 freshly minted id. */+export function linkInSource(source: string, targets: readonly PatchTarget[]): string {+ return setLinkInSource(source, targets, mintLinkIdForSource(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));++ 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],+ ...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("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;+}++/** Exactly one video and one audio, same file, identical timing, not already linked together. */+export function canLinkPair(selected: readonly TimedElement[]): boolean {+ if (selected.length !== 2) return false;+ const [a, b] = selected;+ if (!a || !b) return false;+ const tags = new Set([tagOf(a), tagOf(b)]);+ if (!tags.has("video") || !tags.has("audio")) return false;+ if (sharesLinkGroup(a, b)) return false;+ return sameAssetInScope(a, b) && hasIdenticalTiming(a, b);+}++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;+}diff --git a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsxindex 8507215654..b479e00f44 100644--- a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx+++ b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx@@ -879,10 +879,10 @@ describe.each<PanelKind>(["flat", "design"])("%s panel — cutout keeps the sounhtmlOp("muted", "true"),dataOp("has-audio", null),dataOp("volume", null),- dataOp("link", "link"),+ dataOp("link", "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 +890,7 @@ describe.each<PanelKind>(["flat", "design"])("%s panel — cutout keeps the sounexpect(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.");});diff --git a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts b/packages/studio/src/components/nle/useTimelineEditCallbacks.tsindex 8dae98bc5b..beacb819ed 100644--- a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts+++ b/packages/studio/src/components/nle/useTimelineEditCallbacks.ts@@ -54,6 +54,8 @@ export interface TimelineEditCallbackDeps {handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;handleRazorSplitAll: (splitTime: number) => Promise<void> | void;handleFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;+ handleLinkEdit?: TimelineEditCallbacks["onLinkEdit"];+ handleTimelineElementDeleteOnly?: TimelineEditCallbacks["onDeleteElementOnly"];/** C1's ungrouped-track FX pointer — same auto-grouping write B6's carve uses. */handleGroupClips?: (clipIds: readonly string[],@@ -134,6 +136,8 @@ export function useTimelineEditCallbacks({handleRazorSplit,handleRazorSplitAll,handleFreezeFrame,+ handleLinkEdit,+ handleTimelineElementDeleteOnly,handleGroupClips,setElementFxAttribute,}: TimelineEditCallbackDeps): TimelineEditCallbacks {@@ -230,6 +234,8 @@ export function useTimelineEditCallbacks({onRazorSplit: handleRazorSplit,onRazorSplitAll: handleRazorSplitAll,onFreezeFrame: handleFreezeFrame,+ onLinkEdit: handleLinkEdit,+ onDeleteElementOnly: handleTimelineElementDeleteOnly,onDeleteAllKeyframes: (element, animationId) => {// Hold the element where it is (collapse keyframes to a static set) rather// than deleting the whole animation — deleting strands a stale GSAP base@@ -427,6 +433,8 @@ export function useTimelineEditCallbacks({handleRazorSplit,handleRazorSplitAll,handleFreezeFrame,+ handleLinkEdit,+ handleTimelineElementDeleteOnly,handleGsapRemoveAllKeyframes,resolveElementAnimations,resolveKeyframeTarget,diff --git a/packages/studio/src/contexts/TimelineEditContext.tsx b/packages/studio/src/contexts/TimelineEditContext.tsxindex 67afa51a05..3ec34a8889 100644--- a/packages/studio/src/contexts/TimelineEditContext.tsx+++ b/packages/studio/src/contexts/TimelineEditContext.tsx@@ -39,6 +39,8 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {onSetElementAttributeQuiet: true,onRevertElementAttributeLive: true,onBlockedEditAttempt: true,+ onLinkEdit: true,+ onDeleteElementOnly: true,onSplitElement: true,onRazorSplit: true,onRazorSplitAll: true,diff --git a/packages/studio/src/hooks/appHotkeysDispatch.ts b/packages/studio/src/hooks/appHotkeysDispatch.tsindex 909b6ad5fd..35c82f6ef2 100644--- a/packages/studio/src/hooks/appHotkeysDispatch.ts+++ b/packages/studio/src/hooks/appHotkeysDispatch.ts@@ -9,6 +9,7 @@ import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";import { canSplitElement } from "../utils/timelineElementSplit";import { trackStudioEvent } from "../utils/studioTelemetry";import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";+import type { LinkShortcutCallbacks } from "./linkShortcuts";// Extracted from useAppHotkeys.ts to keep it under the studio 600-line cap,// following useTimelineDeleteOps's precedent. Pure functions, no hooks — the@@ -29,7 +30,7 @@ function handleUndoRedoKey(event: KeyboardEvent, onUndo: () => void, onRedo: ()return false;}-export interface HotkeyCallbacks {+export interface HotkeyCallbacks extends LinkShortcutCallbacks {handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;handleDomEditElementDelete: (diff --git a/packages/studio/src/hooks/linkShortcuts.test.ts b/packages/studio/src/hooks/linkShortcuts.test.tsnew file mode 100644index 0000000000..93ab84c85d--- /dev/null+++ b/packages/studio/src/hooks/linkShortcuts.test.ts@@ -0,0 +1,70 @@+// @vitest-environment happy-dom+import { afterEach, describe, expect, it, vi } from "vitest";+import { usePlayerStore, type TimelineElement } from "../player";+import { dispatchLinkShortcut } from "./linkShortcuts";++const clip = (id: string, tag: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({+ id,+ tag,+ src: "talk.mp4",+ start: 0,+ duration: 4,+ track: 0,+ ...extra,+});++function key(init: KeyboardEventInit): KeyboardEvent {+ const event = new KeyboardEvent("keydown", { cancelable: true, ...init });+ vi.spyOn(event, "preventDefault");+ return event;+}++function select(elements: TimelineElement[], id: string) {+ usePlayerStore.getState().setElements(elements);+ usePlayerStore.getState().setSelection([id], id);+}++describe("dispatchLinkShortcut", () => {+ afterEach(() => vi.restoreAllMocks());++ it("⌘L unlinks the selected linked clip", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-1" });+ const audio = clip("talk-audio", "audio", { link: "lk-1" });+ select([video, audio], "talk");+ const handleLinkEdit = vi.fn();+ const event = key({ metaKey: true, key: "l" });+ expect(dispatchLinkShortcut(event, { handleLinkEdit })).toBe(true);+ expect(handleLinkEdit).toHaveBeenCalledWith({ kind: "unlink", elements: [video, audio] });+ expect(event.preventDefault).toHaveBeenCalled();+ });++ it("⌥⇧D detaches audio, read by key code since Option changes the character", () => {+ const talk = clip("talk", "video", { hasAudio: true });+ select([talk], "talk");+ const handleLinkEdit = vi.fn();+ expect(+ dispatchLinkShortcut(key({ altKey: true, shiftKey: true, key: "Î", code: "KeyD" }), {+ handleLinkEdit,+ }),+ ).toBe(true);+ expect(handleLinkEdit).toHaveBeenCalledWith({ kind: "detach", element: talk });+ });++ it("⌥⌫ deletes one linked member", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-1" });+ select([video, clip("talk-audio", "audio", { link: "lk-1" })], "talk");+ const handleTimelineElementDeleteOnly = vi.fn();+ dispatchLinkShortcut(key({ altKey: true, key: "Backspace" }), {+ handleLinkEdit: vi.fn(),+ handleTimelineElementDeleteOnly,+ });+ expect(handleTimelineElementDeleteOnly).toHaveBeenCalledWith(video);+ });++ it("leaves the key alone when no link item applies", () => {+ select([clip("title", "div")], "title");+ const event = key({ metaKey: true, key: "l" });+ expect(dispatchLinkShortcut(event, { handleLinkEdit: vi.fn() })).toBe(false);+ expect(event.preventDefault).not.toHaveBeenCalled();+ });+});diff --git a/packages/studio/src/hooks/linkShortcuts.ts b/packages/studio/src/hooks/linkShortcuts.tsnew file mode 100644index 0000000000..059ee8ff3a--- /dev/null+++ b/packages/studio/src/hooks/linkShortcuts.ts@@ -0,0 +1,41 @@+import { usePlayerStore } from "../player";+import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";+import { resolveLinkMenuItems } from "../player/components/clipMenuLinkItems";++export interface LinkShortcutCallbacks {+ handleLinkEdit?: TimelineEditCallbacks["onLinkEdit"];+ handleTimelineElementDeleteOnly?: TimelineEditCallbacks["onDeleteElementOnly"];+}++const isDeleteKey = (event: KeyboardEvent) => event.key === "Backspace" || event.key === "Delete";+const hasMod = (event: KeyboardEvent) => event.metaKey || event.ctrlKey;++const SHORTCUTS: ReadonlyArray<[string, (event: KeyboardEvent) => boolean]> = [+ ["⌘L", (e) => hasMod(e) && !e.altKey && !e.shiftKey && e.key.toLowerCase() === "l"],+ ["⌥⇧D", (e) => !hasMod(e) && e.altKey && e.shiftKey && e.code === "KeyD"],+ ["⌥⌫", (e) => !hasMod(e) && e.altKey && !e.shiftKey && isDeleteKey(e)],+];++function shortcutOf(event: KeyboardEvent): string | null {+ return SHORTCUTS.find(([, matches]) => matches(event))?.[0] ?? null;+}++/** ⌘L unlink/link, ⌥⇧D detach audio, ⌥⌫ delete one linked clip — the clip menu's shortcuts. */+export function dispatchLinkShortcut(event: KeyboardEvent, cb: LinkShortcutCallbacks): boolean {+ const shortcut = shortcutOf(event);+ if (!shortcut) return false;+ const { elements, selectedElementId, selectedElementIds } = usePlayerStore.getState();+ const element = elements.find((el) => (el.key ?? el.id) === selectedElementId);+ if (!element) return false;+ const item = resolveLinkMenuItems({+ element,+ elements,+ selectedKeys: selectedElementIds,+ onLinkEdit: cb.handleLinkEdit,+ onDeleteElementOnly: cb.handleTimelineElementDeleteOnly,+ }).find((candidate) => candidate.shortcut === shortcut);+ if (!item) return false;+ event.preventDefault();+ item.run();+ return true;+}diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts b/packages/studio/src/hooks/timelineLinkEditPlan.test.tsnew file mode 100644index 0000000000..0513e12a41--- /dev/null+++ b/packages/studio/src/hooks/timelineLinkEditPlan.test.ts@@ -0,0 +1,80 @@+// @vitest-environment happy-dom+import { describe, expect, it } from "vitest";+import type { TimelineElement } from "../player";+import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";++const clip = (id: string, tag: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({+ id,+ domId: id,+ tag,+ src: "talk.mp4",+ start: 2,+ duration: 6,+ track: tag === "audio" ? 1 : 0,+ ...extra,+});++const video = clip("talk", "video", { link: "lk-1", muted: true });+const audio = clip("talk-audio", "audio", { link: "lk-1" });+const title = clip("title", "div");++const SOURCE =+ '<div><video id="talk" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6"></video><audio id="talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-volume="0.5"></audio></div>';++describe("clipsToUnlink", () => {+ it("unlinks a lone removed member and its orphaned partner", () => {+ expect(clipsToUnlink([video], [video, audio, title]).map((el) => el.id)).toEqual([+ "talk",+ "talk-audio",+ ]);+ });++ it("keeps a three-member group linked when one leaves", () => {+ const third = clip("talk-2", "audio", { link: "lk-1" });+ expect(clipsToUnlink([video], [video, audio, third]).map((el) => el.id)).toEqual(["talk"]);+ });++ it("ignores unlinked clips", () => {+ expect(clipsToUnlink([title], [video, audio, title])).toEqual([]);+ });++ it("never reaches a same-id link in another source file", () => {+ const childVideo = clip("c", "video", { link: "lk-1", sourceFile: "child.html" });+ const removed = clipsToUnlink([video], [video, audio, childVideo]).map((el) => el.id);+ expect(removed).toEqual(["talk", "talk-audio"]);+ });+});++describe("planLinkEdit", () => {+ const elements = [video, audio, title];++ it("unlink strips data-link from both members", () => {+ const plan = planLinkEdit({ kind: "unlink", elements: [video, audio] }, elements);+ expect(plan?.label).toBe("Unlink clips");+ expect(plan?.transform(SOURCE)).not.toContain("data-link");+ });++ it("link writes one fresh id on both", () => {+ const unlinked = SOURCE.replaceAll(' data-link="lk-1"', "");+ const plan = planLinkEdit({ kind: "link", elements: [video, audio] }, elements);+ expect(plan?.transform(unlinked)?.match(/data-link="lk-1"/g)).toHaveLength(2);+ });++ it("merge folds the audio into the video", () => {+ const plan = planLinkEdit({ kind: "merge", video, audio }, elements);+ const merged = plan?.transform(SOURCE) ?? "";+ expect(merged).not.toContain("<audio");+ expect(merged).toContain('data-volume="0.5"');+ expect(merged).toContain('data-has-audio="true"');+ });++ it("detach puts the audio on the first free audio track", () => {+ const talk = clip("talk", "video", { hasAudio: true });+ const src =+ '<div><video id="talk" src="talk.mp4" data-has-audio="true" data-start="2" data-duration="6"></video></div>';+ const plan = planLinkEdit({ kind: "detach", element: talk }, [talk, title]);+ const out = plan?.transform(src) ?? "";+ expect(out).toContain('id="talk-audio"');+ expect(out).toContain('data-track-index="1"');+ });+});diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.ts b/packages/studio/src/hooks/timelineLinkEditPlan.tsnew file mode 100644index 0000000000..65b0c25f0d--- /dev/null+++ b/packages/studio/src/hooks/timelineLinkEditPlan.ts@@ -0,0 +1,86 @@+import type { TimelineElement } from "../player";+import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";+import { buildPatchTarget, type PatchTarget } from "./timelineEditingHelpers";+import { sharesLinkGroup } from "../player/components/audioClipLink";+import {+ detachAudioInSource,+ linkInSource,+ mergeAudioInSource,+ pickDetachedAudioTrack,+ setLinkInSource,+} from "../components/editor/mediaLinkEdits";++export interface LinkEditPlan {+ label: string;+ anchor: TimelineElement;+ transform: (source: string) => string | null;+}++const keyOf = (el: TimelineElement) => el.key ?? el.id;++function targetsOf(elements: readonly TimelineElement[]): PatchTarget[] | null {+ const targets = elements.map(buildPatchTarget);+ return targets.every((target): target is PatchTarget => target !== null) ? targets : null;+}++/**+ * The clips to strip `data-link` from when `removed` leave their groups: the+ * removed clips themselves, plus any partner left alone in its group.+ */+export function clipsToUnlink(+ removed: readonly TimelineElement[],+ elements: readonly TimelineElement[],+): TimelineElement[] {+ const removedKeys = new Set(removed.map(keyOf));+ const orphans = new Map<string, TimelineElement>();+ for (const leaving of removed) {+ const survivors = elements.filter(+ (el) => sharesLinkGroup(el, leaving) && !removedKeys.has(keyOf(el)),+ );+ if (survivors.length === 1 && survivors[0]) orphans.set(keyOf(survivors[0]), survivors[0]);+ }+ return [...removed.filter((el) => el.link), ...orphans.values()];+}++export function planLinkEdit(+ edit: TimelineLinkEdit,+ elements: readonly TimelineElement[],+): LinkEditPlan | null {+ switch (edit.kind) {+ case "unlink": {+ const members = clipsToUnlink(edit.elements, elements);+ const targets = targetsOf(members);+ const anchor = members[0];+ if (!targets || !anchor) return null;+ return { label: "Unlink clips", anchor, transform: (s) => setLinkInSource(s, targets, null) };+ }+ case "link": {+ const targets = targetsOf(edit.elements);+ const anchor = edit.elements[0];+ if (!targets || !anchor) return null;+ return { label: "Link clips", anchor, transform: (s) => linkInSource(s, targets) };+ }+ case "detach": {+ const target = buildPatchTarget(edit.element);+ if (!target) return null;+ const track = pickDetachedAudioTrack(elements, edit.element);+ return {+ label: "Detach audio",+ anchor: edit.element,+ transform: (s) =>+ detachAudioInSource(s, { target, videoId: edit.element.domId ?? null, track })?.html ??+ null,+ };+ }+ case "merge": {+ const videoTarget = buildPatchTarget(edit.video);+ const audioTarget = buildPatchTarget(edit.audio);+ if (!videoTarget || !audioTarget) return null;+ return {+ label: "Merge audio back into video",+ anchor: edit.video,+ transform: (s) => mergeAudioInSource(s, { videoTarget, audioTarget }),+ };+ }+ }+}diff --git a/packages/studio/src/hooks/timelineMoveAdapter.ts b/packages/studio/src/hooks/timelineMoveAdapter.tsindex ee7544e8ea..09665c039e 100644--- a/packages/studio/src/hooks/timelineMoveAdapter.ts+++ b/packages/studio/src/hooks/timelineMoveAdapter.ts@@ -1,3 +1,4 @@+import { useCallback } from "react";import type { TimelineElement } from "../player";import type {TimelineGroupCommitOptions,@@ -45,3 +46,15 @@ export function persistTimelineMoveEditsAtomically({ coalesceKey, coalesceMs },);}++export function useTimelineMoveEditsHandler(+ handleTimelineGroupMove: AtomicMoveDeps["handleTimelineGroupMove"],+): TimelineMoveEditsHandler {+ return useCallback(+ async (edits, coalesceKey, operation: TimelineMoveOperation = "timing", coalesceMs) => {+ const deps = { handleTimelineGroupMove };+ await persistTimelineMoveEditsAtomically(edits, coalesceKey, operation, deps, coalesceMs);+ },+ [handleTimelineGroupMove],+ );+}diff --git a/packages/studio/src/hooks/useAppHotkeys.ts b/packages/studio/src/hooks/useAppHotkeys.tsindex 69b07f43ba..78f455dabb 100644--- a/packages/studio/src/hooks/useAppHotkeys.ts+++ b/packages/studio/src/hooks/useAppHotkeys.ts@@ -2,6 +2,8 @@ import { useCallback, useEffect, useRef } from "react";import { usePlayerStore } from "../player";import type { TimelineElement } from "../player";import type { DomEditSelection } from "../components/editor/domEditing";+import { isTypingTarget } from "../utils/typingTarget";+import { dispatchLinkShortcut, type LinkShortcutCallbacks } from "./linkShortcuts";import { useCaptionStore } from "../captions/store";import {applyCaptionModelToIframe,@@ -71,6 +73,8 @@ function tryApplyBeatHistory(interface UseAppHotkeysParams {handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;+ handleLinkEdit?: LinkShortcutCallbacks["handleLinkEdit"];+ handleTimelineElementDeleteOnly?: LinkShortcutCallbacks["handleTimelineElementDeleteOnly"];handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;handleDomEditElementDelete: (selection: DomEditSelection,@@ -114,6 +118,8 @@ interface UseAppHotkeysParams {export function useAppHotkeys({handleTimelineElementsDelete,+ handleLinkEdit,+ handleTimelineElementDeleteOnly,handleTimelineElementSplit,handleDomEditElementDelete,domEditSelectionRef,@@ -192,6 +198,8 @@ export function useAppHotkeys({const cbRef = useRef<HotkeyCallbacks>(null!);cbRef.current = {handleTimelineElementsDelete,+ handleLinkEdit,+ handleTimelineElementDeleteOnly,handleTimelineElementSplit,handleDomEditElementDelete,handleUndo,@@ -215,6 +223,7 @@ export function useAppHotkeys({const handleAppKeyDown = useCallback((event: KeyboardEvent) => {const cb = cbRef.current;const key = event.key.toLowerCase();+ if (!isTypingTarget(event.target) && dispatchLinkShortcut(event, cb)) return;if (event.metaKey || event.ctrlKey) {dispatchModifierKey(event, key, cb);return;diff --git a/packages/studio/src/hooks/useRazorSplit.test.tsx b/packages/studio/src/hooks/useRazorSplit.test.tsxindex feb25bf4f5..d5475ec9f3 100644--- a/packages/studio/src/hooks/useRazorSplit.test.tsx+++ b/packages/studio/src/hooks/useRazorSplit.test.tsx@@ -95,3 +95,51 @@ describe("useRazorSplit mutation versions", () => {container.remove();});});++describe("useRazorSplit linked clips", () => {+ afterEach(() => vi.restoreAllMocks());++ it("splits every member of a linked pair in one cut", async () => {+ const { usePlayerStore } = await import("../player");+ const clip = (id: string, tag: string): TimelineElement => ({+ id,+ domId: id,+ tag,+ start: 0,+ duration: 4,+ track: tag === "audio" ? 1 : 0,+ link: "lk-1",+ });+ const video = clip("talk", "video");+ usePlayerStore.getState().setElements([video, clip("talk-audio", "audio")]);+ const bodies: string[] = [];+ vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {+ const url = String(input);+ if (url.includes("/files/")) return jsonResponse({ content: "", version: '"v0"' });+ bodies.push(String(init?.body ?? ""));+ return jsonResponse({ error: "stop" }, 409);+ });+ let split: ((element: TimelineElement, splitTime: number) => Promise<void>) | undefined;+ const root = createRoot(document.body.appendChild(document.createElement("div")));+ function Harness() {+ split = useRazorSplit({+ projectId: "p1",+ activeCompPath: "index.html",+ showToast: vi.fn(),+ writeProjectFile: vi.fn(),+ recordEdit: vi.fn(),+ reloadPreview: vi.fn(),+ }).handleRazorSplit;+ return null;+ }+ await act(async () => root.render(React.createElement(Harness)));+ await act(async () => {+ await split?.(video, 2);+ });+ const targets = JSON.parse(bodies[0] ?? "{}").files[0].targets.map(+ (cut: { originalId: string }) => cut.originalId,+ );+ expect(targets).toEqual(["talk", "talk-audio"]);+ act(() => root.unmount());+ });+});diff --git a/packages/studio/src/hooks/useRazorSplit.ts b/packages/studio/src/hooks/useRazorSplit.tsindex d392063fc7..29b9113c01 100644--- a/packages/studio/src/hooks/useRazorSplit.ts+++ b/packages/studio/src/hooks/useRazorSplit.ts@@ -4,6 +4,7 @@ import { usePlayerStore } from "../player";import { getTimelineElementLabel } from "../utils/studioHelpers";import { trackStudioRazorSplit } from "../telemetry/events";import { canSplitElementAt, selectSplittableElements } from "../utils/timelineElementSplit";+import { linkedMembersOf } from "../player/components/audioClipLink";import { buildAtomicCutIntents, runAtomicCutTransaction } from "../utils/razorSplitTransaction";import type { RecordEditInput } from "./timelineEditingHelpers";import { useFreezeFrame } from "./useFreezeFrame";@@ -103,7 +104,12 @@ export function useRazorSplit({}if (!canSplitElementAt(element, splitTime)) return;try {- const result = await runCut([element], splitTime, "single");+ const members = linkedMembersOf(element, usePlayerStore.getState().elements);+ const result = await runCut(+ members.filter((member) => canSplitElementAt(member, splitTime)),+ splitTime,+ "single",+ );if (!result) return;if (result.syncFailed) return;showToast(`Split ${getTimelineElementLabel(element)} at ${splitTime.toFixed(2)}s`, "info");diff --git a/packages/studio/src/hooks/useRenderClipContent.test.ts b/packages/studio/src/hooks/useRenderClipContent.test.tsindex f03b43c52c..0edcc303c0 100644--- a/packages/studio/src/hooks/useRenderClipContent.test.ts+++ b/packages/studio/src/hooks/useRenderClipContent.test.ts@@ -196,7 +196,7 @@ describe("useRenderClipContent", () => {}});- it("marks audio linked when a video clip uses the same file, and muted when hidden", () => {+ it("marks audio linked by data-link, and muted when hidden", () => {usePlayerStore.setState({thumbnailMode: "hidden",elements: [@@ -217,6 +217,7 @@ describe("useRenderClipContent", () => {duration: 4,track: 1,src: "assets/clip.mp4",+ link: "lk-1",hidden: true,});expect(isValidElement<{ linked: boolean; muted: boolean }>(linked)).toBe(true);diff --git a/packages/studio/src/hooks/useTimelineDeleteOps.ts b/packages/studio/src/hooks/useTimelineDeleteOps.tsindex 0503d9705f..79ec4baee7 100644--- a/packages/studio/src/hooks/useTimelineDeleteOps.ts+++ b/packages/studio/src/hooks/useTimelineDeleteOps.ts@@ -10,6 +10,7 @@ import { studioWriteHeaders } from "../utils/studioFileVersion";import { getTimelineElementLabel } from "../utils/studioHelpers";import { buildPatchTarget, removeIframeTimelineElements } from "./timelineEditingHelpers";import { captureDurationRollback } from "./timelineTimingSync";+import { setLinkInSource } from "../components/editor/mediaLinkEdits";import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";import {@@ -60,6 +61,11 @@ interface UseTimelineDeleteOpsOptions {// timelineGapCommit.ts.let deleteGestureSeq = 0;+function unlinkInSource(source: string, survivors: readonly TimelineElement[]): string {+ const targets = survivors.map(buildPatchTarget).filter((target) => target !== null);+ return targets.length > 0 ? setLinkInSource(source, targets, null) : source;+}+export function useTimelineDeleteOps({projectIdRef,activeCompPath,@@ -80,7 +86,7 @@ export function useTimelineDeleteOps({// fallow-ignore-next-line complexityconst handleTimelineElementsDelete = useCallback(// fallow-ignore-next-line complexity- async (selection: TimelineElement[]) => {+ async (selection: TimelineElement[], alsoUnlink: readonly TimelineElement[] = []) => {if (isRecordingRef?.current) {showToast("Cannot edit timeline while recording", "error");return;@@ -150,9 +156,9 @@ export function useTimelineDeleteOps({// Shrink to the furthest remaining clip end, read from the post-removal source:// store durations are runtime-truncated.const deleteContentEnd = furthestClipEndFromSource(removedContent);- const patchedContent = setCompositionDurationToContent(- removedContent,- deleteContentEnd,+ const patchedContent = unlinkInSource(+ setCompositionDurationToContent(removedContent, deleteContentEnd),+ alsoUnlink,);// Optimistically reflect the shrunk length in the readout/seek bar,// rolling it back if the persist below fails (see captureDurationRollback).diff --git a/packages/studio/src/hooks/useTimelineEditGuard.ts b/packages/studio/src/hooks/useTimelineEditGuard.tsnew file mode 100644index 0000000000..b417a9723b--- /dev/null+++ b/packages/studio/src/hooks/useTimelineEditGuard.ts@@ -0,0 +1,54 @@+import { useCallback, useRef } from "react";+import type { TimelineElement } from "../player";+import { useTimelineEditRefusal } from "./timelineEditPermission";++type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;+type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];+type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;++interface GuardedTimelineEntry {+ resolveTargets: GuardedTimelineResolver;+ onRefused?: GuardedTimelineRefusal;+ wrapped: GuardedTimelineHandler;+}++export function useTimelineEditGuard(+ canEdit: Parameters<typeof useTimelineEditRefusal>[0],+ showToast: Parameters<typeof useTimelineEditRefusal>[1],+) {+ const refuseEdit = useTimelineEditRefusal(canEdit, showToast);+ const refuseEditRef = useRef(refuseEdit);+ refuseEditRef.current = refuseEdit;+ const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());+ // Refuses (no call, no write, no history entry) when any target is+ // blocked; otherwise runs fn as before. Cached by fn identity — like+ // track() — so a fresh closure here doesn't defeat track's own cache.+ const guard = useCallback(+ <H extends (...args: never[]) => Promise<unknown>>(+ resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],+ fn: H,+ onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,+ ): H => {+ const key = fn as unknown as GuardedTimelineHandler;+ const cached = guardedRef.current.get(key);+ if (cached) {+ cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;+ cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;+ return cached.wrapped as H;+ }+ const entry = {} as GuardedTimelineEntry;+ entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;+ entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;+ entry.wrapped = ((...args: Parameters<H>) => {+ const reason = refuseEditRef.current(entry.resolveTargets(...(args as never[])));+ if (reason !== null)+ return Promise.resolve(entry.onRefused?.(reason, ...(args as never[])));+ return fn(...args);+ }) as H as unknown as GuardedTimelineHandler;+ guardedRef.current.set(key, entry);+ return entry.wrapped as H;+ },+ [],+ );+ return guard;+}diff --git a/packages/studio/src/hooks/useTimelineEditing.ts b/packages/studio/src/hooks/useTimelineEditing.tsindex 8c6b69d711..c4103daad8 100644--- a/packages/studio/src/hooks/useTimelineEditing.ts+++ b/packages/studio/src/hooks/useTimelineEditing.ts@@ -27,6 +27,12 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";import { useSetElementAttribute } from "./timelineElementFxAttribute";import { useTimelineDeleteOps } from "./useTimelineDeleteOps";+import { useTimelineEditGuard } from "./useTimelineEditGuard";+import {+ linkEditTargets,+ useTimelineLinkEditing,+ withLinkPartners,+} from "./useTimelineLinkEditing";import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";import {@@ -35,26 +41,12 @@ import {} from "./timelineTrackVisibility";import { useTimelineGroupEditing } from "./useTimelineGroupEditing";import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";-import {- useTimelineEditGate,- useTimelineEditRefusal,- type TimelineEditOutcome,-} from "./timelineEditPermission";+import { useTimelineEditGate, type TimelineEditOutcome } from "./timelineEditPermission";import { serializeZLaneGesture } from "../components/nle/zLaneGesture";import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";-type GuardedTimelineHandler = (...args: never[]) => Promise<unknown>;-type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];-type GuardedTimelineRefusal = (reason: string, ...args: never[]) => unknown;--interface GuardedTimelineEntry {- resolveTargets: GuardedTimelineResolver;- onRefused?: GuardedTimelineRefusal;- wrapped: GuardedTimelineHandler;-}-export function useTimelineEditing({projectId,activeCompPath,@@ -80,40 +72,7 @@ export function useTimelineEditing({const editQueueRef = useRef(Promise.resolve());const track = useTrackPendingTimelineEdit();const checkEditable = useTimelineEditGate(canEdit, showToast);- const refuseEdit = useTimelineEditRefusal(canEdit, showToast);- const refuseEditRef = useRef(refuseEdit);- refuseEditRef.current = refuseEdit;- const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());- // Refuses (no call, no write, no history entry) when any target is- // blocked; otherwise runs fn as before. Cached by fn identity — like- // track() — so a fresh closure here doesn't defeat track's own cache.- const guard = useCallback(- <H extends (...args: never[]) => Promise<unknown>>(- resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],- fn: H,- onRefused?: (reason: string, ...args: Parameters<H>) => Awaited<ReturnType<H>>,- ): H => {- const key = fn as unknown as GuardedTimelineHandler;- const cached = guardedRef.current.get(key);- if (cached) {- cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;- cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;- return cached.wrapped as H;- }- const entry = {} as GuardedTimelineEntry;- entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;- entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;- entry.wrapped = ((...args: Parameters<H>) => {- const reason = refuseEditRef.current(entry.resolveTargets(...(args as never[])));- if (reason !== null)- return Promise.resolve(entry.onRefused?.(reason, ...(args as never[])));- return fn(...args);- }) as H as unknown as GuardedTimelineHandler;- guardedRef.current.set(key, entry);- return entry.wrapped as H;- },- [],- );+ const guard = useTimelineEditGuard(canEdit, showToast);const enqueueEdit = useCallback((@@ -252,7 +211,7 @@ export function useTimelineEditing({return reorderDone.then(() => {// SDK setTiming writes start only; a lane change needs the fallback's track patch.- if (sdkSession && element.hfId && !needsExtension && !trackChanged) {+ if (sdkSession && element.hfId && !element.link && !needsExtension && !trackChanged) {return sdkTimingPersist(element.hfId,targetPath,@@ -359,7 +318,7 @@ export function useTimelineEditing({finishResizeGsapSync(),);const persistDone =- sdkSession && element.hfId && !hasPbsAdjustment && !needsExtension+ sdkSession && element.hfId && !element.link && !hasPbsAdjustment && !needsExtension? sdkTimingPersist(element.hfId,targetPath,@@ -461,7 +420,7 @@ export function useTimelineEditing({isRecordingRef,});- const { handleTimelineElementsDelete, handleTimelineElementDelete } = useTimelineDeleteOps({+ const { handleTimelineElementsDelete } = useTimelineDeleteOps({projectIdRef,activeCompPath,timelineElements,@@ -491,6 +450,20 @@ export function useTimelineEditing({checkEditable,});+ const linkEditing = useTimelineLinkEditing({+ projectIdRef,+ activeCompPath,+ editQueueRef,+ pendingTimelineEditPathRef,+ isRecordingRef,+ showToast,+ writeProjectFile,+ recordEdit,+ reloadPreview,+ forceReloadSdkSession,+ handleTimelineElementsDelete,+ });+const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);const { handleRazorSplit, handleRazorSplitAll, handleFreezeFrame } = useRazorSplit({projectId,@@ -526,7 +499,9 @@ export function useTimelineEditing({// Every write-handler is tracked here, the one place all hand edits// converge, so undo never races a write; canEdit gates the same point.// Coverage boundary: see the PR body, not every kind resolves an element.- const trackedRazorSplit = track(guard((element) => [element], handleRazorSplit));+ const trackedRazorSplit = track(+ guard((element) => withLinkPartners([element]), handleRazorSplit),+ );return {handleTimelineElementMove: track(guard((element) => [element], handleTimelineElementMove)),handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),@@ -568,10 +543,16 @@ export function useTimelineEditing({),),},- handleTimelineElementDelete: track(guard((element) => [element], handleTimelineElementDelete)),+ handleTimelineElementDelete: track(+ guard((element) => withLinkPartners([element]), linkEditing.handleLinkedElementDelete),+ ),handleTimelineElementsDelete: track(- guard((elements) => elements, handleTimelineElementsDelete),+ guard(withLinkPartners, linkEditing.handleLinkedElementsDelete),+ ),+ handleTimelineElementDeleteOnly: track(+ guard((element) => [element], linkEditing.handleDeleteElementOnly),),+ handleLinkEdit: track(guard(linkEditTargets, linkEditing.handleLinkEdit)),handleTimelineElementSplit: trackedRazorSplit,handleRazorSplit: trackedRazorSplit,handleFreezeFrame: track(guard((element) => [element], handleFreezeFrame)),diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsxnew file mode 100644index 0000000000..06808aec51--- /dev/null+++ b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx@@ -0,0 +1,97 @@+// @vitest-environment happy-dom+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 { useTimelineLinkEditing, withLinkPartners } from "./useTimelineLinkEditing";++(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;++const clip = (id: string, tag: string, link?: string): TimelineElement => ({+ id,+ domId: id,+ tag,+ start: 0,+ duration: 4,+ track: 0,+ ...(link ? { link } : {}),+});+const video = clip("talk", "video", "lk-1");+const audio = clip("talk-audio", "audio", "lk-1");+const title = clip("title", "div");++const SOURCE =+ '<div><video id="talk" muted data-link="lk-1"></video><audio id="talk-audio" data-link="lk-1"></audio></div>';++async function renderLinkEditing(handleTimelineElementsDelete = vi.fn()) {+ usePlayerStore.getState().setElements([video, audio, title]);+ const writeProjectFile = vi.fn().mockResolvedValue(undefined);+ const recordEdit = vi.fn().mockResolvedValue(undefined);+ let api: ReturnType<typeof useTimelineLinkEditing> | undefined;+ function Harness() {+ api = useTimelineLinkEditing({+ projectIdRef: { current: "p1" },+ activeCompPath: "index.html",+ editQueueRef: { current: Promise.resolve() },+ pendingTimelineEditPathRef: { current: new Set() },+ showToast: vi.fn(),+ writeProjectFile,+ recordEdit,+ reloadPreview: vi.fn(),+ handleTimelineElementsDelete,+ });+ return null;+ }+ const root = createRoot(document.body.appendChild(document.createElement("div")));+ await act(async () => root.render(React.createElement(Harness)));+ if (!api) throw new Error("hook did not render");+ return { api, writeProjectFile, recordEdit, unmount: () => act(() => root.unmount()) };+}++describe("withLinkPartners", () => {+ it("adds partners after the selection, once", () => {+ usePlayerStore.getState().setElements([video, audio, title]);+ expect(withLinkPartners([video, title]).map((el) => el.id)).toEqual([+ "talk",+ "title",+ "talk-audio",+ ]);+ expect(withLinkPartners([video, audio])).toHaveLength(2);+ });+});++describe("useTimelineLinkEditing", () => {+ afterEach(() => vi.restoreAllMocks());++ it("deletes a linked clip with its partner", async () => {+ const del = vi.fn().mockResolvedValue(undefined);+ const { api, unmount } = await renderLinkEditing(del);+ await act(async () => api.handleLinkedElementDelete(video));+ expect(del.mock.calls[0]?.[0].map((el: TimelineElement) => el.id)).toEqual([+ "talk",+ "talk-audio",+ ]);+ unmount();+ });++ it("delete-only removes one member and unlinks the survivor", async () => {+ const del = vi.fn().mockResolvedValue(undefined);+ const { api, unmount } = await renderLinkEditing(del);+ await act(async () => api.handleDeleteElementOnly(video));+ expect(del).toHaveBeenCalledWith([video], [audio]);+ unmount();+ });++ it("unlink writes one undo step removing data-link from both", async () => {+ vi.spyOn(globalThis, "fetch").mockResolvedValue(+ new Response(JSON.stringify({ content: SOURCE }), { status: 200 }),+ );+ const { api, writeProjectFile, recordEdit, unmount } = await renderLinkEditing();+ await act(async () => api.handleLinkEdit({ kind: "unlink", elements: [video, audio] }));+ expect(writeProjectFile).toHaveBeenCalledTimes(1);+ expect(writeProjectFile.mock.calls[0]?.[1]).not.toContain("data-link");+ expect(recordEdit).toHaveBeenCalledTimes(1);+ expect(recordEdit.mock.calls[0]?.[0].label).toBe("Unlink clips");+ unmount();+ });+});diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.ts b/packages/studio/src/hooks/useTimelineLinkEditing.tsnew file mode 100644index 0000000000..b8fadcd919--- /dev/null+++ b/packages/studio/src/hooks/useTimelineLinkEditing.ts@@ -0,0 +1,143 @@+import { useCallback, type MutableRefObject } from "react";+import { usePlayerStore, type TimelineElement } from "../player";+import type { TimelineLinkEdit } from "../player/components/timelineCallbacks";+import { expandToLinkedMembers } from "../player/components/audioClipLink";+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";+import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";+import { readFileContent } from "./timelineEditingHelpers";+import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";++interface UseTimelineLinkEditingOptions {+ projectIdRef: MutableRefObject<string | null>;+ activeCompPath: string | null;+ editQueueRef: MutableRefObject<Promise<void>>;+ pendingTimelineEditPathRef: MutableRefObject<Set<string>>;+ isRecordingRef?: MutableRefObject<boolean>;+ showToast: (message: string, tone?: "error" | "info") => void;+ writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;+ recordEdit: (input: RecordEditInput) => Promise<void>;+ reloadPreview: () => void;+ forceReloadSdkSession?: () => void;+ handleTimelineElementsDelete: (+ selection: TimelineElement[],+ alsoUnlink?: readonly TimelineElement[],+ ) => Promise<void>;+}++const keyOf = (el: TimelineElement) => el.key ?? el.id;++/** Every clip a link edit writes, for the edit-permission gate. */+export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {+ switch (edit.kind) {+ case "unlink":+ case "link":+ return [...edit.elements];+ case "detach":+ return [edit.element];+ case "merge":+ return [edit.video, edit.audio];+ }+}++export function withLinkPartners(selection: readonly TimelineElement[]): TimelineElement[] {+ const elements = usePlayerStore.getState().elements;+ const keys = expandToLinkedMembers(selection.map(keyOf), elements);+ const known = new Set(selection.map(keyOf));+ return [...selection, ...elements.filter((el) => keys.has(keyOf(el)) && !known.has(keyOf(el)))];+}++export function useTimelineLinkEditing({+ projectIdRef,+ activeCompPath,+ editQueueRef,+ pendingTimelineEditPathRef,+ isRecordingRef,+ showToast,+ writeProjectFile,+ recordEdit,+ reloadPreview,+ forceReloadSdkSession,+ handleTimelineElementsDelete,+}: UseTimelineLinkEditingOptions) {+ const handleLinkEdit = useCallback(+ async (edit: TimelineLinkEdit) => {+ if (isRecordingRef?.current) {+ showToast("Cannot edit timeline while recording", "error");+ return;+ }+ const pid = projectIdRef.current;+ const plan = planLinkEdit(edit, usePlayerStore.getState().elements);+ if (!pid || !plan) return;+ const path = plan.anchor.sourceFile || activeCompPath || "index.html";+ pendingTimelineEditPathRef.current.add(path);+ const queued = editQueueRef.current.then(() =>+ saveProjectFilesWithHistory({+ projectId: pid,+ label: plan.label,+ files: {+ [path]: (current) => {+ const next = plan.transform(current);+ if (next === null || next === current) {+ throw new Error(`Couldn't ${plan.label.toLowerCase()}`);+ }+ return next;+ },+ },+ readFile: (filePath) => readFileContent(pid, filePath),+ writeFile: writeProjectFile,+ recordEdit,+ }),+ );+ editQueueRef.current = queued.then(+ () => undefined,+ () => undefined,+ );+ try {+ await queued;+ forceReloadSdkSession?.();+ reloadPreview();+ } catch (error) {+ showToast(getStudioSaveErrorMessage(error), "error");+ }+ },+ [+ activeCompPath,+ editQueueRef,+ forceReloadSdkSession,+ isRecordingRef,+ pendingTimelineEditPathRef,+ projectIdRef,+ recordEdit,+ reloadPreview,+ showToast,+ writeProjectFile,+ ],+ );++ const handleLinkedElementsDelete = useCallback(+ (selection: TimelineElement[]) => handleTimelineElementsDelete(withLinkPartners(selection)),+ [handleTimelineElementsDelete],+ );++ const handleLinkedElementDelete = useCallback(+ (element: TimelineElement) => handleTimelineElementsDelete(withLinkPartners([element])),+ [handleTimelineElementsDelete],+ );++ const handleDeleteElementOnly = useCallback(+ (element: TimelineElement) => {+ const orphans = clipsToUnlink([element], usePlayerStore.getState().elements).filter(+ (el) => keyOf(el) !== keyOf(element),+ );+ return handleTimelineElementsDelete([element], orphans);+ },+ [handleTimelineElementsDelete],+ );++ return {+ handleLinkEdit,+ handleLinkedElementsDelete,+ handleLinkedElementDelete,+ handleDeleteElementOnly,+ };+}diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsxindex 723e3f455c..7aef774d9c 100644--- a/packages/studio/src/player/components/ClipContextMenu.tsx+++ b/packages/studio/src/player/components/ClipContextMenu.tsx@@ -7,6 +7,7 @@ import { useMenuKeyboardNav } from "./menuKeyboardNav";import type { TimelineClipMenuItem } from "./TimelineTypes";import { ClipMenuToolItems } from "./clipMenuToolItems";import { ClipMenuAudioItems } from "./clipMenuAudioItems";+import { ClipMenuLinkItems } from "./clipMenuLinkItems";interface ClipContextMenuProps {x: number;@@ -157,6 +158,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({)}<ClipMenuAudioItems element={element} onClose={onClose} />+ <ClipMenuLinkItems element={element} onClose={onClose} />{(onCopy || onPaste || onDuplicate) && (<>diff --git a/packages/studio/src/player/components/audioClipLink.test.ts b/packages/studio/src/player/components/audioClipLink.test.tsindex 1a1196bab9..42f5743dde 100644--- a/packages/studio/src/player/components/audioClipLink.test.ts+++ b/packages/studio/src/player/components/audioClipLink.test.ts@@ -1,34 +1,204 @@+// @vitest-environment happy-domimport { describe, expect, it } from "vitest";-import { audioPillFlags, isLinkedVideoAudio } from "./audioClipLink";--const audio = { id: "bed", tag: "audio", src: "assets/City Ride.mp4?v=2" };--describe("isLinkedVideoAudio", () => {- it("links an audio pill to a video of the same file", () => {- expect(- isLinkedVideoAudio(audio, [- audio,- { id: "picture", tag: "video", src: "/preview/assets/city ride.mp4" },- ]),- ).toBe(true);- });-- it("greys a hidden clip and a muted group without dropping the link", () => {- expect(audioPillFlags({ ...audio, hidden: true }, [])).toEqual({- muted: true,- linked: false,- });- expect(audioPillFlags({ ...audio, audioGroupHidden: true }, [])).toEqual({- muted: true,- linked: false,- });- });-- it("leaves a standalone audio file unlinked", () => {- expect(- isLinkedVideoAudio({ id: "vo", tag: "audio", src: "assets/voice.wav" }, [- { id: "picture", tag: "video", src: "assets/city.mp4" },- ]),- ).toBe(false);+import {+ audioPillFlags,+ expandToLinkedMembers,+ linkedGestureKeys,+ linkedMembersOf,+ mediaAssetIdentity,+} from "./audioClipLink";+import { createTimelineElementFromManifestClip, parseTimelineFromDOM } from "../lib/timelineDOM";++const video = { id: "talk", link: "lk-1" };+const audio = { id: "talk-audio", link: "lk-1" };+const other = { id: "music", link: "lk-2" };+const otherAudio = { id: "music-audio", link: "lk-2" };+const plain = { id: "title" };+const elements = [video, audio, other, otherAudio, plain];++describe("audioPillFlags", () => {+ it("is linked only by data-link, never by a shared file name", () => {+ expect(audioPillFlags({ link: "lk-1" }).linked).toBe(true);+ expect(audioPillFlags({}).linked).toBe(false);+ });++ it("greys a hidden clip and a muted group", () => {+ expect(audioPillFlags({ hidden: true }).muted).toBe(true);+ expect(audioPillFlags({ audioGroupHidden: true }).muted).toBe(true);+ });+});++describe("mediaAssetIdentity", () => {+ it("tells same-named files in different folders apart", () => {+ expect(mediaAssetIdentity({ src: "assets/one/talk.mp4" })).not.toBe(+ mediaAssetIdentity({ src: "assets/two/talk.mp4" }),+ );+ });++ it("resolves a src against its own source file and drops query and hash", () => {+ expect(mediaAssetIdentity({ src: "../assets/talk.mp4?v=2", sourceFile: "scenes/a.html" })).toBe(+ mediaAssetIdentity({ src: "./assets/talk.mp4#t=1" }),+ );+ expect(mediaAssetIdentity({ src: "assets/City%20Ride.mp4" })).toBe(+ mediaAssetIdentity({ src: "assets/City Ride.mp4" }),+ );+ expect(mediaAssetIdentity({ src: "" })).toBeNull();+ });++ it("keeps a remote url's query, since it can select a different file", () => {+ expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1" })).not.toBe(+ mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=2" }),+ );+ expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a%26x=b" })).not.toBe(+ mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a&x=b" }),+ );+ expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4%3Fclip=a" })).not.toBe(+ mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a" }),+ );+ expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1#t=3" })).toBe(+ mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1" }),+ );+ });+});++describe("expandToLinkedMembers", () => {+ it("adds every partner of a linked clip", () => {+ expect(expandToLinkedMembers(["talk"], elements)).toEqual(new Set(["talk", "talk-audio"]));+ });++ it("leaves unlinked clips alone and does not pull in other groups", () => {+ expect(expandToLinkedMembers(["title"], elements)).toEqual(new Set(["title"]));+ expect(expandToLinkedMembers(["talk-audio", "title"], elements)).toEqual(+ new Set(["talk-audio", "talk", "title"]),+ );+ });++ it("prefers the store key over the id", () => {+ const keyed = [+ { id: "a", key: "k-a", link: "lk-9" },+ { id: "b", key: "k-b", link: "lk-9" },+ ];+ expect(expandToLinkedMembers(["k-a"], keyed)).toEqual(new Set(["k-a", "k-b"]));+ });+});++describe("link groups stay inside their composition", () => {+ const root = [+ { id: "v", link: "lk-1", sourceFile: undefined },+ { id: "a", link: "lk-1", sourceFile: undefined },+ ];+ const child = [+ { id: "cv", key: "child.html#cv", link: "lk-1", sourceFile: "child.html" },+ { id: "ca", key: "child.html#ca", link: "lk-1", sourceFile: "child.html" },+ ];+ const all = [...root, ...child];++ it("does not pull a child file's same-id link into the root group", () => {+ expect(linkedMembersOf(root[0] ?? video, all).map((el) => el.id)).toEqual(["v", "a"]);+ expect(expandToLinkedMembers(["child.html#cv"], all)).toEqual(+ new Set(["child.html#cv", "child.html#ca"]),+ );+ });++ const media = (id: string, tag: string, start: number) =>+ `<${tag} id="${id}" class="clip" src="${id}.mp4" data-link="lk-1" data-start="${start}" data-duration="4"></${tag}>`;+ const inlineDoc = () => {+ const doc = document.implementation.createHTMLDocument();+ doc.body.innerHTML = `<div data-composition-id="main" data-duration="20">+ ${media("v", "video", 0)}${media("a", "audio", 0)}+ <div id="child" data-composition-id="child" data-start="0" data-duration="10">+ ${media("cv", "video", 5)}${media("ca", "audio", 5)}+ </div>+ </div>`;+ return doc;+ };++ it("does not pull an inline composition's same-id link into the root group", () => {+ const rows = parseTimelineFromDOM(inlineDoc(), 20).filter((row) => row.link);+ const byId = (id: string) => rows.find((row) => row.domId === id) ?? video;+ expect(linkedMembersOf(byId("v"), rows).map((row) => row.domId)).toEqual(["v", "a"]);+ expect(linkedMembersOf(byId("cv"), rows).map((row) => row.domId)).toEqual(["cv", "ca"]);+ });++ it("keeps the inline composition apart on rows built from the runtime manifest", () => {+ const doc = inlineDoc();+ const rows = ["v", "a", "cv", "ca"].map((id, fallbackIndex) =>+ createTimelineElementFromManifestClip({+ clip: {+ ...{ id, label: id, start: 0, duration: 4, track: 0, kind: "video", tagName: "video" },+ ...{+ compositionId: null,+ parentCompositionId: null,+ compositionSrc: null,+ assetUrl: null,+ },+ },+ fallbackIndex,+ doc,+ hostEl: doc.getElementById(id),+ }),+ );+ const [rootVideo] = rows;+ expect(linkedMembersOf(rootVideo ?? video, rows).map((row) => row.domId)).toEqual(["v", "a"]);+ });+});++describe("linkedMembersOf", () => {+ it("returns the group, or the clip alone when unlinked", () => {+ expect(linkedMembersOf(video, elements).map((el) => el.id)).toEqual(["talk", "talk-audio"]);+ expect(linkedMembersOf(plain, elements)).toEqual([plain]);+ });+});++describe("linkedGestureKeys", () => {+ it("drags an unselected linked clip with its partner", () => {+ expect(linkedGestureKeys(new Set(["title"]), video, elements, false)).toEqual(+ new Set(["talk", "talk-audio"]),+ );+ });++ it("keeps a selection that holds the grabbed clip and adds partners", () => {+ expect(linkedGestureKeys(new Set(["talk", "title"]), video, elements, false)).toEqual(+ new Set(["talk", "talk-audio", "title"]),+ );+ });++ it("Alt edits the grabbed clip alone", () => {+ expect(linkedGestureKeys(new Set(["talk", "talk-audio"]), video, elements, true)).toEqual(+ new Set(["talk"]),+ );+ });+});++describe("selectClipWithLinks", () => {+ const linkedPair = [+ { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },+ { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },+ { id: "title", tag: "div", start: 0, duration: 4, track: 2 },+ ];++ async function store() {+ const { usePlayerStore } = await import("../store/playerStore");+ const { selectClipWithLinks } = await import("./timelineLinkSelection");+ usePlayerStore.getState().setElements(linkedPair);+ const click = (key: string, alt = false) =>+ selectClipWithLinks(key, alt, usePlayerStore.getState().setSelectedElementId);+ return { usePlayerStore, click };+ }++ it("a click selects the whole pair; Alt-click then narrows to one member", async () => {+ const { usePlayerStore, click } = await store();+ click("talk");+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk", "talk-audio"]));+ click("talk-audio", true);+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk-audio"]));+ });++ it("a plain click collapses a larger selection to the clicked clip's link group", async () => {+ const { usePlayerStore, click } = await store();+ usePlayerStore.getState().setSelection(["talk", "talk-audio", "title"], "title");+ click("talk");+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk", "talk-audio"]));+ expect(usePlayerStore.getState().selectedElementId).toBe("talk");});});diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.tsindex f3a17993c0..ee6cdc338f 100644--- a/packages/studio/src/player/components/audioClipLink.ts+++ b/packages/studio/src/player/components/audioClipLink.ts@@ -1,33 +1,76 @@-import type { TimelineElement } from "../store/timelineElement";+import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";-function mediaFileKey(src: string | undefined): string | null {+type LinkScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;+type LinkedElement = Pick<TimelineElement, "id" | "key" | "link"> & LinkScoped;++const keyOf = (element: Pick<TimelineElement, "id" | "key">) => element.key ?? element.id;++const SOURCE_BASE = "https://project.invalid/";+const SOURCE_ORIGIN = new URL(SOURCE_BASE).origin;++export function mediaAssetIdentity(+ element: Pick<TimelineElement, "src" | "sourceFile">,+): string | null {+ const src = element.src?.trim();if (!src) return null;- const path = src.split(/[?#]/, 1)[0] ?? "";- const segment = path.split(/[/\\]/).pop()?.trim().toLowerCase() ?? "";- return segment.length > 0 ? segment : null;+ try {+ const url = new URL(src, new URL(element.sourceFile ?? "index.html", SOURCE_BASE));+ if (url.origin !== SOURCE_ORIGIN) return `${url.origin}${url.pathname}${url.search}`;+ return decodeURIComponent(`${url.origin}${url.pathname}`);+ } catch {+ return null;+ }+}++function isLinked(element: Pick<TimelineElement, "link">): boolean {+ return typeof element.link === "string" && element.link.length > 0;+}++export function sharesLinkGroup(+ a: Pick<TimelineElement, "link"> & LinkScoped,+ b: Pick<TimelineElement, "link"> & LinkScoped,+): boolean {+ return isLinked(a) && a.link === b.link && sameCompositionScope(a, b);}export function audioPillFlags(- audio: Pick<TimelineElement, "id" | "tag" | "src" | "hidden" | "audioGroupHidden">,- elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],+ audio: Pick<TimelineElement, "hidden" | "audioGroupHidden" | "link">,+ _elements?: readonly unknown[],): { muted: boolean; linked: boolean } {return {muted: audio.hidden === true || audio.audioGroupHidden === true,- linked: isLinkedVideoAudio(audio, elements),+ linked: isLinked(audio),};}-/** An audio pill whose file is also a video clip on this timeline. */-export function isLinkedVideoAudio(- audio: Pick<TimelineElement, "id" | "tag" | "src">,- elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],-): boolean {- if (audio.tag.trim().toLowerCase() !== "audio") return false;- const key = mediaFileKey(audio.src);- if (!key) return false;- return elements.some((element) => {- if (element.id === audio.id) return false;- if (element.tag.trim().toLowerCase() !== "video") return false;- return mediaFileKey(element.src) === key;- });+export function linkedMembersOf<T extends LinkedElement>(element: T, elements: readonly T[]): T[] {+ if (!isLinked(element)) return [element];+ const members = elements.filter((candidate) => sharesLinkGroup(candidate, element));+ return members.some((member) => keyOf(member) === keyOf(element))+ ? members+ : [element, ...members];+}++export function expandToLinkedMembers(+ keys: Iterable<string>,+ elements: readonly LinkedElement[],+): Set<string> {+ const expanded = new Set(keys);+ const seeds = elements.filter((el) => expanded.has(keyOf(el)) && isLinked(el));+ for (const element of elements) {+ if (seeds.some((seed) => sharesLinkGroup(seed, element))) expanded.add(keyOf(element));+ }+ return expanded;+}++export function linkedGestureKeys(+ selected: ReadonlySet<string>,+ grabbed: LinkedElement,+ elements: readonly LinkedElement[],+ altKey: boolean,+): Set<string> {+ const grabbedKey = keyOf(grabbed);+ if (altKey) return new Set([grabbedKey]);+ const base = selected.has(grabbedKey) ? selected : [grabbedKey];+ return expandToLinkedMembers(base, elements);}diff --git a/packages/studio/src/player/components/clipMenuLinkItems.test.ts b/packages/studio/src/player/components/clipMenuLinkItems.test.tsnew file mode 100644index 0000000000..98ef1c1971--- /dev/null+++ b/packages/studio/src/player/components/clipMenuLinkItems.test.ts@@ -0,0 +1,73 @@+import { describe, expect, it, vi } from "vitest";+import type { TimelineElement } from "../store/playerStore";+import { resolveLinkMenuItems } from "./clipMenuLinkItems";++const clip = (id: string, tag: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({+ id,+ tag,+ src: "talk.mp4",+ start: 0,+ duration: 4,+ track: 0,+ ...extra,+});++function labels(element: TimelineElement, elements: TimelineElement[], selected: string[] = []) {+ return resolveLinkMenuItems({+ element,+ elements,+ selectedKeys: new Set(selected),+ onLinkEdit: vi.fn(),+ onDeleteElementOnly: vi.fn(),+ }).map((item) => item.label);+}++describe("resolveLinkMenuItems", () => {+ it("offers Detach audio on a video with sound (frame 4)", () => {+ const talk = clip("talk", "video", { hasAudio: true });+ expect(labels(talk, [talk])).toEqual(["Detach audio"]);+ });++ it("offers Unlink, Merge back and Delete this clip only on a linked pair (frame 6)", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-1" });+ const audio = clip("talk-audio", "audio", { link: "lk-1" });+ expect(labels(audio, [video, audio])).toEqual([+ "Unlink",+ "Merge audio back into video",+ "Delete this clip only",+ ]);+ });++ it("offers Link instead of Unlink for a selected unlinked pair", () => {+ const video = clip("talk", "video", { muted: true });+ const audio = clip("talk-audio", "audio");+ expect(labels(video, [video, audio], ["talk", "talk-audio"])).toEqual([+ "Link",+ "Merge audio back into video",+ ]);+ });++ it("offers nothing for a silent video or without a link handler", () => {+ const broll = clip("broll", "video", { muted: true, src: "b.mp4" });+ expect(labels(broll, [broll])).toEqual([]);+ expect(+ resolveLinkMenuItems({+ element: clip("t", "video", { hasAudio: true }),+ elements: [],+ selectedKeys: new Set(),+ }),+ ).toEqual([]);+ });++ it("each item dispatches its link edit", () => {+ const onLinkEdit = vi.fn();+ const talk = clip("talk", "video", { hasAudio: true });+ resolveLinkMenuItems({+ element: talk,+ elements: [talk],+ selectedKeys: new Set(),+ onLinkEdit,+ })[0]?.run();+ expect(onLinkEdit).toHaveBeenCalledWith({ kind: "detach", element: talk });+ });+});diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsxnew file mode 100644index 0000000000..a5ca0d0daa--- /dev/null+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx@@ -0,0 +1,110 @@+import { usePlayerStore, type TimelineElement } from "../store/playerStore";+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";+import type { TimelineLinkEdit } from "./timelineCallbacks";+import { linkedMembersOf } from "./audioClipLink";+import { canDetachAudio, canLinkPair, findMergePair } from "../../components/editor/mediaLinkEdits";++interface LinkMenuItem {+ label: string;+ shortcut?: string;+ destructive?: boolean;+ run: () => void;+}++const keyOf = (el: TimelineElement) => el.key ?? el.id;++/** The link-model items for a clip, in wireframe order (detach · unlink/link · merge · delete-one). */+export function resolveLinkMenuItems(input: {+ element: TimelineElement;+ elements: readonly TimelineElement[];+ selectedKeys: ReadonlySet<string>;+ onLinkEdit?: (edit: TimelineLinkEdit) => unknown;+ onDeleteElementOnly?: (element: TimelineElement) => unknown;+}): LinkMenuItem[] {+ const { element, elements, selectedKeys, onLinkEdit, onDeleteElementOnly } = input;+ const items: LinkMenuItem[] = [];+ if (!onLinkEdit) return items;+ const members = linkedMembersOf(element, elements);+ const linked = members.length > 1;+ if (canDetachAudio(element)) {+ items.push({+ label: "Detach audio",+ shortcut: "⌥⇧D",+ run: () => onLinkEdit({ kind: "detach", element }),+ });+ }+ const selected = elements.filter((el) => selectedKeys.has(keyOf(el)));+ if (linked) {+ items.push({+ label: "Unlink",+ shortcut: "⌘L",+ run: () => onLinkEdit({ kind: "unlink", elements: members }),+ });+ } else if (canLinkPair(selected) && selectedKeys.has(keyOf(element))) {+ items.push({+ label: "Link",+ shortcut: "⌘L",+ run: () => onLinkEdit({ kind: "link", elements: selected }),+ });+ }+ const pair = findMergePair(element, elements);+ if (pair) {+ items.push({+ label: "Merge audio back into video",+ run: () => onLinkEdit({ kind: "merge", ...pair }),+ });+ }+ if (linked && onDeleteElementOnly) {+ items.push({+ label: "Delete this clip only",+ shortcut: "⌥⌫",+ destructive: true,+ run: () => onDeleteElementOnly(element),+ });+ }+ return items;+}++export function ClipMenuLinkItems({+ element,+ onClose,+}: {+ element: TimelineElement;+ onClose: () => void;+}) {+ const { onLinkEdit, onDeleteElementOnly } = useTimelineEditContextOptional();+ const elements = usePlayerStore((s) => s.elements);+ const selectedKeys = usePlayerStore((s) => s.selectedElementIds);+ const items = resolveLinkMenuItems({+ element,+ elements,+ selectedKeys,+ onLinkEdit,+ onDeleteElementOnly,+ });+ if (items.length === 0) return null;+ return (+ <>+ {items.map((item) => (+ <button+ key={item.label}+ type="button"+ role="menuitem"+ className={`w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden cursor-pointer hover:bg-neutral-800 focus-visible:bg-neutral-800 ${+ item.destructive ? "text-red-400" : "text-neutral-300"+ }`}+ onClick={() => {+ item.run();+ onClose();+ }}+ >+ <span>{item.label}</span>+ {item.shortcut && (+ <span className="text-neutral-500 text-[10px] ml-3">{item.shortcut}</span>+ )}+ </button>+ ))}+ <div className="my-1 border-t border-neutral-700/60" />+ </>+ );+}diff --git a/packages/studio/src/player/components/timelineCallbacks.ts b/packages/studio/src/player/components/timelineCallbacks.tsindex 3fa2a7f0fe..812e6ca022 100644--- a/packages/studio/src/player/components/timelineCallbacks.ts+++ b/packages/studio/src/player/components/timelineCallbacks.ts@@ -39,6 +39,12 @@ export interface TimelineDropCallbacks {) => Promise<void> | void;}+export type TimelineLinkEdit =+ | { kind: "unlink"; elements: readonly TimelineElement[] }+ | { kind: "link"; elements: readonly TimelineElement[] }+ | { kind: "detach"; element: TimelineElement }+ | { kind: "merge"; video: TimelineElement; audio: TimelineElement };+export interface TimelineEditCallbacks {onMoveElement?: (element: TimelineElement,@@ -115,6 +121,8 @@ export interface TimelineEditCallbacks {label: string,) => Promise<TimelineEditOutcome | void>;onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;+ onLinkEdit?: (edit: TimelineLinkEdit) => Promise<void> | void;+ onDeleteElementOnly?: (element: TimelineElement) => Promise<void> | void;onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;onRazorSplitAll?: (splitTime: number) => Promise<void> | void;diff --git a/packages/studio/src/player/components/timelineClipDragGestureLifecycle.ts b/packages/studio/src/player/components/timelineClipDragGestureLifecycle.tsindex 2b0a624755..7f6cb33d18 100644--- a/packages/studio/src/player/components/timelineClipDragGestureLifecycle.ts+++ b/packages/studio/src/player/components/timelineClipDragGestureLifecycle.ts@@ -70,6 +70,7 @@ interface TimelineClipDragGestureLifecycleInput {onBlockedEditAttemptRef: RefObject<((element: TimelineElement, intent: BlockedClipState["intent"]) => void) | undefined>;+ onLinkEditRef: RefObject<TimelineEditCallbacks["onLinkEdit"]>;readZIndexRef: RefObject<((element: TimelineElement) => number) | undefined>;onStackingPatchesRef: RefObject<((patches: StackingPatch[]) => Promise<unknown> | void) | undefined@@ -107,6 +108,7 @@ export function mountTimelineClipDragGestureLifecycle({onResizeElementRef,onResizeElementsRef,onBlockedEditAttemptRef,+ onLinkEditRef,readZIndexRef,onStackingPatchesRef,refreshAfterLaneMoveRef,@@ -228,6 +230,11 @@ export function mountTimelineClipDragGestureLifecycle({if (drag && pointerMatchesGesture(event)) handleDragPointerMove(event, drag);};+ const unlinkAltEdited = (gesture: { element: TimelineElement; altKey?: boolean }) => {+ if (!gesture.altKey || !gesture.element.link) return;+ void onLinkEditRef.current?.({ kind: "unlink", elements: [gesture.element] });+ };+const commitResizePointerUp = (resize: ResizingClipState,groupSession: TimelineGroupResizeSession | null,@@ -271,6 +278,7 @@ export function mountTimelineClipDragGestureLifecycle({]);console.error("[Timeline] Failed to persist clip resize", error);});+ unlinkAltEdited(resize);};const finishBlockedPointerUp = (blocked: BlockedClipState) => {@@ -293,6 +301,7 @@ export function mountTimelineClipDragGestureLifecycle({onStackingPatches: onStackingPatchesRef.current,refreshAfterLaneMove: refreshAfterLaneMoveRef.current,});+ unlinkAltEdited(drag);};/** Group gestures commit atomically: one missing member cancels the whole resize. */diff --git a/packages/studio/src/player/components/timelineClipDragTypes.ts b/packages/studio/src/player/components/timelineClipDragTypes.tsindex 2f8ce3e6de..4ef2801b67 100644--- a/packages/studio/src/player/components/timelineClipDragTypes.ts+++ b/packages/studio/src/player/components/timelineClipDragTypes.ts@@ -33,6 +33,7 @@ export interface DraggedClipState {snapTime: number | null;snapType: TimelineSnapType | null;started: boolean;+ altKey?: boolean;}export interface ResizingClipState {@@ -63,6 +64,7 @@ export interface ResizingClipState {playbackStart?: number;}[];started: boolean;+ altKey?: boolean;}export interface BlockedClipState {diff --git a/packages/studio/src/player/components/timelineClipGestureHandlers.ts b/packages/studio/src/player/components/timelineClipGestureHandlers.tsindex 4dc1671c95..885d3692cf 100644--- a/packages/studio/src/player/components/timelineClipGestureHandlers.ts+++ b/packages/studio/src/player/components/timelineClipGestureHandlers.ts@@ -8,6 +8,7 @@ import {import type { TimelineEditCapabilities } from "./timelineEditCapabilities";import type { TimelineEditCallbacks } from "./timelineCallbacks";import { CLIP_HANDLE_W } from "./timelineLayout";+import { selectClipWithLinks } from "./timelineLinkSelection";import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";export interface ClipGestureDeps {@@ -145,6 +146,7 @@ export function createClipGestureHandlers(previewDuration: el.duration,previewPlaybackStart: el.playbackStart,started: false,+ altKey: e.altKey,});};@@ -191,6 +193,7 @@ export function createClipGestureHandlers(snapTime: null,snapType: null,started: false,+ altKey: e.altKey,});};@@ -217,7 +220,7 @@ export function createClipGestureHandlers(return;}// Clip selection is idempotent; empty timeline space owns deselection.- setSelectedElementId(elementKey);+ selectClipWithLinks(elementKey, e.altKey, setSelectedElementId);onSelectElement?.(el);};diff --git a/packages/studio/src/player/components/timelineLinkSelection.ts b/packages/studio/src/player/components/timelineLinkSelection.tsnew file mode 100644index 0000000000..1ed00acc8c--- /dev/null+++ b/packages/studio/src/player/components/timelineLinkSelection.ts@@ -0,0 +1,22 @@+import { usePlayerStore } from "../store/playerStore";+import { expandToLinkedMembers } from "./audioClipLink";++/**+ * Select `key` the way a clip click does, then widen to link partners; Alt+ * selects `key` alone even when it sat inside a larger selection.+ */+export function selectClipWithLinks(+ key: string,+ altKey: boolean,+ setSelectedElementId: (id: string) => void,+): void {+ const state = usePlayerStore.getState();+ if (altKey) {+ state.setSelection([key], key);+ return;+ }+ setSelectedElementId(key);+ const { selectedElementIds, elements } = usePlayerStore.getState();+ const expanded = expandToLinkedMembers(selectedElementIds, elements);+ if (expanded.size > selectedElementIds.size) state.setSelection(expanded, key);+}diff --git a/packages/studio/src/player/components/useTimelineClipContextMenu.ts b/packages/studio/src/player/components/useTimelineClipContextMenu.tsindex 25a47f369d..56a816e557 100644--- a/packages/studio/src/player/components/useTimelineClipContextMenu.ts+++ b/packages/studio/src/player/components/useTimelineClipContextMenu.ts@@ -1,6 +1,7 @@import { useCallback } from "react";import { usePlayerStore, type TimelineElement } from "../store/playerStore";import type { ClipContextMenuState } from "./TimelineProvider";+import { selectClipWithLinks } from "./timelineLinkSelection";/** A clicked member of an active multi-selection keeps the whole group* selected, so the context menu it opens acts on all of it. */@@ -16,7 +17,7 @@ export function useClipContextMenu(e.preventDefault();const id = el.key ?? el.id;if (!(selectedElementIds.size > 1 && selectedElementIds.has(id))) {- setSelectedElementId(id);+ selectClipWithLinks(id, e.altKey, setSelectedElementId);onSelectElement?.(el);}dismissGapMenu();diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.tsindex 18e588d747..41a21dd815 100644--- a/packages/studio/src/player/components/useTimelineClipDrag.ts+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts@@ -27,6 +27,7 @@ import type {BlockedClipState,} from "./timelineClipDragTypes";import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";+import { linkedGestureKeys } from "./audioClipLink";import type { TimelineRowGeometry } from "./timelineLayout";import {mountTimelineClipDragGestureLifecycle,@@ -65,6 +66,7 @@ interface UseTimelineClipDragInput {) => Promise<void> | void;onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;+ onLinkEdit?: TimelineEditCallbacks["onLinkEdit"];/** Seeks the preview; a trim shows the frame at its dragged edge. */onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;setShowPopover: (show: boolean) => void;@@ -95,6 +97,7 @@ export function useTimelineClipDrag({onResizeElement,onResizeElements,onBlockedEditAttempt,+ onLinkEdit,onSeek,setShowPopover,setRangeSelectionRef,@@ -220,6 +223,12 @@ export function useTimelineClipDrag({return;}beginGesture("drag", next.pointerId);+ gestureSelectedKeysRef.current = linkedGestureKeys(+ gestureSelectedKeysRef.current,+ next.element,+ elementsRef.current,+ next.altKey === true,+ );publishDraggedClip(next);},[beginGesture, publishDraggedClip],@@ -231,6 +240,12 @@ export function useTimelineClipDrag({return;}beginGesture("resize", next.pointerId);+ gestureSelectedKeysRef.current = linkedGestureKeys(+ gestureSelectedKeysRef.current,+ next.element,+ elementsRef.current,+ next.altKey === true,+ );publishResizingClip(next);},[beginGesture, publishResizingClip],@@ -249,6 +264,8 @@ export function useTimelineClipDrag({onMoveElementsRef.current = onMoveElements;const onBlockedEditAttemptRef = useRef(onBlockedEditAttempt);onBlockedEditAttemptRef.current = onBlockedEditAttempt;+ const onLinkEditRef = useRef(onLinkEdit);+ onLinkEditRef.current = onLinkEdit;const onResizeElementRef = useRef(onResizeElement);onResizeElementRef.current = onResizeElement;const onResizeElementsRef = useRef(onResizeElements);@@ -422,6 +439,7 @@ export function useTimelineClipDrag({refreshAfterLaneMoveRef,readZIndexRef,onBlockedEditAttemptRef,+ onLinkEditRef,onResizeElementsRef,onResizeElementRef,onMoveElementsRef,diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsxindex e6deabb9ae..bb67de3585 100644--- a/packages/studio/src/player/components/useTimelineProviderState.tsx+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx@@ -86,6 +86,7 @@ export function useTimelineProviderState({onResizeElement,onResizeElements,onBlockedEditAttempt,+ onLinkEdit,onSplitElement,onRazorSplitAll,onDeleteKeyframe,@@ -105,6 +106,7 @@ export function useTimelineProviderState({const readOnlyPress = useTimelineReadOnlyPress();const oneShotEdits = refuseWhenReadOnly(readOnlyPress, {onBlockedEditAttempt,+ onLinkEdit,onRazorSplitAll,onToggleTrackHidden: editContext.onToggleTrackHidden,onTogglePropertyGroupKeyframe: editContext.onTogglePropertyGroupKeyframe,@@ -217,6 +219,7 @@ export function useTimelineProviderState({onResizeElement: pinnedOnResizeElement,onResizeElements: pinnedOnResizeElements,onBlockedEditAttempt: oneShotEdits.onBlockedEditAttempt,+ onLinkEdit: oneShotEdits.onLinkEdit,onSeek,setShowPopover,setRangeSelectionRef,diff --git a/packages/studio/src/player/lib/timelineDOM.test.ts b/packages/studio/src/player/lib/timelineDOM.test.tsindex 7143ae7521..f0b03876ef 100644--- a/packages/studio/src/player/lib/timelineDOM.test.ts+++ b/packages/studio/src/player/lib/timelineDOM.test.ts@@ -281,6 +281,34 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {expect(element.hidden).toBe(true);});++ it("reads data-link on both the DOM and manifest paths", () => {+ const doc = makeDoc(`+ <div data-composition-id="root">+ <video id="talk" class="clip" src="t.mp4" muted data-link="lk-1" data-start="0" data-duration="5"></video>+ </div>+ `);+ expect(parseTimelineFromDOM(doc, 10).find((el) => el.domId === "talk")?.link).toBe("lk-1");+ const element = createTimelineElementFromManifestClip({+ clip: {+ id: "talk",+ label: "Talk",+ kind: "element",+ tagName: "video",+ start: 0,+ duration: 5,+ track: 0,+ compositionId: null,+ parentCompositionId: null,+ compositionSrc: null,+ assetUrl: null,+ },+ fallbackIndex: 0,+ doc,+ hostEl: doc.getElementById("talk"),+ });+ expect(element.link).toBe("lk-1");+ });});describe("group info cache", () => {diff --git a/packages/studio/src/player/lib/timelineDOM.ts b/packages/studio/src/player/lib/timelineDOM.tsindex c93108cb0b..1efa59e438 100644--- a/packages/studio/src/player/lib/timelineDOM.ts+++ b/packages/studio/src/player/lib/timelineDOM.ts@@ -12,6 +12,7 @@ import type { TimelineElement } from "../store/playerStore";import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";import { readClipTiming } from "@hyperframes/core/composition-contract";+import { linkScopeOf } from "@hyperframes/core/media-link";import { createRuntimeStartTimeResolver } from "@hyperframes/core/runtime/start-resolver";import { groupInfoFor } from "./timelineGroupInfo";import { transitionLabelsForDocument } from "./timelineTransitionMetadata";@@ -150,6 +151,10 @@ export function createTimelineElementFromManifestClip(params: {if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;const timelineRole = hostEl.getAttribute("data-timeline-role");if (timelineRole) entry.timelineRole = timelineRole;+ const link = hostEl.getAttribute("data-link");+ if (link) entry.link = link;+ const compositionScope = linkScopeOf(hostEl)?.getAttribute("data-composition-id");+ if (compositionScope) entry.compositionScope = compositionScope;const audioGroup = hostEl.getAttribute("data-audio-group");if (audioGroup) {entry.audioGroup = audioGroup;@@ -337,6 +342,10 @@ export function parseTimelineFromDOM(const timelineRole = el.getAttribute("data-timeline-role");if (timelineRole) entry.timelineRole = timelineRole;+ const domLink = el.getAttribute("data-link");+ if (domLink) entry.link = domLink;+ const domCompositionScope = linkScopeOf(el)?.getAttribute("data-composition-id");+ if (domCompositionScope) entry.compositionScope = domCompositionScope;const domAudioGroup = el.getAttribute("data-audio-group");if (domAudioGroup) {diff --git a/packages/studio/src/player/store/timelineElement.ts b/packages/studio/src/player/store/timelineElement.tsindex 436391d791..90f7a85206 100644--- a/packages/studio/src/player/store/timelineElement.ts+++ b/packages/studio/src/player/store/timelineElement.ts@@ -83,6 +83,8 @@ export interface TimelineElement {/** The owning group's serialized `data-fx-chain`, when set — resolved once per parse. */audioGroupFxChain?: string;audioGroupAutomation?: string;+ link?: string;+ compositionScope?: string;/*** Master start of the composition this row runs in, which its tweens and its* `data-start` are local to; 0 at the root. Writes go through toAuthoredStart.@@ -116,6 +118,15 @@ export function toCompositionTime(element: RowClock, masterTime: number): numberreturn masterTime - (element.parentCompositionStart ?? 0);}+type CompositionScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;++export function sameCompositionScope(a: CompositionScoped, b: CompositionScoped): boolean {+ return (+ (a.sourceFile ?? "") === (b.sourceFile ?? "") &&+ (a.compositionScope ?? "") === (b.compositionScope ?? "")+ );+}+/*** The fields `updateElement` may write.*diff --git a/skills-manifest.json b/skills-manifest.jsonindex b1490ddb7a..f380caf3df 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -34,7 +34,7 @@"files": 11},"hyperframes-core": {- "hash": "db99256dd85d0460",+ "hash": "3bc49ffe4697122b","files": 11},"hyperframes-creative": {diff --git a/skills/hyperframes-core/references/data-attributes.md b/skills/hyperframes-core/references/data-attributes.mdindex 8f98dddd51..7949c27dd8 100644--- a/skills/hyperframes-core/references/data-attributes.md+++ b/skills/hyperframes-core/references/data-attributes.md@@ -26,15 +26,16 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid**Nesting is allowed.** A timed element inside a wrapper is still timed, and a timed ancestor clamps its descendants: a child cannot be visible while its timed ancestor is hidden. Direct children of the root get automatic layout (see "Root-level clips get automatic layout" below); nested ones do not, so give them their own positioning.-| Attribute | Required | Meaning |-| ------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `id` | Yes on `<video>`/`<audio>`, else recommended | `lint` errors with `media_missing_id` on media without one, and an id-less `<audio>` is never mixed, so the render is **silent**. Elsewhere it is a warning (`studio_missing_editable_id`): Studio needs a stable edit target, and timeline targets reference it. |-| `data-start` | Yes | Start time in seconds, or a supported clip-time reference. This attribute is what marks the element as timed. |-| `data-duration` | Required for `div` and sub-compositions | Duration in seconds. An `img` with `data-start` defaults to 3 s; video/audio default to the source length (less the playback offset, over the rate) once known; an authored value trims. Without any resolvable duration the element has no end and stays visible for the rest of the composition. |-| `data-track-index` | No | Studio timeline lane, display only. The render never reads it, and clips on one track may overlap in time. Absent, the parser defaults it and Studio lays out one lane per clip. Two `<audio>` elements on the same index that overlap in time raise a `lint` warning. |-| `data-media-start` | No | Offset into the media source, in seconds. |-| `data-volume` | No | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades and ducking, use the `data-automation` volume lane (see `creator-editing-recipes.md`). |-| `data-has-audio` | Required on a timed `<video>` unless it is `muted` | `"true"` keeps the file's sound on this clip (the default for footage with sound). Silent footage uses `muted` instead; a video with neither fails lint (`video_missing_muted`). |+| Attribute | Required | Meaning |+| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `id` | Yes on `<video>`/`<audio>`, else recommended | `lint` errors with `media_missing_id` on media without one, and an id-less `<audio>` is never mixed, so the render is **silent**. Elsewhere it is a warning (`studio_missing_editable_id`): Studio needs a stable edit target, and timeline targets reference it. |+| `data-start` | Yes | Start time in seconds, or a supported clip-time reference. This attribute is what marks the element as timed. |+| `data-duration` | Required for `div` and sub-compositions | Duration in seconds. An `img` with `data-start` defaults to 3 s; video/audio default to the source length (less the playback offset, over the rate) once known; an authored value trims. Without any resolvable duration the element has no end and stays visible for the rest of the composition. |+| `data-track-index` | No | Studio timeline lane, display only. The render never reads it, and clips on one track may overlap in time. Absent, the parser defaults it and Studio lays out one lane per clip. Two `<audio>` elements on the same index that overlap in time raise a `lint` warning. |+| `data-media-start` | No | Offset into the media source, in seconds. |+| `data-volume` | No | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades and ducking, use the `data-automation` volume lane (see `creator-editing-recipes.md`). |+| `data-has-audio` | Required on a timed `<video>` unless it is `muted` | `"true"` keeps the file's sound on this clip (the default for footage with sound). Silent footage uses `muted` instead; a video with neither fails lint (`video_missing_muted`). |+| `data-link` | No | Editing contract only (render ignores it): clips sharing an id, e.g. a video and the `<audio>` detached from it in Studio, are edited as one. Keep every member's `data-start`, `data-duration`, `data-media-start` and `data-playback-rate` equal; to unlink, remove the attribute from all members. See [tracks-and-clips.md](tracks-and-clips.md#linked-clips). |**The visibility window is half-open: `[start, start + duration)`.** A clip shows while `start ≤ t < start + duration` and is hidden at exactly `t = start + duration`. Land an animation's resolved end state slightly **before** `data-duration`, not on it, or its last frame is never rendered. Two clips can therefore be authored back to back (`b.start === a.start + a.duration`) with no overlapping frame.diff --git a/skills/hyperframes-core/references/tracks-and-clips.md b/skills/hyperframes-core/references/tracks-and-clips.mdindex d979bc8c60..93f7023177 100644--- a/skills/hyperframes-core/references/tracks-and-clips.md+++ b/skills/hyperframes-core/references/tracks-and-clips.md@@ -48,6 +48,38 @@ not try to keyframe source cutting.Each video segment keeps its sound: the sound stays on the clip (`data-has-audio="true"`), so cutting the video cuts its sound. A separate `<audio>` is for other sound (music, voiceover, replacement audio, J/L cuts).+## Linked clips++`data-link="<id>"` marks clips that are edited as one: in Studio, moving, trimming, splitting or deleting one member does the same to the others. Detach audio in Studio produces a pair, a muted `<video>` and an `<audio>` over the same file:++```html+<video+ id="talk"+ src="talk.mp4"+ muted+ data-link="lk-1"+ data-start="2"+ data-duration="6"+ data-media-start="1"+ data-track-index="0"+></video>+<audio+ id="talk-audio"+ src="talk.mp4"+ data-link="lk-1"+ data-start="2"+ data-duration="6"+ data-media-start="1"+ data-track-index="2"+></audio>+```++- **Keep members in sync.** Every member needs the same `data-start`, `data-duration`, `data-media-start` (absent = 0) and `data-playback-rate` (absent = 1). Track index, volume, fades and FX may differ. When you retime one member by hand, retime all of them, or `lint` warns `linked_clips_out_of_sync`.+- **Unlink** by removing `data-link` from every member. Removing it from one leaves the other alone with the id, which `lint` flags as `linked_clip_orphan`.+- The render ignores `data-link`: an out-of-sync pair still plays exactly what its timings say.+- Prefer a single `<video data-has-audio="true">` for footage with sound. Link only when the sound needs its own clip (its own track, volume or FX); to undo a detach, move the audio attributes back onto the video and delete the `<audio>`.+- `@hyperframes/sdk` `setTiming` applies to link partners by default; pass `{ linked: false }` to edit one member, which unlinks it.+## Relative Timing`data-start` accepts a clip ID instead of a number, meaning "start when that clip ends". Add `+ N` / `- N` to offset; negative produces overlap (useful for crossfades).