Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(studio): sync origin, out-of-sync repair, linked selection toggle and grouped clip menu (7/8) (#4820)
Vance Ingalls45b8e171e279
diff --git a/packages/cli/src/timeline/describeProject.test.ts b/packages/cli/src/timeline/describeProject.test.tsindex ec0e22e15d..94538fd178 100644--- a/packages/cli/src/timeline/describeProject.test.ts+++ b/packages/cli/src/timeline/describeProject.test.ts@@ -116,6 +116,20 @@ describe("describeProject", () => {]);});+ it("reports each half's out-of-sync offset from its source pair, at the project fps", async () => {+ const { rows, text } = await rowsOf(`<html><body>+<div data-composition-id="main" data-duration="10" data-fps="24">+ <video id="v" src="t.mp4" muted data-sync-origin="lk-1" data-start="1" data-duration="4" data-track-index="0"></video>+ <audio id="a" src="t.mp4" data-sync-origin="lk-1" data-start="1.5" data-duration="4" data-track-index="1"></audio>+ <audio id="m" src="m.mp3" data-start="0" data-duration="4" data-track-index="2"></audio>+</div></body></html>`);+ const offset = (id: string) => rows.find((r) => r.id === id)?.syncOffsetFrames;+ expect(offset("a")).toBe(12);+ expect(offset("v")).toBe(-12);+ expect(offset("m")).toBeNull();+ expect(text).toContain("out-of-sync=+12f");+ });+it("reports unreadable automation instead of showing no lanes", async () => {const bad = (await describeProject(project())).tracks.flatMap((t) => t.rows)diff --git a/packages/cli/src/timeline/describeProject.ts b/packages/cli/src/timeline/describeProject.tsindex 988138f027..1475a6e7b9 100644--- a/packages/cli/src/timeline/describeProject.ts+++ b/packages/cli/src/timeline/describeProject.ts@@ -8,7 +8,9 @@ import {import { HF_AUDIO_FX_ATTR, parseAudioFxChain } from "@hyperframes/core/audio-fx";import { HF_AUDIO_GROUP_ATTR } from "@hyperframes/core/audio-groups";import { byStart, type ClipFact, type ClipLane } from "@hyperframes/core/clip-facts";-import { parseNumeric } from "@hyperframes/core";+import { fpsToNumber, parseFpsWithDefault, parseNumeric } from "@hyperframes/core";+import { findSyncPartner, readLinkTiming, syncOffsetFrames } from "@hyperframes/core/media-link";+import { readCompositionFps } from "../utils/compositionFps.js";import {readMediaOffsetSeconds,readPlaybackRate,@@ -60,6 +62,8 @@ export interface TimelineRow extends ClipFact {hostRow: RowPointer | null;/** Where this row's sub-composition clips are (one level only); each is a full row in its kind's `rows`. */children: RowPointer[];+ /** Signed frames from its `data-sync-origin` partner (+ = late); `null` unpaired or rates differ. */+ syncOffsetFrames: number | null;}export interface RowPointer {@@ -137,6 +141,7 @@ interface DocScope {withProbeSlot: <T>(fn: () => Promise<T>) => Promise<T>;measure: MeasureMedia;sourceOverrides: ReadonlyMap<string, string>;+ fps: number;}/** Source length in seconds of a media file. ffprobe in production; tests pass a recorded fake. */@@ -312,9 +317,15 @@ function describeRowFields(scope: DocScope, node: DomNode, timing: RowTiming): Cwarnings: [],elementId: el.id || null,hfId: el.getAttribute("data-hf-id"),+ syncOffsetFrames: syncOffsetOf(el, scope.fps),};}+function syncOffsetOf(el: Element, fps: number): number | null {+ const partner = findSyncPartner(el);+ return partner ? syncOffsetFrames(readLinkTiming(el), readLinkTiming(partner), fps) : null;+}+async function describeRow(scope: DocScope, node: DomNode, depth: number): Promise<ClipDraft> {return describeRowFields(scope, node, await resolveRowTiming(scope, node, depth));}@@ -343,6 +354,7 @@ async function readSubComposition(withProbeSlot: parent.withProbeSlot,measure: parent.measure,sourceOverrides: parent.sourceOverrides,+ fps: parent.fps,};const rows = await Promise.all(topLevelElements(toNode(root)).map((node) => describeRow(scope, node, 1)),@@ -416,6 +428,11 @@ function flatten(top: ClipDraft[]): TimelineTrack[] {}));}+function projectFps(source: string): number {+ const parsed = parseFpsWithDefault(readCompositionFps(source) ?? undefined);+ return fpsToNumber(parsed.ok ? parsed.value : { num: 30, den: 1 });+}+/** Needs a global DOMParser (`ensureDOMParser`). Reads `index.html` and one level of sub-compositions. */export async function describeProject(indexPath: string,@@ -437,6 +454,7 @@ export async function describeProject(withProbeSlot: createProbeGate(PROBE_CONCURRENCY),measure,sourceOverrides,+ fps: projectFps(source),};const rows = (await Promise.all(topLevelElements(toNode(root)).map((node) => describeRow(scope, node, 0)))diff --git a/packages/cli/src/timeline/formatTimeline.ts b/packages/cli/src/timeline/formatTimeline.tsindex c412feb6fd..2b8b0862c4 100644--- a/packages/cli/src/timeline/formatTimeline.ts+++ b/packages/cli/src/timeline/formatTimeline.ts@@ -29,6 +29,11 @@ function durationNote(row: TimelineRow): string | false {}}+function syncNote(frames: number | null): string | false {+ if (!frames) return false;+ return `out-of-sync=${frames > 0 ? "+" : ""}${frames}f`;+}+function details(row: TimelineRow): string {const lanes = row.lanes.map((l) => `${l.target}[${l.points.map((p) => `${n(p.t)}:${n(p.v)}`).join(" ")}]`,@@ -38,6 +43,7 @@ function details(row: TimelineRow): string {row.volume !== null && `vol=${row.volume}`,row.playbackRate !== null && `rate=${n(row.playbackRate)}`,row.audioGroup && `group=${row.audioGroup}`,+ syncNote(row.syncOffsetFrames),durationNote(row),row.sourceFile && !row.children.length && "children=unread",row.laneError && `lanes unreadable: ${row.laneError}`,diff --git a/packages/cli/src/timeline/timeExpr.test.ts b/packages/cli/src/timeline/timeExpr.test.tsindex 99c51e634e..31b7730742 100644--- a/packages/cli/src/timeline/timeExpr.test.ts+++ b/packages/cli/src/timeline/timeExpr.test.ts@@ -32,6 +32,7 @@ const row: TimelineRow = {durationSource: "authored",pendingReason: null,laneError: null,+ syncOffsetFrames: null,};describe("parseTimeExpression", () => {diff --git a/packages/core/src/mediaLink.test.ts b/packages/core/src/mediaLink.test.tsindex 568c7f930d..c8465b6f97 100644--- a/packages/core/src/mediaLink.test.ts+++ b/packages/core/src/mediaLink.test.ts@@ -1,7 +1,14 @@import { describe, expect, it } from "vitest";import {MEDIA_LINK_ATTR,+ SYNC_ORIGIN_ATTR,+ findSyncPartner,+ formatSyncOffset,linkTimingMismatches,+ moveIntoSyncStart,+ slipIntoSyncMediaStart,+ sourceZeroTime,+ syncOffsetFrames,mintLinkId,readLinkTiming,relinkSplitHalves,@@ -24,6 +31,11 @@ describe("readLinkTiming", () => {it("reads data-playback-start as the media-start alias", () => {expect(readLinkTiming(attrs({ "data-playback-start": "1.5" })).mediaStart).toBe(1.5);});++ it("lets data-playback-start win over data-media-start, as playback does", () => {+ const both = attrs({ "data-playback-start": "0", "data-media-start": "0.5" });+ expect(readLinkTiming(both).mediaStart).toBe(0);+ });});describe("linkTimingMismatches", () => {@@ -86,6 +98,17 @@ describe("relinkSplitHalves", () => {expect(link("i-split")).toBeNull();});+ it("keeps the source origin when only one member of an unlinked pair is cut", () => {+ const d = doc(`+ <video id="v" data-sync-origin="lk-1" data-start="0" data-duration="10"></video>+ <audio id="a" data-sync-origin="lk-1" data-start="0" data-duration="4"></audio>+ <audio id="a-split" data-sync-origin="lk-1" data-start="4" data-duration="6"></audio>`);+ relinkSplitHalves(d, ["a-split"]);+ const right = d.getElementById("a-split");+ expect(right?.getAttribute(SYNC_ORIGIN_ATTR)).toBe("lk-1");+ expect(right && findSyncPartner(right)?.id).toBe("v");+ });+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>@@ -97,3 +120,100 @@ describe("relinkSplitHalves", () => {expect(ids).not.toContain("lk-7");});});++describe("relinkSplitHalves sync origin", () => {+ it("gives right halves their own shared sync origin, even when unlinked", () => {+ document.body.innerHTML = `+ <video id="v" data-sync-origin="lk-1"></video><video id="v2" data-sync-origin="lk-1"></video>+ <audio id="a" data-sync-origin="lk-1"></audio><audio id="a2" data-sync-origin="lk-1"></audio>`;+ relinkSplitHalves(document, ["v2", "a2"]);+ const origin = (id: string) => document.getElementById(id)?.getAttribute(SYNC_ORIGIN_ATTR);+ expect(origin("v")).toBe("lk-1");+ expect(origin("a")).toBe("lk-1");+ expect(origin("v2")).not.toBe("lk-1");+ expect(origin("v2")).toBe(origin("a2"));+ });+});++describe("sync offset", () => {+ const clip = (start: number, mediaStart = 0, playbackRate = 1) => ({+ start,+ mediaStart,+ playbackRate,+ });++ it("places source zero at start minus media-start over rate", () => {+ expect(sourceZeroTime(clip(4, 2, 2))).toBe(3);+ });++ it("is zero for a pair in sync, whatever their shared media start", () => {+ expect(syncOffsetFrames(clip(2, 1), clip(2, 1), 30)).toBe(0);+ expect(syncOffsetFrames(clip(3, 2), clip(2, 1), 30)).toBe(0);+ });++ it("is signed from the clip's side: late is positive, and the partner reads the negation", () => {+ expect(syncOffsetFrames(clip(2 + 10 / 30), clip(2), 30)).toBe(10);+ expect(syncOffsetFrames(clip(2), clip(2 + 10 / 30), 30)).toBe(-10);+ });++ it("counts media start: a slipped clip is out of sync in place", () => {+ expect(syncOffsetFrames(clip(2, 0.5), clip(2, 0), 30)).toBe(-15);+ });++ it("divides media start by the shared rate", () => {+ expect(syncOffsetFrames(clip(2, 1, 2), clip(2, 0, 2), 30)).toBe(-15);+ });++ it("has no offset when the rates differ", () => {+ expect(syncOffsetFrames(clip(2, 0, 1.5), clip(2, 0, 1), 30)).toBeNull();+ });++ it("formats frames, then seconds:frames past one second", () => {+ expect(formatSyncOffset(10, 30)).toBe("+10");+ expect(formatSyncOffset(-51, 30)).toBe("-1:21");+ expect(formatSyncOffset(30, 30)).toBe("+1:00");+ expect(formatSyncOffset(-3, 24)).toBe("-3");+ });++ it("moves the clip onto its partner, or refuses before zero", () => {+ expect(moveIntoSyncStart(clip(2.5, 0.5), clip(1, 0))).toBeCloseTo(1.5);+ expect(syncOffsetFrames(clip(1.5, 0.5), clip(1, 0), 30)).toBe(0);+ expect(moveIntoSyncStart(clip(0, 2), clip(0, 0))).toBeCloseTo(2);+ expect(moveIntoSyncStart(clip(1, 0), clip(0, 2))).toBeNull();+ });++ it("slips the clip's media in place, scaled by rate, or refuses before the file start", () => {+ expect(slipIntoSyncMediaStart(clip(3, 0), clip(2, 0))).toBeCloseTo(1);+ expect(slipIntoSyncMediaStart(clip(3, 0, 2), clip(2, 0, 2))).toBeCloseTo(2);+ expect(syncOffsetFrames(clip(3, 2, 2), clip(2, 0, 2), 30)).toBe(0);+ expect(slipIntoSyncMediaStart(clip(1, 0), clip(2, 0))).toBeNull();+ });+});++describe("findSyncPartner", () => {+ it("finds the opposite kind sharing the origin, preferring the most shared timeline", () => {+ document.body.innerHTML = `<div data-composition-id="m">+ <video id="v" data-sync-origin="lk-1" data-start="0" data-duration="4"></video>+ <video id="v2" data-sync-origin="lk-1" data-start="4" data-duration="4"></video>+ <audio id="a" data-sync-origin="lk-1" data-start="4.2" data-duration="4"></audio>+ <audio id="x" data-sync-origin="lk-9" data-start="4" data-duration="4"></audio></div>`;+ const byId = (id: string) => document.getElementById(id);+ const a = byId("a");+ const x = byId("x");+ expect(a && findSyncPartner(a)?.id).toBe("v2");+ expect(x && findSyncPartner(x)).toBeNull();+ });++ it.each(['data-composition-id="child"', 'data-composition-file="child.html"'])(+ "never takes a partner from a nested composition (%s) reusing the origin",+ (host) => {+ document.body.innerHTML = `<div data-composition-id="m">+ <video id="v" data-sync-origin="lk-1" data-start="0" data-duration="4"></video>+ <div ${host}>+ <audio id="ca" data-sync-origin="lk-1" data-start="0" data-duration="4"></audio>+ </div></div>`;+ const v = document.getElementById("v");+ expect(v && findSyncPartner(v)).toBeNull();+ },+ );+});diff --git a/packages/core/src/mediaLink.ts b/packages/core/src/mediaLink.tsindex a74e24b224..7cdf736e5d 100644--- a/packages/core/src/mediaLink.ts+++ b/packages/core/src/mediaLink.ts@@ -1,3 +1,5 @@+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";+/*** 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.@@ -38,7 +40,7 @@ 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),+ mediaStart: readMediaOffsetSeconds((name) => el.getAttribute(name)),playbackRate: readNumber(el, ["data-playback-rate"], 1),};}@@ -53,9 +55,11 @@ export function linkTimingMismatches(members: readonly AttributeReader[]): strin).map(([, field]) => field);}+const LINK_SCOPE_SELECTOR = "[data-composition-id], [data-composition-file]";+/** 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;+ return el.parentElement?.closest(LINK_SCOPE_SELECTOR) ?? null;}export function mintLinkId(taken: Iterable<string>): string {@@ -66,30 +70,138 @@ export function mintLinkId(taken: Iterable<string>): string {}function takenLinkIds(doc: Document): string[] {- return Array.from(doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}]`)).flatMap((el) => [+ return Array.from(+ doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}], [${SYNC_ORIGIN_ATTR}]`),+ ).flatMap((el) => [el.id,el.getAttribute(MEDIA_LINK_ATTR) ?? "",+ el.getAttribute(SYNC_ORIGIN_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));+function renameShared(+ doc: Document,+ ids: readonly string[],+ attr: string,+ taken: Set<string>,+): void {const renamed = new Map<string, string>();- for (const id of rightHalfIds) {+ for (const id of ids) {const el = doc.getElementById(id);- const oldLink = el?.getAttribute(MEDIA_LINK_ATTR);- if (!el || !oldLink) continue;- let fresh = renamed.get(oldLink);+ const old = el?.getAttribute(attr);+ if (!el || !old) continue;+ let fresh = renamed.get(old);if (!fresh) {fresh = mintLinkId(taken);taken.add(fresh);- renamed.set(oldLink, fresh);+ renamed.set(old, fresh);+ }+ el.setAttribute(attr, fresh);+ }+}++/** Split right halves get a fresh link id; a sync origin is reminted only when video and audio were both cut. */+export function relinkSplitHalves(doc: Document, rightHalfIds: readonly string[]): void {+ const taken = new Set(takenLinkIds(doc));+ renameShared(doc, rightHalfIds, MEDIA_LINK_ATTR, taken);+ renameShared(doc, idsWithBothSidesCut(doc, rightHalfIds), SYNC_ORIGIN_ATTR, taken);+}++function idsWithBothSidesCut(doc: Document, rightHalfIds: readonly string[]): string[] {+ const tagsByOrigin = new Map<string, Set<string>>();+ const originOf = (id: string) => doc.getElementById(id)?.getAttribute(SYNC_ORIGIN_ATTR) ?? null;+ for (const id of rightHalfIds) {+ const origin = originOf(id);+ const tag = doc.getElementById(id)?.tagName.toLowerCase();+ if (!origin || !tag) continue;+ tagsByOrigin.set(origin, (tagsByOrigin.get(origin) ?? new Set()).add(tag));+ }+ return rightHalfIds.filter((id) => {+ const tags = tagsByOrigin.get(originOf(id) ?? "");+ return tags?.has("video") === true && tags.has("audio");+ });+}++/** Shared by a detached or linked video + audio of one file; it survives Unlink so a drifted pair can resync. */+export const SYNC_ORIGIN_ATTR = "data-sync-origin";++export type SyncTiming = Pick<LinkTiming, "start" | "mediaStart" | "playbackRate">;++const rateOf = (timing: SyncTiming) => (timing.playbackRate > 0 ? timing.playbackRate : 1);++/** Where source time zero lands on the timeline: `start − mediaStart / rate`. */+export function sourceZeroTime(timing: SyncTiming): number {+ return timing.start - timing.mediaStart / rateOf(timing);+}++/** Frames `clip` sits from `partner`, positive when it plays late; null when their rates differ. */+export function syncOffsetFrames(+ clip: SyncTiming,+ partner: SyncTiming,+ fps: number,+): number | null {+ if (Math.abs(rateOf(clip) - rateOf(partner)) > 1e-6) return null;+ const frames = Math.round((sourceZeroTime(clip) - sourceZeroTime(partner)) * fps);+ return Object.is(frames, -0) ? 0 : frames;+}++/** `+10`, `-1:21` (seconds:frames once past one second). */+export function formatSyncOffset(frames: number, fps: number): string {+ const sign = frames < 0 ? "-" : "+";+ const whole = Math.abs(frames);+ const perSecond = Math.max(1, Math.round(fps));+ if (whole < perSecond) return `${sign}${whole}`;+ const seconds = Math.floor(whole / perSecond);+ const rest = String(whole % perSecond).padStart(2, "0");+ return `${sign}${seconds}:${rest}`;+}++/** Move into Sync: the start that puts `clip` back on `partner`, or null before zero. */+export function moveIntoSyncStart(clip: SyncTiming, partner: SyncTiming): number | null {+ const start = clip.start - (sourceZeroTime(clip) - sourceZeroTime(partner));+ return start >= -SYNC_TOLERANCE_S ? Math.max(0, start) : null;+}++/** Slip into Sync: the media start that syncs `clip` in place, or null before the file's start. */+export function slipIntoSyncMediaStart(clip: SyncTiming, partner: SyncTiming): number | null {+ const mediaStart = (clip.start - sourceZeroTime(partner)) * rateOf(clip);+ return mediaStart >= -SYNC_TOLERANCE_S ? Math.max(0, mediaStart) : null;+}++interface PairableElement extends AttributeReader {+ tagName: string;+ closest(selectors: string): Element | null;+ ownerDocument: Document;+}++function sharedSeconds(a: LinkTiming, b: LinkTiming): number {+ return Math.min(a.start + a.duration, b.start + b.duration) - Math.max(a.start, b.start);+}++/** `el`'s source partner (same sync origin, other tag): most shared timeline, then nearest start. */+function sameOriginInScope(el: PairableElement, tag: string, origin: string): Element[] {+ const scopeOf = (node: PairableElement) => node.closest(LINK_SCOPE_SELECTOR) ?? el.ownerDocument;+ const scope = scopeOf(el);+ return Array.from(scope.querySelectorAll(tag)).filter(+ (candidate) =>+ candidate.getAttribute(SYNC_ORIGIN_ATTR) === origin && scopeOf(candidate) === scope,+ );+}++export function findSyncPartner(el: PairableElement): Element | null {+ const origin = el.getAttribute(SYNC_ORIGIN_ATTR);+ const tag = el.tagName.toLowerCase();+ if (!origin || (tag !== "video" && tag !== "audio")) return null;+ const partnerTag = tag === "video" ? "audio" : "video";+ const own = readLinkTiming(el);+ let best: { el: Element; shared: number; distance: number } | null = null;+ for (const candidate of sameOriginInScope(el, partnerTag, origin)) {+ const timing = readLinkTiming(candidate);+ const shared = sharedSeconds(own, timing);+ const distance = Math.abs(timing.start - own.start);+ if (!best || shared > best.shared || (shared === best.shared && distance < best.distance)) {+ best = { el: candidate, shared, distance };}- el.setAttribute(MEDIA_LINK_ATTR, fresh);}+ return best?.el ?? null;}diff --git a/packages/lint/src/rules/linkedClips.ts b/packages/lint/src/rules/linkedClips.tsindex 90c5a57c23..49ff9cdb4c 100644--- a/packages/lint/src/rules/linkedClips.ts+++ b/packages/lint/src/rules/linkedClips.ts@@ -6,7 +6,7 @@ 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: "media-start", attrs: ["data-playback-start", "data-media-start"], fallback: 0 },{ field: "playback-rate", attrs: ["data-playback-rate"], fallback: 1 },];diff --git a/packages/sdk/src/engine/syncTiming.ts b/packages/sdk/src/engine/syncTiming.tsnew file mode 100644index 0000000000..cb7ef6a314--- /dev/null+++ b/packages/sdk/src/engine/syncTiming.ts@@ -0,0 +1,50 @@+import {+ findSyncPartner,+ moveIntoSyncStart,+ readLinkTiming,+ slipIntoSyncMediaStart,+ syncOffsetFrames,+} from "@hyperframes/core/media-link";+import type { HfId } from "../types.js";+import { resolveScoped } from "./model.js";++export type SyncFix =+ | { kind: "move"; start: number }+ | { kind: "slip"; name: "data-media-start" | "data-playback-start"; value: string };++function pairOf(document: Document, id: HfId): { own: Element; partner: Element } | null {+ const own = resolveScoped(document, id);+ const partner = own ? findSyncPartner(own) : null;+ return own && partner ? { own, partner } : null;+}++/** Frames `id` sits from its source partner; null when unpaired or at another rate. */+export function syncOffsetOf(document: Document, id: HfId, fps: number): number | null {+ const pair = pairOf(document, id);+ if (!pair) return null;+ return syncOffsetFrames(readLinkTiming(pair.own), readLinkTiming(pair.partner), fps);+}++const formatSeconds = (value: number) => String(Number(value.toFixed(6)));++/** The one attribute write that brings `id` back into sync, by moving or slipping it. */+export function syncFixFor(document: Document, id: HfId, mode: "move" | "slip"): SyncFix {+ const pair = pairOf(document, id);+ if (!pair) throw new Error(`${id} has no source partner (data-sync-origin)`);+ const own = readLinkTiming(pair.own);+ const partner = readLinkTiming(pair.partner);+ if (syncOffsetFrames(own, partner, 1000) === null) {+ throw new Error(`${id} and its partner play at different rates; no single sync exists`);+ }+ if (mode === "move") {+ const start = moveIntoSyncStart(own, partner);+ if (start === null) throw new Error(`moving ${id} into sync would put it before 0`);+ return { kind: "move", start: Number(start.toFixed(6)) };+ }+ const mediaStart = slipIntoSyncMediaStart(own, partner);+ if (mediaStart === null) throw new Error(`slipping ${id} into sync would start before its file`);+ const name = pair.own.hasAttribute("data-playback-start")+ ? "data-playback-start"+ : "data-media-start";+ return { kind: "slip", name, value: formatSeconds(mediaStart) };+}diff --git a/packages/sdk/src/session.sync.test.ts b/packages/sdk/src/session.sync.test.tsnew file mode 100644index 0000000000..b9121c77fe--- /dev/null+++ b/packages/sdk/src/session.sync.test.ts@@ -0,0 +1,60 @@+import { describe, expect, it } from "vitest";+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";+import { openComposition } from "./session.js";++const DRIFTED = `+<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-sync-origin="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>+ <audio data-hf-id="hf-talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2.5" data-duration="6" data-media-start="0" data-track-index="1"></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("sync origin on the SDK", () => {+ it("reports each half's signed offset in frames", async () => {+ const comp = await openComposition(DRIFTED);+ expect(comp.syncOffset("hf-talk-audio")).toBe(15);+ expect(comp.syncOffset("hf-talk", 24)).toBe(-12);+ });++ it("moveIntoSync moves that clip alone, and undo restores it", async () => {+ const comp = await openComposition(DRIFTED);+ comp.moveIntoSync("hf-talk-audio");+ expect(attr(comp.serialize(), "hf-talk-audio", "data-start")).toBe("2");+ expect(attr(comp.serialize(), "hf-talk", "data-start")).toBe("2");+ expect(comp.syncOffset("hf-talk-audio")).toBe(0);+ comp.undo();+ expect(attr(comp.serialize(), "hf-talk-audio", "data-start")).toBe("2.5");+ });++ it("slipIntoSync keeps the start and slips the media", async () => {+ const comp = await openComposition(DRIFTED);+ comp.slipIntoSync("hf-talk-audio");+ const html = comp.serialize();+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("2.5");+ expect(attr(html, "hf-talk-audio", "data-media-start")).toBe("0.5");+ expect(comp.syncOffset("hf-talk-audio")).toBe(0);+ });++ it("slips the attribute playback reads when both in-point attributes are authored", async () => {+ const both = DRIFTED.replace(+ 'data-media-start="0"',+ 'data-playback-start="0" data-media-start="0"',+ );+ const comp = await openComposition(both);+ comp.slipIntoSync("hf-talk-audio");+ const html = comp.serialize();+ const played = readMediaOffsetSeconds((name) => attr(html, "hf-talk-audio", name));+ expect(played).toBeCloseTo(0.5, 6);+ expect(comp.syncOffset("hf-talk-audio")).toBe(0);+ });++ it("refuses a slip that would start before the file", async () => {+ const comp = await openComposition(DRIFTED);+ expect(() => comp.slipIntoSync("hf-talk")).toThrow(/before its file/);+ });+});diff --git a/packages/sdk/src/session.ts b/packages/sdk/src/session.tsindex 1a77c7cc7e..86d096126d 100644--- a/packages/sdk/src/session.ts+++ b/packages/sdk/src/session.ts@@ -31,6 +31,7 @@ import type {} from "./types.js";import { ORIGIN_APPLY_PATCHES, ORIGIN_LOCAL } from "./types.js";import { buildRoots, flatElements, parsedAnimationIds } from "./document.js";+import { syncFixFor, syncOffsetOf } from "./engine/syncTiming.js";import type { PersistAdapter, PreviewAdapter } from "./adapters/types.js";import { parseMutable } from "./engine/model.js";import type { ParsedDocument } from "./engine/model.js";@@ -169,6 +170,23 @@ class CompositionImpl implements Composition {this.dispatch({ type: "setTiming", target: id, ...timing, ...opts });}+ syncOffset(id: HfId, fps = 30): number | null {+ return syncOffsetOf(this.parsed.document, id, fps);+ }++ /** Moves `id` alone; a link group it belongs to is left (as `setTiming` `linked: false`). */+ moveIntoSync(id: HfId): void {+ const fix = syncFixFor(this.parsed.document, id, "move");+ if (fix.kind === "move")+ this.dispatch({ type: "setTiming", target: id, start: fix.start, linked: false });+ }++ slipIntoSync(id: HfId): void {+ const fix = syncFixFor(this.parsed.document, id, "slip");+ if (fix.kind === "slip")+ this.dispatch({ type: "setAttribute", target: id, name: fix.name, value: fix.value });+ }+removeElement(id: HfId): void {this.dispatch({ type: "removeElement", target: id });}diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.tsindex d4599cabc9..52e078f238 100644--- a/packages/sdk/src/types.ts+++ b/packages/sdk/src/types.ts@@ -435,6 +435,10 @@ export interface Composition {timing: { start?: number; duration?: number; trackIndex?: number },opts?: { linked?: boolean },): void;+ /** Frames `id` sits from its `data-sync-origin` partner, positive when late; null if unpaired or rates differ. */+ syncOffset(id: HfId, fps?: number): number | null;+ moveIntoSync(id: HfId): void;+ slipIntoSync(id: HfId): 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/freezeFrame.test.ts b/packages/studio-server/src/helpers/freezeFrame.test.tsindex 8767d1bc85..e7a70ce3ec 100644--- a/packages/studio-server/src/helpers/freezeFrame.test.ts+++ b/packages/studio-server/src/helpers/freezeFrame.test.ts@@ -142,8 +142,8 @@ describe("applyFreezeFrameToHtml", () => {it("splits the linked audio, leaving a silent gap, and links the right halves together", () => {expect(timing(html, "talk-audio")).toEqual(["1", "2.2"]);expect(timing(html, "talk-audio-split")).toEqual(["5.2", "3.8"]);- expect(at(html, "talk-split")?.getAttribute("data-link")).toBe("L-2");- expect(at(html, "talk-audio-split")?.getAttribute("data-link")).toBe("L-2");+ expect(at(html, "talk-split")?.getAttribute("data-link")).toBe("lk-1");+ expect(at(html, "talk-audio-split")?.getAttribute("data-link")).toBe("lk-1");expect(at(html, "talk-audio")?.getAttribute("data-link")).toBe("L");});diff --git a/packages/studio-server/src/helpers/freezeFrame.ts b/packages/studio-server/src/helpers/freezeFrame.tsindex 4630f5551e..583e964af1 100644--- a/packages/studio-server/src/helpers/freezeFrame.ts+++ b/packages/studio-server/src/helpers/freezeFrame.ts@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";import { ensureHfIds } from "@hyperframes/parsers/hf-ids";import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";import { resolveRateSpec, sourceTimeAt } from "@hyperframes/core/speed-ramp";+import { MEDIA_LINK_ATTR as LINK_ATTR, relinkSplitHalves } from "@hyperframes/core/media-link";import {findTargetElement,isHTMLElement,@@ -11,7 +12,6 @@ import {} from "./sourceMutation.js";const FREEZE_HOLD_SECONDS = 2;-const LINK_ATTR = "data-link";const EPSILON = 1e-3;const round3 = (value: number) => Math.round(value * 1000) / 1000;@@ -195,12 +195,6 @@ function splitAll(return { html: next, rightHalfIds };}-function relinkRightHalves(document: Document, link: string | null, ids: readonly string[]): void {- if (!link) return;- const rightLink = uniqueLink(document, link);- for (const id of ids) document.getElementById(id)?.setAttribute(LINK_ATTR, rightLink);-}-/*** Split the video at the playhead, put a still of that frame in the gap and push the rest of its* track (and a linked partner's, which is split too and left silent for the hold) right by the hold.@@ -228,7 +222,7 @@ export function applyFreezeFrameToHtml(if (!cut) return null;const { document, wrappedFragment } = parseSourceDocument(cut.html);- relinkRightHalves(document, video.getAttribute(LINK_ATTR), cut.rightHalfIds);+ relinkSplitHalves(document, cut.rightHalfIds);shiftTracks(document, tracks, input.playhead, hold);const leftHalf = findTargetElement(document, input.target);if (!leftHalf?.parentElement) return null;@@ -246,12 +240,3 @@ export function applyFreezeFrameToHtml(freezeId,};}--function uniqueLink(document: Document, base: string): string {- const taken = new Set(- Array.from(document.querySelectorAll(`[${LINK_ATTR}]`)).map((el) => el.getAttribute(LINK_ATTR)),- );- let candidate = `${base}-2`;- for (let n = 3; taken.has(candidate); n++) candidate = `${base}-${n}`;- return candidate;-}diff --git a/packages/studio-server/src/helpers/sourceMutation.ts b/packages/studio-server/src/helpers/sourceMutation.tsindex 66873d43bc..ccf8216846 100644--- a/packages/studio-server/src/helpers/sourceMutation.ts+++ b/packages/studio-server/src/helpers/sourceMutation.ts@@ -702,10 +702,14 @@ export function unwrapElementsFromHtml(};}-/** After a cut, give each linked group's right halves their own shared `data-link`. */+/** After a cut, give each linked group's right halves their own `data-link` and `data-sync-origin`. */export function relinkSplitHalvesInHtml(source: string, rightHalfIds: readonly string[]): string {const { document, wrappedFragment } = parseSourceDocument(source);- if (!rightHalfIds.some((id) => document.getElementById(id)?.hasAttribute("data-link"))) {+ const carriesPairing = (id: string) => {+ const el = document.getElementById(id);+ return Boolean(el?.hasAttribute("data-link") || el?.hasAttribute("data-sync-origin"));+ };+ if (!rightHalfIds.some(carriesPairing)) {return source;}relinkSplitHalves(document, rightHalfIds);diff --git a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.tsindex 2ed4297a8d..47208de26e 100644--- a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts+++ b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts@@ -411,6 +411,19 @@ describe("relinkSplitHalvesInHtml", () => {expect(link("a-split")).toBe("lk-2");});+ it("gives an unlinked pair's right halves their own sync origin", () => {+ const source =+ '<div data-composition-id="c"><video id="v" src="t.mp4" muted data-sync-origin="lk-1" data-start="0" data-duration="4"></video><audio id="a" src="t.mp4" data-sync-origin="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 origin = (id: string) =>+ new RegExp(`id="${id}"[^>]*data-sync-origin="([^"]+)"`).exec(html)?.[1];+ expect(origin("v")).toBe("lk-1");+ expect(origin("v-split")).not.toBe("lk-1");+ expect(origin("v-split")).toBe(origin("a-split"));+ });+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/src/components/LinkedSelectionToggle.tsx b/packages/studio/src/components/LinkedSelectionToggle.tsxnew file mode 100644index 0000000000..8f01a2d144--- /dev/null+++ b/packages/studio/src/components/LinkedSelectionToggle.tsx@@ -0,0 +1,73 @@+import { useCallback, useState } from "react";+import { createPortal } from "react-dom";+import { LinkSimple } from "@phosphor-icons/react";+import { useContextMenuDismiss } from "../hooks/useContextMenuDismiss";+import { useMenuKeyboardNav } from "../player/components/menuKeyboardNav";+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";+import { Tooltip } from "./ui";+import { flatActive, flatIdle } from "./timelineToolbarStyles";++function SyncIndicatorMenu({ x, y, onClose }: { x: number; y: number; onClose: () => void }) {+ const menuRef = useContextMenuDismiss(onClose);+ useMenuKeyboardNav(menuRef);+ const visible = useLinkedClipPreferences((s) => s.syncIndicatorsVisible);+ const setVisible = useLinkedClipPreferences((s) => s.setSyncIndicatorsVisible);+ return createPortal(+ <div+ ref={menuRef}+ role="menu"+ aria-label="Linked clips"+ className="fixed z-200 min-w-[200px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"+ style={{ left: x, top: y }}+ >+ <button+ type="button"+ role="menuitemcheckbox"+ aria-checked={visible}+ className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800"+ onClick={() => {+ setVisible(!visible);+ onClose();+ }}+ >+ <span className="w-3 text-studio-accent">{visible ? "✓" : ""}</span>+ Show out-of-sync indicators+ </button>+ </div>,+ document.body,+ );+}++/** Premiere's Linked Selection; right-click holds the out-of-sync indicator preference. */+export function LinkedSelectionToggle() {+ const linkedSelection = useLinkedClipPreferences((s) => s.linkedSelection);+ const setLinkedSelection = useLinkedClipPreferences((s) => s.setLinkedSelection);+ const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);+ const closeMenu = useCallback(() => setMenuAt(null), []);+ return (+ <>+ <Tooltip+ label={+ linkedSelection+ ? "Linked Selection on — a click selects both halves (⌥-click for one)"+ : "Linked Selection off — a click selects one clip"+ }+ >+ <button+ type="button"+ onClick={() => setLinkedSelection(!linkedSelection)}+ onContextMenu={(e) => {+ e.preventDefault();+ setMenuAt({ x: e.clientX, y: e.clientY });+ }}+ aria-label="Linked Selection"+ aria-pressed={linkedSelection}+ className={linkedSelection ? flatActive : flatIdle}+ >+ <LinkSimple size={16} weight="bold" aria-hidden="true" />+ </button>+ </Tooltip>+ {menuAt && <SyncIndicatorMenu x={menuAt.x} y={menuAt.y} onClose={closeMenu} />}+ </>+ );+}diff --git a/packages/studio/src/components/TimelineToolbar.test.tsx b/packages/studio/src/components/TimelineToolbar.test.tsxindex 778194ab62..d9de1d7fe4 100644--- a/packages/studio/src/components/TimelineToolbar.test.tsx+++ b/packages/studio/src/components/TimelineToolbar.test.tsx@@ -391,3 +391,34 @@ describe("TimelineToolbar add beat", () => {act(() => root.unmount());});});++describe("TimelineToolbar Linked Selection", () => {+ it("is on by default, first among the editing toggles, and persists a click", async () => {+ const { useLinkedClipPreferences } = await import("../utils/linkedClipPreferences");+ const { host } = renderToolbar();+ const button = host.querySelector<HTMLButtonElement>('button[aria-label="Linked Selection"]');+ expect(button?.getAttribute("aria-pressed")).toBe("true");+ const snapping = host.querySelector('button[aria-label="Toggle timeline snapping"]');+ expect(snapping && button?.compareDocumentPosition(snapping)).toBe(+ Node.DOCUMENT_POSITION_FOLLOWING,+ );+ act(() => button?.dispatchEvent(new MouseEvent("click", { bubbles: true })));+ expect(button?.getAttribute("aria-pressed")).toBe("false");+ expect(readStudioUiPreferences().linkedSelectionEnabled).toBe(false);+ act(() => useLinkedClipPreferences.getState().setLinkedSelection(true));+ });++ it("right-click toggles the out-of-sync indicator preference", async () => {+ const { useLinkedClipPreferences } = await import("../utils/linkedClipPreferences");+ const { host } = renderToolbar();+ const button = host.querySelector('button[aria-label="Linked Selection"]');+ act(() => button?.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true })));+ const item = document.querySelector<HTMLButtonElement>('[role="menuitemcheckbox"]');+ expect(item?.textContent).toContain("Show out-of-sync indicators");+ expect(item?.getAttribute("aria-checked")).toBe("true");+ act(() => item?.click());+ expect(useLinkedClipPreferences.getState().syncIndicatorsVisible).toBe(false);+ expect(readStudioUiPreferences().syncIndicatorsVisible).toBe(false);+ act(() => useLinkedClipPreferences.getState().setSyncIndicatorsVisible(true));+ });+});diff --git a/packages/studio/src/components/TimelineToolbar.tsx b/packages/studio/src/components/TimelineToolbar.tsxindex fc4424f6d9..7f0da96b33 100644--- a/packages/studio/src/components/TimelineToolbar.tsx+++ b/packages/studio/src/components/TimelineToolbar.tsx@@ -31,6 +31,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";import type { DomEditSelection } from "./editor/domEditingTypes";import { canSplitElement } from "../utils/timelineElementSplit";import { useAudioMetersVisible } from "../utils/audioMeterVisibility";+import { LinkedSelectionToggle } from "./LinkedSelectionToggle";import { useProjectHasAudio } from "../utils/audioMeterMath";import { canAddBeatAt, addBeatAtCompositionTime } from "../utils/beatEditActions";import { isTypingTarget } from "../utils/typingTarget";@@ -218,6 +219,7 @@ export function TimelineToolbar({<TimelineToolPicker showSelectAroundPlayhead={showSelectAroundPlayhead} />{/* Divider: tool-mode | editing-actions */}<div aria-hidden="true" className="mx-1 h-4 w-px bg-neutral-800" />+ <LinkedSelectionToggle /><Tooltip label={timelineSnapEnabled ? "Snapping on (N)" : "Snapping off (N)"}><buttontype="button"diff --git a/packages/studio/src/components/editor/PropertyPanelFlat.tsx b/packages/studio/src/components/editor/PropertyPanelFlat.tsxindex a33deaacd8..035a4a3dc4 100644--- a/packages/studio/src/components/editor/PropertyPanelFlat.tsx+++ b/packages/studio/src/components/editor/PropertyPanelFlat.tsx@@ -5,6 +5,7 @@ import { DesignPanelInputProvider } from "../../contexts/DesignPanelInputContextimport { slugifyDesignInput } from "../../utils/designInputTracking";import { isTextEditableSelection } from "./domEditing";import type { PropertyPanelFlatProps } from "./propertyPanelFlatProps";+import { useLinkedSpeedCommit, withLinkedPlaybackRate } from "./linkedSpeedEdits";import { formatPxMetricValue } from "./propertyPanelHelpers";import { audioFxSummary } from "./audioFxSummary";import { resolveAudioGroups } from "@hyperframes/core/audio-groups";@@ -289,10 +290,12 @@ export function PropertyPanelFlat({const showMotionEffects = gsapEffectHandlers !== null && !audioSelection;const showMotionGroup = showMotionTiming || showMotionEffects;+ const linkedSpeed = useLinkedSpeedCommit(element, forwardedProps.onSetAttributeBatch);const volumeAutomation = useVolumeAutomation(element,currentTime,onSetAttributeQuiet ?? onSetAttributeLive,+ linkedSpeed,);// The group this clip belongs to, if any — the Audio FX summary reads@@ -505,7 +508,7 @@ export function PropertyPanelFlat({element={element}styles={styles}onSetStyle={onSetStyle}- onSetAttribute={onSetAttribute}+ onSetAttribute={withLinkedPlaybackRate(onSetAttribute, linkedSpeed)}{...volumeAutomation}/>),diff --git a/packages/studio/src/components/editor/linkedSpeedEdits.test.tsx b/packages/studio/src/components/editor/linkedSpeedEdits.test.tsxnew file mode 100644index 0000000000..b6d7cf14c0--- /dev/null+++ b/packages/studio/src/components/editor/linkedSpeedEdits.test.tsx@@ -0,0 +1,164 @@+// @vitest-environment happy-dom+import { act } from "react";+import { describe, expect, it, vi } from "vitest";+import { createHappyDomRootHarness } from "../../player/components/testRootHarness";+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";+import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";+import type { DomEditSelection } from "./domEditingTypes";+import {+ fanOutAttributeInSource,+ linkedPartnerTargets,+ useLinkedSpeedCommit,+ withLinkedPlaybackRate,+ type LinkedSpeedCommit,+} from "./linkedSpeedEdits";+import { useVolumeAutomation } from "./useVolumeAutomation";+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";++const clip = (id: string, tag: string, link?: string): TimelineElement => ({+ id,+ domId: id,+ tag,+ start: 0,+ duration: 4,+ track: 0,+ ...(link ? { link } : {}),+});++const elements = [+ clip("talk", "video", "lk-1"),+ clip("talk-audio", "audio", "lk-1"),+ clip("music", "audio"),+];++const source = `<div data-composition-id="main">+<video id="talk" data-start="0" data-duration="4" data-link="lk-1" muted></video>+<audio id="talk-audio" data-start="0" data-duration="4" data-link="lk-1" data-automation="{"version":1,"lanes":[]}"></audio>+<audio id="music" data-start="0" data-duration="4"></audio>+</div>`;++function selection(id: string, dataAttributes: Record<string, string> = {}): DomEditSelection {+ const element = document.createElement("video");+ element.id = id;+ return {+ id,+ element,+ label: id,+ tagName: "video",+ sourceFile: "index.html",+ compositionPath: "index.html",+ isCompositionHost: false,+ isInsideLockedComposition: false,+ boundingBox: { x: 0, y: 0, width: 0, height: 0 },+ textContent: null,+ dataAttributes: { start: "0", duration: "4", ...dataAttributes },+ inlineStyles: {},+ computedStyles: {},+ textFields: [],+ capabilities: {+ canSelect: true,+ canEditStyles: true,+ canCrop: true,+ canMove: true,+ canResize: true,+ canApplyManualOffset: true,+ canApplyManualSize: true,+ canApplyManualRotation: true,+ },+ };+}++describe("linkedPartnerTargets", () => {+ it("returns the other data-link members and nothing for an unlinked clip", () => {+ expect(linkedPartnerTargets({ id: "talk" }, elements)).toEqual([{ id: "talk-audio" }]);+ expect(linkedPartnerTargets({ id: "music" }, elements)).toEqual([]);+ });++ it("reaches no partner with Linked Selection off", () => {+ useLinkedClipPreferences.getState().setLinkedSelection(false);+ try {+ expect(linkedPartnerTargets({ id: "talk" }, elements)).toEqual([]);+ } finally {+ useLinkedClipPreferences.getState().setLinkedSelection(true);+ }+ });+});++describe("fanOutAttributeInSource", () => {+ it("writes each partner from its own current value", () => {+ const seen: Array<string | undefined> = [];+ const next = fanOutAttributeInSource(+ source,+ [{ id: "talk-audio" }],+ "data-automation",+ (raw) => {+ seen.push(raw);+ return "rate-lane";+ },+ );+ expect(seen).toEqual(['{"version":1,"lanes":[]}']);+ expect(next).toContain(+ 'id="talk-audio" data-start="0" data-duration="4" data-link="lk-1" data-automation="rate-lane"',+ );+ expect(next).not.toContain('id="music" data-start="0" data-duration="4" data-automation');+ });+});++const harness = createHappyDomRootHarness();++function renderLinked(sel: DomEditSelection, commit: CommitDomAttributeBatch) {+ let linked: LinkedSpeedCommit | null = null;+ let rate: ReturnType<typeof useVolumeAutomation>["rate"] | null = null;+ function Probe() {+ linked = useLinkedSpeedCommit(sel, commit);+ rate = useVolumeAutomation(sel, 0, vi.fn(), linked).rate;+ return null;+ }+ const host = document.createElement("div");+ document.body.appendChild(host);+ act(() => harness.mount(host).render(<Probe />));+ return { linked: () => linked, rate: () => rate };+}++describe("linked speed edits", () => {+ it("fans a playback-rate edit out to the partner in one batch commit", async () => {+ usePlayerStore.getState().setElements(elements);+ const commit = vi.fn<CommitDomAttributeBatch>(async () => true);+ const onSetAttribute = vi.fn();+ const probe = renderLinked(selection("talk"), commit);+ await withLinkedPlaybackRate(onSetAttribute, probe.linked())("playback-rate", "2");+ expect(onSetAttribute).not.toHaveBeenCalled();+ expect(commit).toHaveBeenCalledTimes(1);+ const [, ops, options] = commit.mock.calls[0] ?? [];+ expect(ops).toEqual([{ type: "attribute", property: "playback-rate", value: "2" }]);+ expect(options?.prepareContent?.(source)).toContain(+ 'id="talk-audio" data-start="0" data-duration="4" data-link="lk-1" data-automation="{"version":1,"lanes":[]}" data-playback-rate="2"',+ );+ });++ it("fans a ramp preset out as one commit carrying each member's rate lane", () => {+ usePlayerStore.getState().setElements(elements);+ const commit = vi.fn<CommitDomAttributeBatch>(async () => true);+ const probe = renderLinked(selection("talk"), commit);+ act(() => probe.rate()?.onApplyPreset("ramp-in"));+ expect(commit).toHaveBeenCalledTimes(1);+ const [, ops, options] = commit.mock.calls[0] ?? [];+ expect(ops?.[0]?.property).toBe("automation");+ expect(String(ops?.[0]?.value)).toContain('"target":"rate"');+ const partner = /id="talk-audio"[^>]*data-automation="([^"]*)"/.exec(+ options?.prepareContent?.(source) ?? "",+ )?.[1];+ expect(partner).toContain("rate");+ });++ it("leaves an unlinked clip on its usual write path", async () => {+ usePlayerStore.getState().setElements(elements);+ const commit = vi.fn<CommitDomAttributeBatch>(async () => true);+ const onSetAttribute = vi.fn();+ const probe = renderLinked(selection("music"), commit);+ expect(probe.linked()).toBeNull();+ await withLinkedPlaybackRate(onSetAttribute, probe.linked())("playback-rate", "2");+ expect(onSetAttribute).toHaveBeenCalledWith("playback-rate", "2");+ expect(commit).not.toHaveBeenCalled();+ });+});diff --git a/packages/studio/src/components/editor/linkedSpeedEdits.ts b/packages/studio/src/components/editor/linkedSpeedEdits.tsnew file mode 100644index 0000000000..3814454752--- /dev/null+++ b/packages/studio/src/components/editor/linkedSpeedEdits.ts@@ -0,0 +1,94 @@+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";+import { expandToLinkedMembers } from "../../player/components/audioClipLink";+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";+import {+ applyPatchByTarget,+ readAttributeByTarget,+ type PatchTarget,+} from "../../utils/sourcePatcher";+import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";+import { buildPatchTarget } from "../../hooks/timelineEditingHelpers";+import type { DomEditSelection } from "./domEditingTypes";++type AttributeValueFor = (current: string | undefined) => string | null;++/** Writes a speed attribute on the selection and every `data-link` partner as one undo step. */+export interface LinkedSpeedCommit {+ commitAttribute: (attr: string, valueFor: AttributeValueFor, label: string) => Promise<boolean>;+}++const keyOf = (el: TimelineElement) => el.key ?? el.id;+const dataProperty = (attr: string) => (attr.startsWith("data-") ? attr.slice(5) : attr);++function isSelected(el: TimelineElement, selection: PatchTarget): boolean {+ if (selection.hfId && el.hfId) return el.hfId === selection.hfId;+ return selection.id != null && (el.domId ?? el.id) === selection.id;+}++export function linkedPartnerTargets(+ selection: PatchTarget,+ elements: readonly TimelineElement[],+): PatchTarget[] {+ const self = elements.find((el) => isSelected(el, selection));+ if (!self?.link) return [];+ const members = expandToLinkedMembers([keyOf(self)], elements, isLinkedSelectionOn());+ members.delete(keyOf(self));+ return elements+ .filter((el) => members.has(keyOf(el)))+ .map(buildPatchTarget)+ .filter((target): target is NonNullable<typeof target> => target !== null);+}++export function fanOutAttributeInSource(+ source: string,+ targets: readonly PatchTarget[],+ attr: string,+ valueFor: AttributeValueFor,+): string {+ const property = dataProperty(attr);+ return targets.reduce(+ (html, target) =>+ applyPatchByTarget(html, target, {+ type: "attribute",+ property,+ value: valueFor(readAttributeByTarget(html, target, attr)),+ }),+ source,+ );+}++/** Null when the selection has no link partner, so unlinked clips keep their usual write path. */+export function useLinkedSpeedCommit(+ selection: DomEditSelection,+ commit: CommitDomAttributeBatch | undefined,+): LinkedSpeedCommit | null {+ const elements = usePlayerStore((s) => s.elements);+ if (!commit) return null;+ const partners = linkedPartnerTargets(selection, elements);+ if (partners.length === 0) return null;+ return {+ commitAttribute: (attr, valueFor, label) => {+ const property = dataProperty(attr);+ return commit(+ selection,+ [{ type: "attribute", property, value: valueFor(selection.dataAttributes[property]) }],+ {+ label,+ prepareContent: (html) => fanOutAttributeInSource(html, partners, attr, valueFor),+ },+ );+ },+ };+}++/** Routes `playback-rate` through the linked commit; every other attribute keeps `onSetAttribute`. */+export function withLinkedPlaybackRate(+ onSetAttribute: (attr: string, value: string) => void | Promise<void>,+ linked: LinkedSpeedCommit | null,+): (attr: string, value: string) => void | Promise<void> {+ if (!linked) return onSetAttribute;+ return async (attr, value) => {+ if (attr !== "playback-rate") return onSetAttribute(attr, value);+ await linked.commitAttribute("data-playback-rate", () => value, "Edit speed");+ };+}diff --git a/packages/studio/src/components/editor/mediaAudioEdits.test.ts b/packages/studio/src/components/editor/mediaAudioEdits.test.tsindex 199d0f49ac..bca8dc7449 100644--- a/packages/studio/src/components/editor/mediaAudioEdits.test.ts+++ b/packages/studio/src/components/editor/mediaAudioEdits.test.ts@@ -177,6 +177,8 @@ describe("buildKeepSoundCutoutEdit", () => {]);expect(audio.getAttribute("data-link")).toBe(video.getAttribute("data-link"));expect(video.getAttribute("data-link")).toBe("lk-1");+ expect(video.getAttribute("data-sync-origin")).toBe("lk-1");+ expect(audio.getAttribute("data-sync-origin")).toBe("lk-1");expect(audio.parentElement).toBe(video.parentElement);});diff --git a/packages/studio/src/components/editor/mediaAudioEdits.ts b/packages/studio/src/components/editor/mediaAudioEdits.tsindex 7b22ce7bb6..7949291e90 100644--- a/packages/studio/src/components/editor/mediaAudioEdits.ts+++ b/packages/studio/src/components/editor/mediaAudioEdits.ts@@ -23,7 +23,11 @@ import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";import { buildDomEditPatchTarget, type DomEditSelection } from "./domEditing";import { generateId } from "../../utils/generateId";-import { MEDIA_LINK_ATTR, mintLinkId as mintLinkIdFrom } from "@hyperframes/core/media-link";+import {+ MEDIA_LINK_ATTR,+ SYNC_ORIGIN_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 =@@ -100,10 +104,14 @@ export function firstFreeName(base: string, taken: Set<string>): string {export function mintLinkId(doc: Document): string {const taken = new Set<string>();- for (const el of Array.from(doc.querySelectorAll(`[id], [${MEDIA_LINK_ATTR}]`))) {- if (el.id) taken.add(el.id);- const link = el.getAttribute(MEDIA_LINK_ATTR);- if (link) taken.add(link);+ const selector = `[id], [${MEDIA_LINK_ATTR}], [${SYNC_ORIGIN_ATTR}]`;+ for (const el of Array.from(doc.querySelectorAll(selector))) {+ for (const value of [+ el.id,+ el.getAttribute(MEDIA_LINK_ATTR),+ el.getAttribute(SYNC_ORIGIN_ATTR),+ ])+ if (value) taken.add(value);}return mintLinkIdFrom(taken);}@@ -187,7 +195,10 @@ export function buildKeepSoundCutoutEdit(input: {movedSound.push([HF_AUDIO_AUTOMATION_ATTR, audioTakes]);ops.push(dataAttr(stripDataPrefix(HF_AUDIO_AUTOMATION_ATTR), videoKeeps));}- ops.push(dataAttr(stripDataPrefix(MEDIA_LINK_ATTR), linkId));+ ops.push(+ dataAttr(stripDataPrefix(MEDIA_LINK_ATTR), linkId),+ dataAttr(stripDataPrefix(SYNC_ORIGIN_ATTR), linkId),+ );const prepareContent = (source: string): string => {const originalSrc = readAuthoredSrc(source, target);@@ -208,6 +219,7 @@ export function buildKeepSoundCutoutEdit(input: {...timing,["data-track-index", String(firstFreeTrackIndex(source))],[MEDIA_LINK_ATTR, linkId],+ [SYNC_ORIGIN_ATTR, linkId],...movedSound,];if (video.hasAttribute("loop")) attrs.push(["loop", ""]);diff --git a/packages/studio/src/components/editor/mediaLinkEdits.test.ts b/packages/studio/src/components/editor/mediaLinkEdits.test.tsindex 70c7fbb017..5fbc15e534 100644--- a/packages/studio/src/components/editor/mediaLinkEdits.test.ts+++ b/packages/studio/src/components/editor/mediaLinkEdits.test.ts@@ -54,6 +54,7 @@ describe("detachAudioInSource", () => {"data-playback-rate": "1","data-track-index": "2","data-link": result?.linkId,+ "data-sync-origin": result?.linkId,"data-volume": "0.5","data-fade-in": "0.3","data-fade-out": "0.2",@@ -68,6 +69,7 @@ describe("detachAudioInSource", () => {const after = attrsOf(result?.html ?? "", "video#talk");expect(after).toHaveProperty("muted");expect(after["data-link"]).toBe(result?.linkId);+ expect(after["data-sync-origin"]).toBe(result?.linkId);for (const gone of ["data-has-audio","data-volume",@@ -179,7 +181,14 @@ describe("removeElementInSource", () => {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">');+ expect(linkInSource(src, [{ id: "a" }])).toContain(+ '<audio id="a" data-link="lk-3" data-sync-origin="lk-3">',+ );+ });++ it("skips ids already used as a sync origin", () => {+ const src = '<video id="v" data-sync-origin="lk-1"></video><audio id="a"></audio>';+ expect(linkInSource(src, [{ id: "a" }])).toContain('data-link="lk-2"');});});@@ -192,6 +201,17 @@ describe("setLinkInSource", () => {);expect(setLinkInSource(linked, [{ id: "v" }, { id: "a" }], null)).toBe(src);});++ it("keeps the sync origin when unlinking", () => {+ const linked = linkInSource('<video id="v"></video><audio id="a"></audio>', [+ { id: "v" },+ { id: "a" },+ ]);+ const unlinked = setLinkInSource(linked, [{ id: "v" }, { id: "a" }], null);+ expect(unlinked).toBe(+ '<video id="v" data-sync-origin="lk-1"></video><audio id="a" data-sync-origin="lk-1"></audio>',+ );+ });});const el = (id: string, tag: string, extra: Record<string, unknown> = {}) => ({diff --git a/packages/studio/src/components/editor/mediaLinkEdits.ts b/packages/studio/src/components/editor/mediaLinkEdits.tsindex f98c26c87a..999895e721 100644--- a/packages/studio/src/components/editor/mediaLinkEdits.ts+++ b/packages/studio/src/components/editor/mediaLinkEdits.ts@@ -1,5 +1,5 @@import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";-import { MEDIA_LINK_ATTR, mintLinkId } from "@hyperframes/core/media-link";+import { MEDIA_LINK_ATTR, SYNC_ORIGIN_ATTR, mintLinkId } from "@hyperframes/core/media-link";import { sameCompositionScope, type TimelineElement } from "../../player/store/timelineElement";import { mediaAssetIdentity, sharesLinkGroup } from "../../player/components/audioClipLink";import {@@ -23,6 +23,7 @@ import {const LINK_PROPERTY = MEDIA_LINK_ATTR.slice("data-".length);const HIDDEN_ATTR = "data-hidden";+const SYNC_ORIGIN_PROPERTY = SYNC_ORIGIN_ATTR.slice("data-".length);const SYNC_TOLERANCE_S = 1e-3;const dataOp = (property: string, value: string | null): PatchOperation => ({@@ -43,7 +44,7 @@ function applyOps(source: string, target: PatchTarget, ops: readonly PatchOperatfunction mintLinkIdForSource(source: string): string {const links = Array.from(- source.matchAll(/\bdata-link=["']([^"']+)["']/g),+ source.matchAll(/\bdata-(?:link|sync-origin)=["']([^"']+)["']/g),(match) => match[1] ?? "",);return mintLinkId([...collectHtmlIds(source), ...links]);@@ -61,9 +62,14 @@ export function setLinkInSource();}-/** Link the targets under one freshly minted id. */+/** Link the targets under one freshly minted id, which is also their sync origin. */export function linkInSource(source: string, targets: readonly PatchTarget[]): string {- return setLinkInSource(source, targets, mintLinkIdForSource(source));+ const linkId = mintLinkIdForSource(source);+ return targets.reduce(+ (html, target) =>+ applyOps(html, target, [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]),+ source,+ );}/** Remove one element (open tag through its matching close tag) and its line's indentation. */@@ -126,7 +132,7 @@ export function detachAudioInSource(moved.push([HF_AUDIO_AUTOMATION_ATTR, audioTakes]);videoOps.push(dataOp(HF_AUDIO_AUTOMATION_ATTR, videoKeeps));}- videoOps.push(dataOp(LINK_PROPERTY, linkId));+ videoOps.push(dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId));const timing: Array<[string, string]> = [];for (const name of COPIED_TIMING_ATTRS) {@@ -141,6 +147,7 @@ export function detachAudioInSource(...timing,["data-track-index", String(input.track)],[MEDIA_LINK_ATTR, linkId],+ [SYNC_ORIGIN_ATTR, linkId],...moved,];if (hasBooleanAttr(source, target, "loop")) attrs.push(["loop", ""]);@@ -172,7 +179,12 @@ export function mergeAudioInSource(}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"));+ videoOps.push(+ htmlOp("muted", null),+ dataOp(LINK_PROPERTY, null),+ dataOp(SYNC_ORIGIN_PROPERTY, null),+ dataOp("has-audio", "true"),+ );return applyOps(removeElementInSource(source, audioTarget), videoTarget, videoOps);}diff --git a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsxindex b479e00f44..64aa15308a 100644--- a/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx+++ b/packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx@@ -880,6 +880,7 @@ describe.each<PanelKind>(["flat", "design"])("%s panel — cutout keeps the soundataOp("has-audio", null),dataOp("volume", null),dataOp("link", "lk-1"),+ dataOp("sync-origin", "lk-1"),]);const source ='<div data-composition-id="main"><video id="s1-bg" src="assets/intro-loop.mp4" muted data-start="2" data-duration="3" data-track-index="0" data-link="lk-1"></video></div>';diff --git a/packages/studio/src/components/editor/propertyPanelMediaSection.tsx b/packages/studio/src/components/editor/propertyPanelMediaSection.tsxindex c86db6461d..a8b57892d7 100644--- a/packages/studio/src/components/editor/propertyPanelMediaSection.tsx+++ b/packages/studio/src/components/editor/propertyPanelMediaSection.tsx@@ -24,6 +24,7 @@ import {audioGainToText,} from "@hyperframes/core/audio-gain";import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";+import { useLinkedSpeedCommit, withLinkedPlaybackRate } from "./linkedSpeedEdits";import { commitCutout, commitHasAudioToggle, commitMutedToggle } from "./mediaAudioEdits";// fallow-ignore-next-line complexity@@ -56,6 +57,10 @@ export function MediaSection({) => Promise<BackgroundRemovalResult>;}) {const track = useTrackDesignInput();+ const setRate = withLinkedPlaybackRate(+ onSetAttribute,+ useLinkedSpeedCommit(element, onSetAttributeBatch),+ );const isVideo = element.tagName === "video";const isAudio = element.tagName === "audio";const isImage = element.tagName === "img";@@ -279,7 +284,7 @@ export function MediaSection({displayValue={`${formatNumericValue(playbackRate)}x`}formatDisplayValue={(next) => `${formatNumericValue(next / 100)}x`}onCommit={(next) => {- void onSetAttribute("playback-rate", formatNumericValue(next / 100));+ void setRate("playback-rate", formatNumericValue(next / 100));}}/></div>diff --git a/packages/studio/src/components/editor/useVolumeAutomation.ts b/packages/studio/src/components/editor/useVolumeAutomation.tsindex f0fe065dc4..f45e2617bf 100644--- a/packages/studio/src/components/editor/useVolumeAutomation.ts+++ b/packages/studio/src/components/editor/useVolumeAutomation.ts@@ -26,6 +26,8 @@ import {import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";import { SPEED_PRESETS, speedPresetLane, type SpeedPresetId } from "@hyperframes/core/speed-ramp";import { clampNumber } from "../../utils/studioHelpers";+import type { HfAutomation } from "@hyperframes/core/audio-automation";+import type { LinkedSpeedCommit } from "./linkedSpeedEdits";export interface LaneBinding {automated: boolean;@@ -59,6 +61,7 @@ export function useVolumeAutomation(element: DomEditSelection,currentTime: number,onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,+ linkedSpeed: LinkedSpeedCommit | null = null,): VolumeAutomationBinding {// The chain is not needed to resolve a volume or rate lane: both are always valid// targets, so this deliberately does not parse it.@@ -77,7 +80,22 @@ export function useVolumeAutomation(// playing track, while the same click on an effect parameter did not.void onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(next) || null);};- const laneBinding = (target: string, seed: number): LaneBinding => {+ type Edit = (current: HfAutomation) => HfAutomation;+ const writeOwn = (edit: Edit) => write(edit(automation));+ // Speed moves every data-link member together, so a linked clip's rate lane edits fan out.+ const writeRate = (edit: Edit) => {+ if (!linkedSpeed) return writeOwn(edit);+ void linkedSpeed.commitAttribute(+ HF_AUDIO_AUTOMATION_ATTR,+ (raw) => automationAttrValue(edit(readPanelAutomation(raw, undefined))) || null,+ "Edit speed",+ );+ };+ const laneBinding = (+ target: string,+ seed: number,+ writeLane: (edit: Edit) => void,+ ): LaneBinding => {const lane = automation.lanes.find((l) => l.target === target);return {automated: lane !== undefined,@@ -85,9 +103,9 @@ export function useVolumeAutomation(? sampleAutomationLane(lane, clipTimeSec, resolveAutomationRange(target, undefined)?.scale): undefined,// Seeded at the level the control already shows, so automating does not change it.- onAutomate: () => write(withSeededLane(automation, target, seed)),- onRemoveAutomation: () => write(withoutLane(automation, target)),- onCommitAt: (v: number) => write(withPointAt(automation, target, clipTimeSec, v)),+ onAutomate: () => writeLane((a) => withSeededLane(a, target, seed)),+ onRemoveAutomation: () => writeLane((a) => withoutLane(a, target)),+ onCommitAt: (v: number) => writeLane((a) => withPointAt(a, target, clipTimeSec, v)),};};// `??` alone would let an empty `data-volume` through as Number("") === 0, so@@ -96,9 +114,13 @@ export function useVolumeAutomation(const raw = element.dataAttributes?.["volume"];const parsed = raw ? Number(raw) : 1;const current = Number.isFinite(parsed) ? parsed : 1;- const volume = laneBinding(VOLUME_TARGET, current);+ const volume = laneBinding(VOLUME_TARGET, current, writeOwn);const rateAttr = Number.parseFloat(element.dataAttributes?.["playback-rate"] ?? "");- const rate = laneBinding(RATE_TARGET, Number.isFinite(rateAttr) && rateAttr > 0 ? rateAttr : 1);+ const rate = laneBinding(+ RATE_TARGET,+ Number.isFinite(rateAttr) && rateAttr > 0 ? rateAttr : 1,+ writeRate,+ );return {volumeAutomated: volume.automated,automatedVolumeValue: volume.automatedValue,@@ -109,7 +131,7 @@ export function useVolumeAutomation(...rate,canApplyPreset: elDuration > 0,onApplyPreset: (id) => {- if (elDuration > 0) write(withLane(automation, speedPresetLane(id, elDuration)));+ if (elDuration > 0) writeRate((a) => withLane(a, speedPresetLane(id, elDuration)));},},};diff --git a/packages/studio/src/contexts/TimelineEditContext.tsx b/packages/studio/src/contexts/TimelineEditContext.tsxindex 3ec34a8889..3144ee661f 100644--- a/packages/studio/src/contexts/TimelineEditContext.tsx+++ b/packages/studio/src/contexts/TimelineEditContext.tsx@@ -45,6 +45,7 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {onRazorSplit: true,onRazorSplitAll: true,onFreezeFrame: true,+ onNotice: true,onDeleteKeyframe: true,onDeleteAllKeyframes: true,onMoveKeyframeToPlayhead: true,diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts b/packages/studio/src/hooks/timelineLinkEditPlan.test.tsindex 0513e12a41..5c95035193 100644--- a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts+++ b/packages/studio/src/hooks/timelineLinkEditPlan.test.ts@@ -78,3 +78,36 @@ describe("planLinkEdit", () => {expect(out).toContain('data-track-index="1"');});});++describe("planLinkEdit into sync", () => {+ const drifted =+ '<div data-composition-id="main" data-duration="10"><video id="talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2" data-duration="6"></video><audio id="talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2.5" data-duration="6" data-media-start="0"></audio></div>';+ const late = clip("talk-audio", "audio", { start: 2.5, playbackStart: 0 });++ it("moves one clip's start, leaving its partner and link alone", () => {+ const plan = planLinkEdit({ kind: "move-into-sync", element: late, start: 2 }, [video, late]);+ expect(plan?.label).toBe("Move into Sync");+ const html = plan?.transform(drifted) ?? "";+ expect(html).toContain('id="talk-audio" src="talk.mp4" data-sync-origin="lk-1" data-start="2"');+ expect(html).toContain('id="talk" src="talk.mp4" muted data-sync-origin="lk-1" data-start="2"');+ });++ it("slips one clip's media start in place", () => {+ const plan = planLinkEdit({ kind: "slip-into-sync", element: late, mediaStart: 0.5 }, [+ video,+ late,+ ]);+ expect(plan?.label).toBe("Slip into Sync");+ const html = plan?.transform(drifted) ?? "";+ expect(html).toContain('data-start="2.5" data-duration="6" data-media-start="0.5"');+ });++ it("slips the legacy playback-start attribute when that is what the clip uses", () => {+ const legacy = { ...late, playbackStartAttr: "playback-start" as const };+ const html =+ planLinkEdit({ kind: "slip-into-sync", element: legacy, mediaStart: 0.5 }, [])?.transform(+ '<audio id="talk-audio" data-playback-start="0"></audio>',+ ) ?? "";+ expect(html).toBe('<audio id="talk-audio" data-playback-start="0.5"></audio>');+ });+});diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.ts b/packages/studio/src/hooks/timelineLinkEditPlan.tsindex 65b0c25f0d..c3d6bce414 100644--- a/packages/studio/src/hooks/timelineLinkEditPlan.ts+++ b/packages/studio/src/hooks/timelineLinkEditPlan.ts@@ -2,6 +2,11 @@ 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 { toAuthoredStart } from "../player/store/timelineElement";+import { formatTimelineMediaOffset } from "../player/components/timelineEditing";+import { applyPatchByTarget } from "../utils/sourcePatcher";+import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";+import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";import {detachAudioInSource,linkInSource,@@ -42,6 +47,35 @@ export function clipsToUnlink(return [...removed.filter((el) => el.link), ...orphans.values()];}+type SyncEdit = Extract<TimelineLinkEdit, { kind: "move-into-sync" | "slip-into-sync" }>;++function planSyncEdit(edit: SyncEdit): LinkEditPlan | null {+ const target = buildPatchTarget(edit.element);+ if (!target) return null;+ if (edit.kind === "move-into-sync") {+ const value = formatTimelineMediaOffset(toAuthoredStart(edit.element, edit.start));+ return {+ label: "Move into Sync",+ anchor: edit.element,+ transform: (s) => {+ const moved = applyPatchByTarget(s, target, {+ type: "attribute",+ property: "start",+ value,+ });+ return setCompositionDurationToContent(moved, furthestClipEndFromSource(moved));+ },+ };+ }+ const property = edit.element.playbackStartAttr ?? "media-start";+ const value = formatTimelineMediaOffset(edit.mediaStart);+ return {+ label: "Slip into Sync",+ anchor: edit.element,+ transform: (s) => applyPatchByTarget(s, target, { type: "attribute", property, value }),+ };+}+export function planLinkEdit(edit: TimelineLinkEdit,elements: readonly TimelineElement[],@@ -72,6 +106,9 @@ export function planLinkEdit(null,};}+ case "move-into-sync":+ case "slip-into-sync":+ return planSyncEdit(edit);case "merge": {const videoTarget = buildPatchTarget(edit.video);const audioTarget = buildPatchTarget(edit.audio);diff --git a/packages/studio/src/hooks/useRazorSplit.ts b/packages/studio/src/hooks/useRazorSplit.tsindex 29b9113c01..1769211825 100644--- a/packages/studio/src/hooks/useRazorSplit.ts+++ b/packages/studio/src/hooks/useRazorSplit.ts@@ -5,6 +5,7 @@ import { getTimelineElementLabel } from "../utils/studioHelpers";import { trackStudioRazorSplit } from "../telemetry/events";import { canSplitElementAt, selectSplittableElements } from "../utils/timelineElementSplit";import { linkedMembersOf } from "../player/components/audioClipLink";+import { isLinkedSelectionOn } from "../utils/linkedClipPreferences";import { buildAtomicCutIntents, runAtomicCutTransaction } from "../utils/razorSplitTransaction";import type { RecordEditInput } from "./timelineEditingHelpers";import { useFreezeFrame } from "./useFreezeFrame";@@ -104,7 +105,11 @@ export function useRazorSplit({}if (!canSplitElementAt(element, splitTime)) return;try {- const members = linkedMembersOf(element, usePlayerStore.getState().elements);+ const members = linkedMembersOf(+ element,+ usePlayerStore.getState().elements,+ isLinkedSelectionOn(),+ );const result = await runCut(members.filter((member) => canSplitElementAt(member, splitTime)),splitTime,diff --git a/packages/studio/src/hooks/useRenderClipContent.test.ts b/packages/studio/src/hooks/useRenderClipContent.test.tsindex 0edcc303c0..9528406fb0 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 by data-link, and muted when hidden", () => {+ it("marks hidden audio muted and leaves the link to the chain badge", () => {usePlayerStore.setState({thumbnailMode: "hidden",elements: [@@ -220,9 +220,9 @@ describe("useRenderClipContent", () => {link: "lk-1",hidden: true,});- expect(isValidElement<{ linked: boolean; muted: boolean }>(linked)).toBe(true);- if (isValidElement<{ linked: boolean; muted: boolean }>(linked)) {- expect(linked.props.linked).toBe(true);+ expect(isValidElement<{ linked?: boolean; muted: boolean }>(linked)).toBe(true);+ if (isValidElement<{ linked?: boolean; muted: boolean }>(linked)) {+ expect(linked.props.linked).toBeUndefined();expect(linked.props.muted).toBe(true);}});@@ -250,6 +250,7 @@ describe("useRenderClipContent", () => {expect(isValidElement<{ waveformUrl: string }>(waveform) && waveform.props.waveformUrl).toBe("/api/projects/my-project/waveform/talk.mp4",);+ expect(isValidElement<{ labelInset?: number }>(waveform) && waveform.props.labelInset).toBe(0);});it("keeps a muted or silent video to thumbnails only", () => {diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.tsindex a929e6ac3a..87d4d7a657 100644--- a/packages/studio/src/hooks/useRenderClipContent.ts+++ b/packages/studio/src/hooks/useRenderClipContent.ts@@ -63,6 +63,7 @@ function renderAudioClip(labelColor: string,context: TimelineClipRenderContext,elements: readonly TimelineElement[],+ labelInset?: number,): ReactNode {const audioUrl = resolveMediaPreviewUrl(el.src ?? "", pid, window.location.origin);const srcRelative = resolvePreviewRelative(audioUrl, pid, window.location.origin);@@ -84,6 +85,7 @@ function renderAudioClip(projectId: pid,sessionEpoch,priority: context.priority,+ labelInset,...audioPillFlags(el, elements),});return createElement(@@ -103,10 +105,10 @@ function renderAudioClip(function withSoundStrip(el: TimelineElement,thumbnail: ReactNode,- waveform: () => ReactNode,+ waveform: (labelInset: number) => ReactNode,): ReactNode {if (el.tag !== "video" || !clipHasSound(el)) return thumbnail;- return createElement(AudibleVideoClipContent, { thumbnail, waveform: waveform() });+ return createElement(AudibleVideoClipContent, { thumbnail, waveform: waveform(0) });}export interface UseRenderClipContentOptions {@@ -141,7 +143,8 @@ export function useRenderClipContent({// Thumbnail generation disabled (perf) -> plain clip bars. Audio still shows// its waveform (cheap, not a frame thumbnail). Toggle: timeline toolbar.- const waveform = () => renderAudioClip(el, pid, sessionEpoch, style.label, context, elements);+ const waveform = (labelInset?: number) =>+ renderAudioClip(el, pid, sessionEpoch, style.label, context, elements, labelInset);if (effectiveMode === "hidden") {return rendersWaveform(el) ? waveform() : withSoundStrip(el, null, waveform);}diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsxindex 06808aec51..de7d0cd473 100644--- a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx+++ b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx@@ -4,6 +4,7 @@ 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";+import { useLinkedClipPreferences } from "../utils/linkedClipPreferences";(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;@@ -74,6 +75,20 @@ describe("useTimelineLinkEditing", () => {unmount();});+ it("with Linked Selection off, delete removes the clip alone and unlinks the survivor", async () => {+ const del = vi.fn().mockResolvedValue(undefined);+ const { api, unmount } = await renderLinkEditing(del);+ useLinkedClipPreferences.getState().setLinkedSelection(false);+ try {+ expect(withLinkPartners([video])).toEqual([video]);+ await act(async () => api.handleLinkedElementDelete(video));+ expect(del).toHaveBeenCalledWith([video], [audio]);+ } finally {+ useLinkedClipPreferences.getState().setLinkedSelection(true);+ }+ unmount();+ });+it("delete-only removes one member and unlinks the survivor", async () => {const del = vi.fn().mockResolvedValue(undefined);const { api, unmount } = await renderLinkEditing(del);diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.ts b/packages/studio/src/hooks/useTimelineLinkEditing.tsindex b8fadcd919..6423e3acee 100644--- a/packages/studio/src/hooks/useTimelineLinkEditing.ts+++ b/packages/studio/src/hooks/useTimelineLinkEditing.ts@@ -2,6 +2,7 @@ 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 { isLinkedSelectionOn } from "../utils/linkedClipPreferences";import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";import { readFileContent } from "./timelineEditingHelpers";@@ -33,6 +34,8 @@ export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {case "link":return [...edit.elements];case "detach":+ case "move-into-sync":+ case "slip-into-sync":return [edit.element];case "merge":return [edit.video, edit.audio];@@ -41,7 +44,7 @@ export function linkEditTargets(edit: TimelineLinkEdit): TimelineElement[] {export function withLinkPartners(selection: readonly TimelineElement[]): TimelineElement[] {const elements = usePlayerStore.getState().elements;- const keys = expandToLinkedMembers(selection.map(keyOf), elements);+ const keys = expandToLinkedMembers(selection.map(keyOf), elements, isLinkedSelectionOn());const known = new Set(selection.map(keyOf));return [...selection, ...elements.filter((el) => keys.has(keyOf(el)) && !known.has(keyOf(el)))];}@@ -115,13 +118,20 @@ export function useTimelineLinkEditing({);const handleLinkedElementsDelete = useCallback(- (selection: TimelineElement[]) => handleTimelineElementsDelete(withLinkPartners(selection)),+ (selection: TimelineElement[]) => {+ if (isLinkedSelectionOn()) return handleTimelineElementsDelete(withLinkPartners(selection));+ const removed = new Set(selection.map(keyOf));+ const orphans = clipsToUnlink(selection, usePlayerStore.getState().elements).filter(+ (el) => !removed.has(keyOf(el)),+ );+ return handleTimelineElementsDelete(selection, orphans);+ },[handleTimelineElementsDelete],);const handleLinkedElementDelete = useCallback(- (element: TimelineElement) => handleTimelineElementsDelete(withLinkPartners([element])),- [handleTimelineElementsDelete],+ (element: TimelineElement) => handleLinkedElementsDelete([element]),+ [handleLinkedElementsDelete],);const handleDeleteElementOnly = useCallback(diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.tsindex b79b3d6df6..b891063737 100644--- a/packages/studio/src/index.ts+++ b/packages/studio/src/index.ts@@ -31,6 +31,7 @@ export {liveTime,formatTime,} from "./player";+export { usePreviewIframeStore } from "./player/store/previewIframeStore";export type {PlayerHandle,PlayerHandleElement,diff --git a/packages/studio/src/player/components/AudioWaveform.test.tsx b/packages/studio/src/player/components/AudioWaveform.test.tsxindex f03c11df92..89f6a8e813 100644--- a/packages/studio/src/player/components/AudioWaveform.test.tsx+++ b/packages/studio/src/player/components/AudioWaveform.test.tsx@@ -96,7 +96,7 @@ describe("AudioWaveform", () => {act(() => root.unmount());});- it("greys the clip in place when muted and draws the parent tick when linked", () => {+ it("greys the clip in place when muted", () => {const host = document.createElement("div");host.className = "timeline-clip is-audio";document.body.append(host);@@ -112,15 +112,42 @@ describe("AudioWaveform", () => {sessionEpoch={1}priority="visible"muted- linked/>,);});expect(host.getAttribute("data-audio-muted")).toBe("true");- expect(host.querySelector(".timeline-audio-link")).not.toBeNull();act(() => root.unmount());expect(host.hasAttribute("data-audio-muted")).toBe(false);});++ it("fills a short sound strip when the label band is dropped", () => {+ const heights = [16, 0].map((labelInset) => {+ const host = document.createElement("div");+ document.body.append(host);+ const root = createRoot(host);+ act(() => {+ root.render(+ <AudioWaveform+ audioUrl="/media/talk.mp4"+ label=""+ labelColor="#fff"+ projectId="project-a"+ sessionEpoch={1}+ priority="visible"+ {...(labelInset === 16 ? {} : { labelInset })}+ />,+ );+ });+ const canvas = host.querySelector("canvas");+ const box = { top: canvas?.style.top, height: canvas?.style.height };+ act(() => root.unmount());+ return box;+ });+ expect(heights).toEqual([+ { top: "16px", height: "calc(100% - 16px)" },+ { top: "0px", height: "calc(100% - 0px)" },+ ]);+ });});diff --git a/packages/studio/src/player/components/AudioWaveform.tsx b/packages/studio/src/player/components/AudioWaveform.tsxindex 2d8eef38f9..0a2ce9dee4 100644--- a/packages/studio/src/player/components/AudioWaveform.tsx+++ b/packages/studio/src/player/components/AudioWaveform.tsx@@ -18,8 +18,7 @@ export interface AudioWaveformProps {priority: ThumbnailPriority;/** `data-hidden` or a muted audio group. Greys the pill; the clip stays. */muted?: boolean;- /** Same media file as a video clip. Draws the 1px parent tick. */- linked?: boolean;+ labelInset?: number;}const BAR_STEP = 3;@@ -167,7 +166,7 @@ export const AudioWaveform = memo(function AudioWaveform({sessionEpoch,priority,muted = false,- linked = false,+ labelInset = 16,}: AudioWaveformProps) {const rootRef = useRef<HTMLDivElement | null>(null);const canvasRef = useRef<HTMLCanvasElement | null>(null);@@ -236,17 +235,17 @@ export const AudioWaveform = memo(function AudioWaveform({return (<div ref={rootRef} className="absolute inset-0">- {linked ? <span className="timeline-audio-link" aria-hidden="true" /> : null}<div className="absolute inset-0 overflow-hidden" style={{ zIndex: 10 }}><canvasref={setCanvasRef}className="absolute inset-x-0 bottom-0 w-full"- style={{ top: 16, height: "calc(100% - 16px)" }}+ style={{ top: labelInset, height: `calc(100% - ${labelInset}px)` }}/>{snapshot.status === "loading" && (<div- className="absolute inset-x-0 bottom-0 top-4 animate-pulse"+ className="absolute inset-x-0 bottom-0 animate-pulse"style={{+ top: labelInset,background: "var(--timeline-thumbnail-shimmer)",}}/>@@ -256,7 +255,7 @@ export const AudioWaveform = memo(function AudioWaveform({{snapshot.status === "error" && (<divclassName="absolute inset-x-0 flex items-center justify-center gap-1.5"- style={{ top: 16, bottom: 0 }}+ style={{ top: labelInset, bottom: 0 }}><divclassName="absolute inset-x-0"diff --git a/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsxnew file mode 100644index 0000000000..dd3f660b49--- /dev/null+++ b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx@@ -0,0 +1,102 @@+// @vitest-environment happy-dom+import { act } from "react";+import { describe, expect, it, vi } from "vitest";+import { createHappyDomRootHarness } from "./testRootHarness";+import { ClipContextMenu } from "./ClipContextMenu";+import { usePlayerStore, type TimelineElement } from "../store/playerStore";+import { TimelineEditProvider } from "../../contexts/TimelineEditContext";++const iframe = document.createElement("iframe");+vi.mock("../../contexts/StudioContext", () => ({+ useStudioShellContextOptional: () => ({+ projectId: "p1",+ showToast: vi.fn(),+ previewIframeRef: { current: iframe },+ }),+}));++const harness = createHappyDomRootHarness();++const talk: TimelineElement = {+ id: "talk",+ domId: "talk",+ tag: "video",+ src: "talk.mp4",+ start: 0,+ duration: 6,+ track: 0,+ hasAudio: true,+ link: "lk-1",+};+const talkAudio: TimelineElement = {+ ...talk,+ id: "talk-a",+ domId: "talk-a",+ tag: "audio",+ track: 1,+};++function renderMenu(element: TimelineElement) {+ usePlayerStore.getState().setElements([talk, talkAudio]);+ document.body.appendChild(iframe);+ const node = iframe.contentDocument?.createElement("video");+ if (node) {+ node.id = "talk";+ node.setAttribute("data-has-audio", "true");+ iframe.contentDocument?.body.appendChild(node);+ }+ const host = document.createElement("div");+ document.body.appendChild(host);+ const noop = vi.fn();+ act(() =>+ harness.mount(host).render(+ <TimelineEditProvider+ value={{+ onSetElementAttributeQuiet: vi.fn(async () => undefined),+ onFreezeFrame: noop,+ onLinkEdit: noop,+ onDeleteElementOnly: noop,+ }}+ >+ <ClipContextMenu+ x={10}+ y={10}+ element={element}+ currentTime={2}+ onClose={noop}+ onSplit={noop}+ onDelete={noop}+ />+ </TimelineEditProvider>,+ ),+ );+}++function menuLabels(): string[] {+ return Array.from(document.querySelectorAll('[role="menuitem"], [role="menuitemcheckbox"]')).map(+ (item) => item.querySelector("span")?.textContent ?? "",+ );+}++describe("ClipContextMenu order", () => {+ it("groups time, sound, picture, then delete for a linked video with sound", () => {+ renderMenu(talk);+ const expected = [+ "Split at 2.00s",+ "Freeze frame",+ "Normalize loudness",+ "Voice",+ "Detach audio",+ "Unlink from audio",+ "Look",+ "Crop",+ "Delete",+ "Delete this clip only",+ ];+ expect(menuLabels().filter((label) => expected.includes(label))).toEqual(expected);+ const groups = Array.from(document.querySelectorAll('[role="group"]')).map((group) =>+ group.getAttribute("aria-label"),+ );+ expect(groups).toEqual(["Time", "Sound", "Picture", "Clipboard", "Delete"]);+ });+});diff --git a/packages/studio/src/player/components/ClipContextMenu.test.tsx b/packages/studio/src/player/components/ClipContextMenu.test.tsxindex b72291631c..4d28e77835 100644--- a/packages/studio/src/player/components/ClipContextMenu.test.tsx+++ b/packages/studio/src/player/components/ClipContextMenu.test.tsx@@ -60,9 +60,14 @@ describe("ClipContextMenu host items", () => {unmount();});- it("counts host rows and their divider when keeping the menu inside the window", () => {+ it("keeps the menu, host rows included, inside the window by its measured height", () => {const innerHeight = Object.getOwnPropertyDescriptor(window, "innerHeight");Object.defineProperty(window, "innerHeight", { configurable: true, value: 600 });+ const offsetHeight = vi+ .spyOn(HTMLElement.prototype, "offsetHeight", "get")+ .mockImplementation(function (this: HTMLElement) {+ return this.getAttribute("role") === "menu" ? 150 : 0;+ });try {const host = document.createElement("div");document.body.appendChild(host);@@ -86,10 +91,11 @@ describe("ClipContextMenu host items", () => {/>,),);- // Four 30 px rows, two 9 px dividers and 8 px of padding end 96 px below the window.- expect(document.body.querySelector<HTMLElement>("[role=menu]")!.style.top).toBe("446px");+ // 150 px measured from y 550 ends 100 px below the window, kept 8 px off its edge.+ expect(document.body.querySelector<HTMLElement>("[role=menu]")!.style.top).toBe("442px");act(() => root.unmount());} finally {+ offsetHeight.mockRestore();if (innerHeight) Object.defineProperty(window, "innerHeight", innerHeight);}});@@ -106,7 +112,7 @@ describe("ClipContextMenu host items", () => {it("shows only Studio's items when the host adds none", () => {const { items, unmount } = renderMenu([]);expect(items().map((item) => item.textContent)).toEqual(["Copy⌘C", "Delete⌫"]);- expect(document.body.querySelectorAll(".border-t")).toHaveLength(1);+ expect(document.body.querySelector("[role=group][aria-label=Host]")).toBeNull();unmount();});});diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsxindex 7aef774d9c..438b09def5 100644--- a/packages/studio/src/player/components/ClipContextMenu.tsx+++ b/packages/studio/src/player/components/ClipContextMenu.tsx@@ -1,4 +1,4 @@-import { memo } from "react";+import { memo, useLayoutEffect, useState, type RefObject } from "react";import { createPortal } from "react-dom";import { usePlayerStore, type TimelineElement } from "../store/playerStore";import { canSplitElement } from "../../utils/timelineElementSplit";@@ -9,6 +9,24 @@ import { ClipMenuToolItems } from "./clipMenuToolItems";import { ClipMenuAudioItems } from "./clipMenuAudioItems";import { ClipMenuLinkItems } from "./clipMenuLinkItems";+const MENU_MARGIN = 8;+// Empty groups collapse; every non-empty group before the always-present Delete group ends in a divider.+const GROUP_CLASS = "empty:hidden mb-1 pb-1 border-b border-neutral-700/60";++function useMeasuredHeight(ref: RefObject<HTMLDivElement | null>, anchorKey: string): number {+ const [height, setHeight] = useState(0);+ useLayoutEffect(() => {+ const node = ref.current;+ if (!node) return;+ setHeight(node.offsetHeight);+ if (typeof ResizeObserver === "undefined") return;+ const observer = new ResizeObserver(() => setHeight(node.offsetHeight));+ observer.observe(node);+ return () => observer.disconnect();+ }, [ref, anchorKey]);+ return height;+}+interface ClipContextMenuProps {x: number;y: number;@@ -63,7 +81,6 @@ function HostItems({)}</button>))}- <div className="my-1 border-t border-neutral-700/60" /></>);}@@ -106,16 +123,11 @@ export const ClipContextMenu = memo(function ClipContextMenu({? `Split at ${currentTime.toFixed(2)}s`: "Split (move playhead inside clip)";- const clipboardItemCount = [onCopy, onPaste, onDuplicate].filter(Boolean).length;- const hostRows = hostItems.length;- const rowCount = hostRows + (splitLabel ? 1 : 0) + clipboardItemCount + 1; // + Delete, always present- const dividerCount =- (hostRows > 0 ? 1 : 0) + (splitLabel ? 1 : 0) + (clipboardItemCount > 0 ? 1 : 0);const menuWidth = 200;- const menuHeight = rowCount * 30 + dividerCount * 9 + 8;- const overflowY = y + menuHeight - window.innerHeight;const adjustedX = x + menuWidth > window.innerWidth ? x - menuWidth : x;- const adjustedY = overflowY > 0 ? y - overflowY - 8 : y;+ const menuHeight = useMeasuredHeight(menuRef, `${x},${y},${element.key ?? element.id}`);+ const overflowY = y + menuHeight - window.innerHeight;+ const adjustedY = overflowY > 0 ? Math.max(MENU_MARGIN, y - overflowY - MENU_MARGIN) : y;return createPortal(<div@@ -125,9 +137,13 @@ export const ClipContextMenu = memo(function ClipContextMenu({className="fixed z-200 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"style={{ left: adjustedX, top: adjustedY }}>- {hostRows > 0 && <HostItems items={hostItems} onClose={onClose} />}- {splitLabel && (- <>+ {hostItems.length > 0 && (+ <div role="group" aria-label="Host" className={GROUP_CLASS}>+ <HostItems items={hostItems} onClose={onClose} />+ </div>+ )}+ <div role="group" aria-label="Time" className={GROUP_CLASS}>+ {splitLabel && (<buttontype="button"role="menuitem"@@ -147,93 +163,100 @@ export const ClipContextMenu = memo(function ClipContextMenu({<span>{splitLabel}</span><span className="text-neutral-500 text-[10px] ml-3">S</span></button>+ )}+ {splitLabel && (<ClipMenuToolItemsgroup="time"element={element}currentTime={currentTime}onClose={onClose}/>- <div className="my-1 border-t border-neutral-700/60" />- </>- )}+ )}+ </div>- <ClipMenuAudioItems element={element} onClose={onClose} />- <ClipMenuLinkItems element={element} onClose={onClose} />+ <div role="group" aria-label="Sound" className={GROUP_CLASS}>+ <ClipMenuAudioItems part="normalize" element={element} onClose={onClose} />+ <ClipMenuToolItems+ group="sound"+ element={element}+ currentTime={currentTime}+ onClose={onClose}+ />+ <ClipMenuLinkItems part="link" element={element} onClose={onClose} />+ <ClipMenuAudioItems part="duck" element={element} onClose={onClose} />+ </div>- {(onCopy || onPaste || onDuplicate) && (- <>- {onCopy && (- <button- type="button"- role="menuitem"- className={itemClass(true)}- onClick={() => {- onCopy();- onClose();- }}- >- <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>- <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>- </button>- )}- {onPaste && (- <button- type="button"- role="menuitem"- className={itemClass(!!canPaste)}- disabled={!canPaste}- onClick={() => {- if (!canPaste) return;- void onPaste();- onClose();- }}- >- <span>Paste</span>- <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>- </button>- )}- {onDuplicate && (- <button- type="button"- role="menuitem"- className={itemClass(true)}- onClick={() => {- void onDuplicate();- onClose();- }}- >- <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>- <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>- </button>- )}- <div className="my-1 border-t border-neutral-700/60" />- </>- )}+ <div role="group" aria-label="Picture" className={GROUP_CLASS}>+ <ClipMenuToolItems+ group="picture"+ element={element}+ currentTime={currentTime}+ onClose={onClose}+ />+ </div>++ <div role="group" aria-label="Clipboard" className={GROUP_CLASS}>+ {onCopy && (+ <button+ type="button"+ role="menuitem"+ className={itemClass(true)}+ onClick={() => {+ onCopy();+ onClose();+ }}+ >+ <span>{selectionSize > 1 ? `Copy ${selectionSize} clips` : "Copy"}</span>+ <span className="text-neutral-500 text-[10px] ml-3">⌘C</span>+ </button>+ )}+ {onPaste && (+ <button+ type="button"+ role="menuitem"+ className={itemClass(!!canPaste)}+ disabled={!canPaste}+ onClick={() => {+ if (!canPaste) return;+ void onPaste();+ onClose();+ }}+ >+ <span>Paste</span>+ <span className="text-neutral-500 text-[10px] ml-3">⌘V</span>+ </button>+ )}+ {onDuplicate && (+ <button+ type="button"+ role="menuitem"+ className={itemClass(true)}+ onClick={() => {+ void onDuplicate();+ onClose();+ }}+ >+ <span>{selectionSize > 1 ? `Duplicate ${selectionSize} clips` : "Duplicate"}</span>+ <span className="text-neutral-500 text-[10px] ml-3">⌘D</span>+ </button>+ )}+ </div>- <ClipMenuToolItems- group="sound"- element={element}- currentTime={currentTime}- onClose={onClose}- />- <ClipMenuToolItems- group="picture"- element={element}- currentTime={currentTime}- onClose={onClose}- />- <button- type="button"- role="menuitem"- className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-danger-ink hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden cursor-pointer text-left"- onClick={() => {- onDelete(element);- onClose();- }}- >- <span>Delete</span>- <span className="text-neutral-500 text-[10px] ml-3">⌫</span>- </button>+ <div role="group" aria-label="Delete">+ <button+ type="button"+ role="menuitem"+ className="w-full flex items-center justify-between px-3 py-1.5 text-xs text-danger-ink hover:bg-neutral-800 focus-visible:bg-neutral-800 outline-hidden cursor-pointer text-left"+ onClick={() => {+ onDelete(element);+ onClose();+ }}+ >+ <span>Delete</span>+ <span className="text-neutral-500 text-[10px] ml-3">⌫</span>+ </button>+ <ClipMenuLinkItems part="delete" element={element} onClose={onClose} />+ </div></div>,document.body,);diff --git a/packages/studio/src/player/components/OutOfSyncBadge.test.tsx b/packages/studio/src/player/components/OutOfSyncBadge.test.tsxnew file mode 100644index 0000000000..40021f35e8--- /dev/null+++ b/packages/studio/src/player/components/OutOfSyncBadge.test.tsx@@ -0,0 +1,91 @@+// @vitest-environment happy-dom+import React, { act } from "react";+import { afterEach, describe, expect, it, vi } from "vitest";+import { TimelineEditProvider } from "../../contexts/TimelineEditContext";+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";+import { usePlayerStore, type TimelineElement } from "../store/playerStore";+import { OutOfSyncBadge } from "./OutOfSyncBadge";+import { createHappyDomRootHarness } from "./testRootHarness";++(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;++const harness = createHappyDomRootHarness();+const clip = (id: string, tag: string, start: number): TimelineElement => ({+ id,+ domId: id,+ tag,+ start,+ duration: 4,+ track: 0,+ playbackStart: 0,+ syncOrigin: "lk-1",+});+const video = clip("talk", "video", 1);+const lateAudio = clip("talk-audio", "audio", 1 + 51 / 30);++afterEach(() =>+ useLinkedClipPreferences.setState({ syncIndicatorsVisible: true, compositionFps: 30 }),+);++function render(el: TimelineElement, onLinkEdit = vi.fn()) {+ usePlayerStore.getState().setElements([video, lateAudio]);+ const host = document.body.appendChild(document.createElement("div"));+ act(() =>+ harness.mount(host).render(+ <TimelineEditProvider value={{ onLinkEdit }}>+ <OutOfSyncBadge el={el} />+ </TimelineEditProvider>,+ ),+ );+ const badge = () => document.querySelector('[data-testid="out-of-sync-badge"]');+ return { badge, onLinkEdit };+}++describe("OutOfSyncBadge", () => {+ it("shows the signed offset on both halves", () => {+ useLinkedClipPreferences.setState({ compositionFps: 30 });+ expect(render(lateAudio).badge()?.textContent).toBe("+1:21");+ document.body.innerHTML = "";+ expect(render(video).badge()?.textContent).toBe("-1:21");+ });++ it("hides when the preference is off", () => {+ useLinkedClipPreferences.setState({ syncIndicatorsVisible: false });+ expect(render(lateAudio).badge()).toBeNull();+ });++ it("opens Move / Slip into Sync from a click anywhere on the badge", () => {+ const { badge, onLinkEdit } = render(lateAudio);+ act(() => badge()?.dispatchEvent(new MouseEvent("click", { bubbles: true })));+ const items = Array.from(document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]'));+ expect(items.map((item) => item.textContent)).toEqual(["Move into Sync", "Slip into Sync"]);+ act(() => items[0]?.click());+ expect(onLinkEdit).toHaveBeenCalledWith(+ expect.objectContaining({ kind: "move-into-sync", element: lateAudio, start: 1 }),+ );+ });++ it("slips from a right-click, and the click never reaches the clip", () => {+ const clipClick = vi.fn();+ document.body.addEventListener("contextmenu", clipClick);+ const { badge, onLinkEdit } = render(lateAudio);+ act(() => badge()?.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true })));+ expect(clipClick).not.toHaveBeenCalled();+ const slip = document.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')[1];+ act(() => slip?.click());+ const edit = onLinkEdit.mock.calls[0]?.[0];+ expect(edit.kind).toBe("slip-into-sync");+ expect(edit.mediaStart).toBeCloseTo(51 / 30);+ document.body.removeEventListener("contextmenu", clipClick);+ });++ it("flips the menu above the pointer near the bottom edge", () => {+ const { badge } = render(lateAudio);+ const y = window.innerHeight - 10;+ act(() => badge()?.dispatchEvent(new MouseEvent("click", { bubbles: true, clientY: y })));+ const menu = document.querySelector<HTMLElement>('[role="menu"]');+ const top = Number.parseFloat(menu?.style.top ?? "");+ expect(top).toBeLessThan(y);+ expect(top).toBeGreaterThanOrEqual(0);+ });+});diff --git a/packages/studio/src/player/components/OutOfSyncBadge.tsx b/packages/studio/src/player/components/OutOfSyncBadge.tsxnew file mode 100644index 0000000000..49fc8c4339--- /dev/null+++ b/packages/studio/src/player/components/OutOfSyncBadge.tsx@@ -0,0 +1,119 @@+import { memo, useCallback, useState, type SyntheticEvent } from "react";+import { createPortal } from "react-dom";+import { formatSyncOffset } from "@hyperframes/core/media-link";+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";+import { usePlayerStore, type TimelineElement } from "../store/playerStore";+import { clipSyncState, type ClipSyncState } from "./clipSync";+import { useMenuKeyboardNav } from "./menuKeyboardNav";++const stop = (e: SyntheticEvent) => e.stopPropagation();++const MENU_ROW =+ "block w-full px-3 py-1.5 text-left text-xs text-neutral-300 outline-hidden hover:bg-neutral-800 focus-visible:bg-neutral-800 disabled:opacity-40";++function SyncMenu({+ x,+ y,+ el,+ sync,+ onClose,+}: {+ x: number;+ y: number;+ el: TimelineElement;+ sync: ClipSyncState<TimelineElement>;+ onClose: () => void;+}) {+ const menuRef = useContextMenuDismiss(onClose);+ useMenuKeyboardNav(menuRef);+ const { onLinkEdit } = useTimelineEditContextOptional();+ const { moveStart, slipMediaStart } = sync;+ const menuWidth = 170;+ const menuHeight = 66;+ const left = x + menuWidth > window.innerWidth ? x - menuWidth : x;+ const top = y + menuHeight > window.innerHeight ? Math.max(0, y - menuHeight) : y;+ return createPortal(+ <div+ ref={menuRef}+ role="menu"+ aria-label="Out of sync"+ className="fixed z-200 min-w-[170px] rounded-sm border border-neutral-700 bg-neutral-900 py-1 shadow-lg"+ style={{ left, top }}+ >+ <button+ type="button"+ role="menuitem"+ className={MENU_ROW}+ disabled={!onLinkEdit || moveStart === null}+ title={moveStart === null ? "Would move the clip before 0:00" : undefined}+ onClick={() => {+ if (moveStart !== null)+ void onLinkEdit?.({ kind: "move-into-sync", element: el, start: moveStart });+ onClose();+ }}+ >+ Move into Sync+ </button>+ <button+ type="button"+ role="menuitem"+ className={MENU_ROW}+ disabled={!onLinkEdit || slipMediaStart === null}+ title={slipMediaStart === null ? "Would slip before the start of the file" : undefined}+ onClick={() => {+ if (slipMediaStart !== null) {+ void onLinkEdit?.({ kind: "slip-into-sync", element: el, mediaStart: slipMediaStart });+ }+ onClose();+ }}+ >+ Slip into Sync+ </button>+ </div>,+ document.body,+ );+}++/**+ * Premiere's red out-of-sync number, at the start of each half of a source pair+ * that drifted. The whole badge opens Move / Slip into Sync (Premiere's own hit+ * target is a sliver at the badge edge, a known complaint).+ */+export const OutOfSyncBadge = memo(function OutOfSyncBadge({ el }: { el: TimelineElement }) {+ const visible = useLinkedClipPreferences((s) => s.syncIndicatorsVisible);+ const fps = useLinkedClipPreferences((s) => s.compositionFps);+ const elements = usePlayerStore((s) => s.elements);+ const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);+ const closeMenu = useCallback(() => setMenuAt(null), []);+ const sync = visible ? clipSyncState(el, elements, fps) : null;+ if (!sync) return null;+ const label = formatSyncOffset(sync.frames, fps);+ const partnerName = sync.partner.label || sync.partner.id;+ const open = (e: React.MouseEvent) => {+ e.preventDefault();+ e.stopPropagation();+ setMenuAt({ x: e.clientX, y: e.clientY });+ };+ return (+ <>+ <span+ role="button"+ tabIndex={-1}+ aria-haspopup="menu"+ aria-label={`Out of sync with ${partnerName} by ${label} frames`}+ title={`Out of sync with ${partnerName} by ${label} — click for Move or Slip into Sync`}+ data-testid="out-of-sync-badge"+ className="absolute bottom-0.5 left-1 z-[7] cursor-pointer rounded-[3px] bg-red-600 px-1 font-mono text-[9px] leading-[14px] text-white tabular-nums"+ onPointerDown={stop}+ onDoubleClick={stop}+ onClick={open}+ onContextMenu={open}+ >+ {label}+ </span>+ {menuAt && <SyncMenu x={menuAt.x} y={menuAt.y} el={el} sync={sync} onClose={closeMenu} />}+ </>+ );+});diff --git a/packages/studio/src/player/components/TimelineClip.test.tsx b/packages/studio/src/player/components/TimelineClip.test.tsxindex 0e2de43a3c..3c4786be67 100644--- a/packages/studio/src/player/components/TimelineClip.test.tsx+++ b/packages/studio/src/player/components/TimelineClip.test.tsx@@ -105,6 +105,23 @@ describe("TimelineClip", () => {expect(seen).toEqual([{ fadeIn: 1, fadeOut: 0.5, duration: 4 }, null]);});+ it("gives both halves of a link group the same label colour, and unlinked clips none", () => {+ const colorOf = (element: TimelineElement) => {+ const { host, root } = renderClip({ element });+ const clip = host.querySelector<HTMLElement>(".timeline-clip");+ const color = clip?.getAttribute("data-link-color") ?? null;+ expect(clip?.style.getPropertyValue("--clip-link-color") || null).toBe(color);+ act(() => root.unmount());+ return color;+ };+ const base = { start: 0, duration: 2, track: 0 };+ const video = colorOf({ id: "v", tag: "video", link: "lk-3", ...base });+ expect(video).not.toBeNull();+ expect(colorOf({ id: "a", tag: "audio", link: "lk-3", ...base })).toBe(video);+ expect(colorOf({ id: "b", tag: "audio", link: "lk-4", ...base })).not.toBe(video);+ expect(colorOf({ id: "c", tag: "audio", ...base })).toBeNull();+ });+it("renders the clip label above custom content without showing default timecode", () => {const { host, root } = renderClip({element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 1, track: 0 },diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsxindex 5030bfdce2..2b63755c05 100644--- a/packages/studio/src/player/components/TimelineClip.tsx+++ b/packages/studio/src/player/components/TimelineClip.tsx@@ -12,6 +12,8 @@ import { timelineClipFocusId } from "./timelineNavigationIdentity";import { ClipFadesContext, TimelineClipFades, useClipFadeDraft } from "./TimelineClipFades";import { rendersWaveform } from "./AudioWaveform";import { ClipBadges } from "./ClipBadges";+import { linkLabelColor } from "./linkLabelColor";+import { OutOfSyncBadge } from "./OutOfSyncBadge";interface TimelineClipProps {el: TimelineElement;@@ -83,6 +85,8 @@ export const TimelineClip = memo(function TimelineClip({"--clip-border-active": theme.clipBorderActive,"--clip-handle": theme.handleColor,} as CSSProperties;+ const linkColor = linkLabelColor(el.link);+ if (linkColor) Object.assign(themeVariables, { "--clip-link-color": linkColor });const isAudioClip = isAudioTimelineElement(el);const hasFades = (isAudioClip || Boolean(el.hasAudio)) && !isGestureActor;const fade = useClipFadeDraft(el);@@ -124,6 +128,7 @@ export const TimelineClip = memo(function TimelineClip({data-clip-start={el.start}data-clip-end={el.start + el.duration}data-clip-hidden={el.hidden ? "true" : undefined}+ data-link-color={linkColor ?? undefined}data-ladder={ladder}data-active={isActive ? "" : undefined}aria-hidden={isGestureActor ? "true" : undefined}@@ -206,6 +211,7 @@ export const TimelineClip = memo(function TimelineClip({)}{showLabel && <span className="timeline-clip__label">{displayLabel}</span>}{showLabel && !isGestureActor && <ClipBadges el={el} />}+ {!isGestureActor && el.syncOrigin && <OutOfSyncBadge el={el} />}{showDefaultText && (<span className="timeline-clip__timecode">{startLabel}-{endLabel}sdiff --git a/packages/studio/src/player/components/audioClipLink.test.ts b/packages/studio/src/player/components/audioClipLink.test.tsindex 42f5743dde..c4e81bb248 100644--- a/packages/studio/src/player/components/audioClipLink.test.ts+++ b/packages/studio/src/player/components/audioClipLink.test.ts@@ -17,11 +17,6 @@ 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);@@ -163,6 +158,12 @@ describe("linkedGestureKeys", () => {);});+ it("Linked Selection off edits the grabbed clip alone without Alt", () => {+ expect(linkedGestureKeys(new Set(["talk"]), video, elements, false, false)).toEqual(+ new Set(["talk"]),+ );+ });+it("Alt edits the grabbed clip alone", () => {expect(linkedGestureKeys(new Set(["talk", "talk-audio"]), video, elements, true)).toEqual(new Set(["talk"]),@@ -202,3 +203,29 @@ describe("selectClipWithLinks", () => {expect(usePlayerStore.getState().selectedElementId).toBe("talk");});});++describe("Linked Selection off", () => {+ 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" },+ ];++ it("expands and lists nothing past the clip itself", () => {+ expect(expandToLinkedMembers(["talk"], linkedPair, false)).toEqual(new Set(["talk"]));+ expect(linkedMembersOf(linkedPair[0], linkedPair, false)).toEqual([linkedPair[0]]);+ });++ it("a click selects only the clicked clip", async () => {+ const { usePlayerStore } = await import("../store/playerStore");+ const { selectClipWithLinks } = await import("./timelineLinkSelection");+ const { useLinkedClipPreferences } = await import("../../utils/linkedClipPreferences");+ usePlayerStore.getState().setElements(linkedPair);+ useLinkedClipPreferences.getState().setLinkedSelection(false);+ try {+ selectClipWithLinks("talk", false, usePlayerStore.getState().setSelectedElementId);+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk"]));+ } finally {+ useLinkedClipPreferences.getState().setLinkedSelection(true);+ }+ });+});diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.tsindex ee6cdc338f..355659d0b6 100644--- a/packages/studio/src/player/components/audioClipLink.ts+++ b/packages/studio/src/player/components/audioClipLink.ts@@ -34,17 +34,18 @@ export function sharesLinkGroup(}export function audioPillFlags(- audio: Pick<TimelineElement, "hidden" | "audioGroupHidden" | "link">,+ audio: Pick<TimelineElement, "hidden" | "audioGroupHidden">,_elements?: readonly unknown[],-): { muted: boolean; linked: boolean } {- return {- muted: audio.hidden === true || audio.audioGroupHidden === true,- linked: isLinked(audio),- };+): { muted: boolean } {+ return { muted: audio.hidden === true || audio.audioGroupHidden === true };}-export function linkedMembersOf<T extends LinkedElement>(element: T, elements: readonly T[]): T[] {- if (!isLinked(element)) return [element];+export function linkedMembersOf<T extends LinkedElement>(+ element: T,+ elements: readonly T[],+ linked = true,+): T[] {+ if (!linked || !isLinked(element)) return [element];const members = elements.filter((candidate) => sharesLinkGroup(candidate, element));return members.some((member) => keyOf(member) === keyOf(element))? members@@ -54,8 +55,10 @@ export function linkedMembersOf<T extends LinkedElement>(element: T, elements: rexport function expandToLinkedMembers(keys: Iterable<string>,elements: readonly LinkedElement[],+ linked = true,): Set<string> {const expanded = new Set(keys);+ if (!linked) return expanded;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));@@ -68,9 +71,10 @@ export function linkedGestureKeys(grabbed: LinkedElement,elements: readonly LinkedElement[],altKey: boolean,+ linked = true,): Set<string> {const grabbedKey = keyOf(grabbed);if (altKey) return new Set([grabbedKey]);const base = selected.has(grabbedKey) ? selected : [grabbedKey];- return expandToLinkedMembers(base, elements);+ return expandToLinkedMembers(base, elements, linked);}diff --git a/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsxnew file mode 100644index 0000000000..a91d2e4768--- /dev/null+++ b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx@@ -0,0 +1,78 @@+// @vitest-environment happy-dom+import { act } from "react";+import { afterEach, describe, expect, it, vi } from "vitest";+import { createHappyDomRootHarness } from "./testRootHarness";+import { ClipMenuAudioItems } from "./clipMenuAudioItems";+import { usePlayerStore } from "../store/playerStore";+import { usePreviewIframeStore } from "../store/previewIframeStore";+import type { TimelineElement } from "../store/timelineElement";++const onNotice = vi.fn();+const setQuiet = vi.fn(async () => {});++vi.mock("../../contexts/StudioContext", () => ({+ useStudioShellContextOptional: () => null,+}));+vi.mock("../../contexts/TimelineEditContext", () => ({+ useTimelineEditContextOptional: () => ({ onSetElementAttributeQuiet: setQuiet, onNotice }),+}));++const harness = createHappyDomRootHarness();+const tour: TimelineElement = {+ id: "tour",+ tag: "video",+ start: 0,+ duration: 4,+ track: 0,+ hasAudio: true,+ src: "tour.mp4",+};++function mountPreview(): void {+ const iframe = document.createElement("iframe");+ document.body.appendChild(iframe);+ const doc = iframe.contentDocument;+ if (!doc) throw new Error("iframe has no document");+ doc.body.innerHTML =+ '<video id="tour" src="tour.mp4" data-has-audio="true" data-start="0" data-duration="4"></video><audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>';+ usePreviewIframeStore.getState().setIframe(iframe);+}++function render(part: "normalize" | "duck") {+ const host = document.createElement("div");+ document.body.appendChild(host);+ act(() =>+ harness+ .mount(host)+ .render(<ClipMenuAudioItems part={part} element={tour} onClose={() => {}} />),+ );+ return host;+}++afterEach(() => {+ usePreviewIframeStore.getState().setIframe(null);+ vi.unstubAllGlobals();+});++describe("ClipMenuAudioItems in a host without Studio's shell", () => {+ it("offers Normalize and Duck from the timeline session and the live preview", () => {+ usePlayerStore.getState().beginTimelineSession("p1");+ mountPreview();+ expect(render("normalize").textContent).toContain("Normalize loudness");+ expect(render("duck").textContent).toContain("Duck under voice");+ });++ it("normalizes through the session's project and reports through onNotice", async () => {+ usePlayerStore.getState().beginTimelineSession("p1");+ mountPreview();+ const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };+ const fetchSpy = vi.fn(async (_url: string) => Response.json({ plan }));+ vi.stubGlobal("fetch", fetchSpy);+ const button = render("normalize").querySelector("button");+ await act(async () => button?.click());+ await vi.waitFor(() => expect(onNotice).toHaveBeenCalled());+ expect(String(fetchSpy.mock.calls[0]?.[0])).toContain("/api/projects/p1/loudness/normalize");+ expect(setQuiet).toHaveBeenCalledWith(tour, "data-volume", "2", "Normalize loudness");+ expect(onNotice).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");+ });+});diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsxindex 7b1a35820e..a73119a647 100644--- a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx@@ -7,7 +7,12 @@ import type { TimelineElement } from "../store/timelineElement";const showToast = vi.fn();const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});-const iframe = document.createElement("iframe");+let previewDoc: Document | null = null;+const iframe = {+ get contentDocument() {+ return previewDoc;+ },+};vi.mock("../../contexts/StudioContext", () => ({useStudioShellContextOptional: () => ({@@ -22,11 +27,13 @@ vi.mock("../../contexts/TimelineEditContext", () => ({const harness = createHappyDomRootHarness();-function render(element: TimelineElement) {+function render(element: TimelineElement, part: "normalize" | "duck" = "normalize") {const host = document.createElement("div");document.body.appendChild(host);act(() =>- harness.mount(host).render(<ClipMenuAudioItems element={element} onClose={() => {}} />),+ harness+ .mount(host)+ .render(<ClipMenuAudioItems part={part} element={element} onClose={() => {}} />),);return host;}@@ -50,6 +57,44 @@ describe("ClipMenuAudioItems", () => {expect(host.textContent).toBe("");});+ describe("Duck under voice", () => {+ const duckLabel = (host: HTMLElement) =>+ [...host.querySelectorAll("button")].find((b) => b.textContent?.includes("Duck under voice"));+ const compose = (body: string) => {+ previewDoc = document.implementation.createHTMLDocument("c");+ previewDoc.body.innerHTML = body;+ };+ const music: TimelineElement = { ...base, id: "music", tag: "audio", src: "music.mp3" };++ it("is hidden on a lone video with sound", () => {+ compose(+ `<video id="a-roll" src="a.mp4" data-start="0" data-duration="4" data-has-audio="true"></video>`,+ );+ const host = render(+ { ...base, id: "a-roll", tag: "video", hasAudio: true, src: "a.mp4" },+ "duck",+ );+ expect(duckLabel(host)).toBeUndefined();+ });++ it("shows for a music bed with an overlapping voice", () => {+ compose(`<audio id="music" src="music.mp3" data-start="0" data-duration="4"></audio>+ <audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>`);+ const host = render(music, "duck");+ expect(duckLabel(host)?.getAttribute("aria-checked")).toBe("false");+ });++ it("stays available, checked, once ducked even with the voice gone", () => {+ compose(+ `<audio id="music" src="music.mp3" data-start="0" data-duration="4" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.25}'></audio>`,+ );+ const host = render(music, "duck");+ const item = duckLabel(host);+ expect(item?.getAttribute("aria-checked")).toBe("true");+ expect(item?.textContent).toBe("Duck under voice✓");+ });+ });+it("normalizes a video with sound by writing data-volume as one edit", async () => {const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };vi.stubGlobal(@@ -104,22 +149,20 @@ describe("ClipMenuAudioItems", () => {});it("stops ducking at the first refused save and says why", async () => {- document.body.appendChild(iframe);- const doc = iframe.contentDocument;- if (!doc) throw new Error("fixture");- doc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>+ previewDoc = document.implementation.createHTMLDocument("c");+ previewDoc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio><audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`;setQuiet.mockResolvedValue({status: "refused",reason: "Cannot edit timeline while recording",});- const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" });+ const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" }, "duck");await clickItem(host, "Duck under voice");await vi.waitFor(() =>expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error"),);expect(setQuiet).toHaveBeenCalledTimes(1);expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Ducks under"), "info");- iframe.remove();+ previewDoc = null;});});diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsxindex 0df27dd0f2..5488d84301 100644--- a/packages/studio/src/player/components/clipMenuAudioItems.tsx+++ b/packages/studio/src/player/components/clipMenuAudioItems.tsx@@ -2,6 +2,8 @@ import { formatAudioGain } from "@hyperframes/core/audio-gain";import type { TimelineElement } from "../store/timelineElement";import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";import { useStudioShellContextOptional } from "../../contexts/StudioContext";+import { usePlayerStore } from "../store/playerStore";+import { useLivePreviewIframe } from "../store/previewIframeStore";import {clipHasSound,normalizeToastText,@@ -11,7 +13,7 @@ import {VOLUME_LANE_REFUSAL,volumeLaneOwnsGain,} from "./clipMenuNormalize";-import { isDuckableBed, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";+import { offersDuck, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";const ITEM_CLASS ="w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 cursor-pointer";@@ -23,21 +25,28 @@ const DUCK_TOAST: Record<DuckOutcome, string> = {aborted: "Could not group the voices to duck under.",};-/** Sound group of the clip menu: Normalize loudness (one-shot) and Duck under voice (toggle). */+/** Normalize loudness (one-shot) or Duck under voice (toggle), placed separately in the sound group. */export function ClipMenuAudioItems({+ part,element,onClose,}: {+ part: "normalize" | "duck";element: TimelineElement;onClose: () => void;}) {const shell = useStudioShellContextOptional();- const { onSetElementAttributeQuiet, onGroupClips } = useTimelineEditContextOptional();- const doc = shell?.previewIframeRef.current?.contentDocument ?? null;+ const { onSetElementAttributeQuiet, onGroupClips, onNotice } = useTimelineEditContextOptional();+ const liveIframe = useLivePreviewIframe();+ const sessionProjectId = usePlayerStore((s) => s.timelineProjectId);+ const projectId = shell?.projectId ?? sessionProjectId;+ const showToast = shell?.showToast ?? onNotice;+ const doc = (shell?.previewIframeRef.current ?? liveIframe)?.contentDocument ?? null;const bed = doc?.getElementById(element.domId ?? element.id) ?? null;const ducked = bed ? readBedCarve(bed)?.enabled === true : false;- if (!clipHasSound(element) || !shell || !onSetElementAttributeQuiet) return null;- const { showToast, projectId } = shell;+ if (!clipHasSound(element) || !projectId || !showToast || !onSetElementAttributeQuiet) {+ return null;+ }const normalize = async () => {onClose();@@ -84,25 +93,24 @@ export function ClipMenuAudioItems({showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");};- return (- <>+ if (part === "normalize") {+ return (<button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}><span>Normalize loudness</span></button>- {isDuckableBed(bed) && (- <button- type="button"- role="menuitemcheckbox"- aria-checked={ducked}- className={ITEM_CLASS}- onClick={() => void toggleDuck()}- >- <span>- <span className="inline-block w-3">{ducked ? "✓" : ""}</span>Duck under voice- </span>- </button>- )}- <div className="my-1 border-t border-neutral-700/60" />- </>+ );+ }+ if (!offersDuck(doc, bed)) return null;+ return (+ <button+ type="button"+ role="menuitemcheckbox"+ aria-checked={ducked}+ className={ITEM_CLASS}+ onClick={() => void toggleDuck()}+ >+ <span>Duck under voice</span>+ <span aria-hidden="true">{ducked ? "✓" : ""}</span>+ </button>);}diff --git a/packages/studio/src/player/components/clipMenuDuck.ts b/packages/studio/src/player/components/clipMenuDuck.tsindex 6b8b258ed0..4af9a1ccac 100644--- a/packages/studio/src/player/components/clipMenuDuck.ts+++ b/packages/studio/src/player/components/clipMenuDuck.ts@@ -83,6 +83,11 @@ export function duckVoiceSources(doc: Document, bed: Element): string[] {.map((candidate) => candidate.id);}+export function offersDuck(doc: Document | null, bed: Element | null): boolean {+ if (!doc || !isDuckableBed(bed)) return false;+ return readBedCarve(bed)?.enabled === true || duckVoiceSources(doc, bed).length > 0;+}+async function writeMeasuredCarve(doc: Document,bed: Element,diff --git a/packages/studio/src/player/components/clipMenuLinkItems.test.ts b/packages/studio/src/player/components/clipMenuLinkItems.test.tsindex 98ef1c1971..2c94db56b1 100644--- a/packages/studio/src/player/components/clipMenuLinkItems.test.ts+++ b/packages/studio/src/player/components/clipMenuLinkItems.test.ts@@ -32,7 +32,7 @@ describe("resolveLinkMenuItems", () => {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",+ "Unlink from video","Merge audio back into video","Delete this clip only",]);@@ -42,9 +42,26 @@ describe("resolveLinkMenuItems", () => {const video = clip("talk", "video", { muted: true });const audio = clip("talk-audio", "audio");expect(labels(video, [video, audio], ["talk", "talk-audio"])).toEqual([- "Link",+ "Link to audio","Merge audio back into video",]);+ expect(labels(audio, [video, audio], ["talk", "talk-audio"])[0]).toBe("Link to video");+ });++ it("names the audio partner when unlinking from the video side", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-1" });+ const audio = clip("talk-audio", "audio", { link: "lk-1" });+ expect(labels(video, [video, audio])[0]).toBe("Unlink from audio");+ });++ it("falls back to plain Unlink for groups of three or same-kind partners", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-1" });+ const audio = clip("talk-audio", "audio", { link: "lk-1" });+ const second = clip("talk-audio2", "audio", { link: "lk-1" });+ expect(labels(video, [video, audio, second])[0]).toBe("Unlink");+ const twin = clip("talk2", "video", { muted: true, link: "lk-2" });+ const twin2 = clip("talk3", "video", { muted: true, link: "lk-2" });+ expect(labels(twin, [twin, twin2])[0]).toBe("Unlink");});it("offers nothing for a silent video or without a link handler", () => {diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsxindex a5ca0d0daa..4931b09d7e 100644--- a/packages/studio/src/player/components/clipMenuLinkItems.tsx+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx@@ -13,6 +13,16 @@ interface LinkMenuItem {const keyOf = (el: TimelineElement) => el.key ?? el.id;+const tagOf = (el: TimelineElement) => el.tag.trim().toLowerCase();++function partnerSuffix(element: TimelineElement, others: readonly TimelineElement[]): string {+ const partners = others.filter((el) => keyOf(el) !== keyOf(element));+ const [partner] = partners;+ if (partners.length !== 1 || !partner) return "";+ const pair = [tagOf(element), tagOf(partner)].sort().join("+");+ return pair === "audio+video" ? ` ${tagOf(partner)}` : "";+}+/** The link-model items for a clip, in wireframe order (detach · unlink/link · merge · delete-one). */export function resolveLinkMenuItems(input: {element: TimelineElement;@@ -36,13 +46,13 @@ export function resolveLinkMenuItems(input: {const selected = elements.filter((el) => selectedKeys.has(keyOf(el)));if (linked) {items.push({- label: "Unlink",+ label: `Unlink${partnerSuffix(element, members) && ` from${partnerSuffix(element, members)}`}`,shortcut: "⌘L",run: () => onLinkEdit({ kind: "unlink", elements: members }),});} else if (canLinkPair(selected) && selectedKeys.has(keyOf(element))) {items.push({- label: "Link",+ label: `Link${partnerSuffix(element, selected) && ` to${partnerSuffix(element, selected)}`}`,shortcut: "⌘L",run: () => onLinkEdit({ kind: "link", elements: selected }),});@@ -66,9 +76,11 @@ export function resolveLinkMenuItems(input: {}export function ClipMenuLinkItems({+ part,element,onClose,}: {+ part: "link" | "delete";element: TimelineElement;onClose: () => void;}) {@@ -81,7 +93,7 @@ export function ClipMenuLinkItems({selectedKeys,onLinkEdit,onDeleteElementOnly,- });+ }).filter((item) => (item.destructive === true) === (part === "delete"));if (items.length === 0) return null;return (<>@@ -104,7 +116,6 @@ export function ClipMenuLinkItems({)}</button>))}- <div className="my-1 border-t border-neutral-700/60" /></>);}diff --git a/packages/studio/src/player/components/clipMenuToolItems.tsx b/packages/studio/src/player/components/clipMenuToolItems.tsxindex bb372f3251..4acffdca5a 100644--- a/packages/studio/src/player/components/clipMenuToolItems.tsx+++ b/packages/studio/src/player/components/clipMenuToolItems.tsx@@ -175,7 +175,7 @@ function FreezeFrameItem({ element, currentTime, onClose }: Omit<ClipMenuToolIte);}-/** Freeze (time), Voice (sound), Look and Crop (picture); sound and picture end in their own divider. */+/** Freeze (time), Voice (sound), Look and Crop (picture). */export function ClipMenuToolItems(props: ClipMenuToolItemsProps) {if (props.group === "time") return <FreezeFrameItem {...props} />;return <ClipMenuAttributeItems {...props} />;@@ -204,7 +204,6 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPrwrite(HF_AUDIO_FX_ATTR, chainWithVoicePreset(state.fxChain, id), "Voice preset")}/>- <div className="my-1 border-t border-neutral-700/60" /></>);}@@ -229,7 +228,6 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPr><span>Crop</span></button>- <div className="my-1 border-t border-neutral-700/60" /></>);}diff --git a/packages/studio/src/player/components/clipSync.test.ts b/packages/studio/src/player/components/clipSync.test.tsnew file mode 100644index 0000000000..9d9fe557e3--- /dev/null+++ b/packages/studio/src/player/components/clipSync.test.ts@@ -0,0 +1,67 @@+import { describe, expect, it } from "vitest";+import { clipSyncState, syncPartnerOf } from "./clipSync";++const clip = (id: string, tag: string, start: number, extra: Record<string, unknown> = {}) => ({+ id,+ tag,+ start,+ duration: 4,+ track: 0,+ syncOrigin: "lk-1",+ ...extra,+});++describe("syncPartnerOf", () => {+ it("pairs a video with the audio sharing its sync origin, not another video", () => {+ const v = clip("v", "video", 0);+ const a = clip("a", "audio", 0);+ const other = clip("v2", "video", 0);+ expect(syncPartnerOf(a, [v, a, other])?.id).toBe("v");+ expect(syncPartnerOf(v, [v, a, other])?.id).toBe("a");+ });++ it("ignores clips with no or another origin", () => {+ const v = clip("v", "video", 0);+ expect(syncPartnerOf(v, [v, clip("a", "audio", 0, { syncOrigin: "lk-2" })])).toBeNull();+ expect(syncPartnerOf({ ...v, syncOrigin: undefined }, [v])).toBeNull();+ });++ it.each([{ sourceFile: "child.html" }, { compositionScope: "child" }])(+ "never pairs across compositions reusing an origin (%o)",+ (scope) => {+ const v = clip("v", "video", 0);+ expect(syncPartnerOf(v, [v, clip("a", "audio", 0, scope)])).toBeNull();+ },+ );++ it("after a split, picks the partner sharing the most timeline", () => {+ const a = clip("a", "audio", 4.2);+ const left = clip("v", "video", 0);+ const right = clip("v-split", "video", 4);+ expect(syncPartnerOf(a, [left, right, a])?.id).toBe("v-split");+ });+});++describe("clipSyncState", () => {+ it("is null in sync and signed per side when drifted", () => {+ const v = clip("v", "video", 1);+ expect(clipSyncState(v, [v, clip("a", "audio", 1)], 30)).toBeNull();+ const late = clip("a", "audio", 1 + 10 / 30);+ expect(clipSyncState(late, [v, late], 30)?.frames).toBe(10);+ expect(clipSyncState(v, [v, late], 30)?.frames).toBe(-10);+ });++ it("offers move and slip targets that each restore sync", () => {+ const v = clip("v", "video", 1, { playbackStart: 0 });+ const a = clip("a", "audio", 1.5, { playbackStart: 0 });+ const state = clipSyncState(a, [v, a], 30);+ expect(state?.moveStart).toBeCloseTo(1);+ expect(state?.slipMediaStart).toBeCloseTo(0.5);+ });++ it("has no badge when the halves play at different rates", () => {+ const v = clip("v", "video", 1, { playbackRate: 2 });+ const a = clip("a", "audio", 2);+ expect(clipSyncState(a, [v, a], 30)).toBeNull();+ });+});diff --git a/packages/studio/src/player/components/clipSync.ts b/packages/studio/src/player/components/clipSync.tsnew file mode 100644index 0000000000..f36705ce9d--- /dev/null+++ b/packages/studio/src/player/components/clipSync.ts@@ -0,0 +1,80 @@+import {+ moveIntoSyncStart,+ slipIntoSyncMediaStart,+ syncOffsetFrames,+ type SyncTiming,+} from "@hyperframes/core/media-link";+import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";++type SyncElement = Pick<+ TimelineElement,+ "id" | "key" | "tag" | "start" | "duration" | "playbackStart" | "playbackRate" | "syncOrigin"+> &+ Pick<TimelineElement, "sourceFile" | "compositionScope">;++const keyOf = (el: Pick<TimelineElement, "id" | "key">) => el.key ?? el.id;+const kindOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();++function syncTimingOf(el: SyncElement): SyncTiming {+ return { start: el.start, mediaStart: el.playbackStart ?? 0, playbackRate: el.playbackRate ?? 1 };+}++function overlap(a: SyncElement, b: SyncElement): number {+ return Math.min(a.start + a.duration, b.start + b.duration) - Math.max(a.start, b.start);+}++/**+ * The other half of `el`'s source pair: a video for an audio and the reverse,+ * sharing its sync origin. After splits several may qualify; the one sharing the+ * most timeline wins, then the nearest start.+ */+export function syncPartnerOf<T extends SyncElement>(el: T, elements: readonly T[]): T | null {+ const kind = kindOf(el);+ if (!el.syncOrigin || (kind !== "video" && kind !== "audio")) return null;+ const partnerKind = kind === "video" ? "audio" : "video";+ const candidates = elements.filter(+ (other) =>+ keyOf(other) !== keyOf(el) &&+ other.syncOrigin === el.syncOrigin &&+ sameCompositionScope(other, el) &&+ kindOf(other) === partnerKind,+ );+ const rank = (other: T) => [overlap(el, other), -Math.abs(other.start - el.start)] as const;+ let best: T | null = null;+ for (const candidate of candidates) {+ if (!best) best = candidate;+ else {+ const [o1, d1] = rank(candidate);+ const [o2, d2] = rank(best);+ if (o1 > o2 || (o1 === o2 && d1 > d2)) best = candidate;+ }+ }+ return best;+}++export interface ClipSyncState<T> {+ partner: T;+ frames: number;+ moveStart: number | null;+ slipMediaStart: number | null;+}++/** `el`'s drift from its source partner, or null when in sync, unpaired or at a different rate. */+export function clipSyncState<T extends SyncElement>(+ el: T,+ elements: readonly T[],+ fps: number,+): ClipSyncState<T> | null {+ const partner = syncPartnerOf(el, elements);+ if (!partner) return null;+ const self = syncTimingOf(el);+ const other = syncTimingOf(partner);+ const frames = syncOffsetFrames(self, other, fps);+ if (frames === null || frames === 0) return null;+ return {+ partner,+ frames,+ moveStart: moveIntoSyncStart(self, other),+ slipMediaStart: slipIntoSyncMediaStart(self, other),+ };+}diff --git a/packages/studio/src/player/components/linkLabelColor.test.ts b/packages/studio/src/player/components/linkLabelColor.test.tsnew file mode 100644index 0000000000..e94d49e44f--- /dev/null+++ b/packages/studio/src/player/components/linkLabelColor.test.ts@@ -0,0 +1,20 @@+import { describe, expect, it } from "vitest";+import { LINK_LABEL_COLORS, linkLabelColor } from "./linkLabelColor";++describe("linkLabelColor", () => {+ it("has no colour for an unlinked clip", () => {+ expect(linkLabelColor(undefined)).toBeNull();+ expect(linkLabelColor("")).toBeNull();+ });++ it("walks the palette in lk-N order, wrapping", () => {+ expect(linkLabelColor("lk-1")).toBe(LINK_LABEL_COLORS[0]);+ expect(linkLabelColor("lk-2")).toBe(LINK_LABEL_COLORS[1]);+ expect(linkLabelColor(`lk-${LINK_LABEL_COLORS.length + 1}`)).toBe(LINK_LABEL_COLORS[0]);+ });++ it("is deterministic for hand-written ids", () => {+ expect(linkLabelColor("talk-pair")).toBe(linkLabelColor("talk-pair"));+ expect(LINK_LABEL_COLORS).toContain(linkLabelColor("talk-pair"));+ });+});diff --git a/packages/studio/src/player/components/linkLabelColor.ts b/packages/studio/src/player/components/linkLabelColor.tsnew file mode 100644index 0000000000..58131814e9--- /dev/null+++ b/packages/studio/src/player/components/linkLabelColor.ts@@ -0,0 +1,24 @@+/** Link-group label colours; teal, violet, white and red belong to clips, selection and the sync badge. */+export const LINK_LABEL_COLORS = [+ "var(--color-amber-500)",+ "var(--color-sky-400)",+ "var(--color-green-400)",+ "var(--color-pink-400)",+ "var(--color-orange-400)",+ "var(--color-amber-300)",+] as const;++function stableIndex(link: string): number {+ const numbered = /^lk-(\d+)$/.exec(link);+ if (numbered) return Number(numbered[1]) - 1;+ let hash = 0;+ for (const char of link) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;+ return hash;+}++/** The same colour for every member of a link group, from its id alone. */+export function linkLabelColor(link: string | undefined): string | null {+ if (!link) return null;+ const count = LINK_LABEL_COLORS.length;+ return LINK_LABEL_COLORS[((stableIndex(link) % count) + count) % count] ?? null;+}diff --git a/packages/studio/src/player/components/timelineCallbacks.ts b/packages/studio/src/player/components/timelineCallbacks.tsindex 812e6ca022..56b96dacc8 100644--- a/packages/studio/src/player/components/timelineCallbacks.ts+++ b/packages/studio/src/player/components/timelineCallbacks.ts@@ -43,7 +43,9 @@ export type TimelineLinkEdit =| { kind: "unlink"; elements: readonly TimelineElement[] }| { kind: "link"; elements: readonly TimelineElement[] }| { kind: "detach"; element: TimelineElement }- | { kind: "merge"; video: TimelineElement; audio: TimelineElement };+ | { kind: "merge"; video: TimelineElement; audio: TimelineElement }+ | { kind: "move-into-sync"; element: TimelineElement; start: number }+ | { kind: "slip-into-sync"; element: TimelineElement; mediaStart: number };export interface TimelineEditCallbacks {onMoveElement?: (@@ -127,6 +129,7 @@ export interface TimelineEditCallbacks {onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;onRazorSplitAll?: (splitTime: number) => Promise<void> | void;onFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;+ onNotice?: (message: string, tone?: "error" | "info") => void;onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;onDeleteAllKeyframes?: (element: TimelineElement, animationId?: string) => void;onMoveKeyframeToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;diff --git a/packages/studio/src/player/components/timelineLinkSelection.ts b/packages/studio/src/player/components/timelineLinkSelection.tsindex 1ed00acc8c..231ee2df94 100644--- a/packages/studio/src/player/components/timelineLinkSelection.ts+++ b/packages/studio/src/player/components/timelineLinkSelection.ts@@ -1,9 +1,10 @@import { usePlayerStore } from "../store/playerStore";import { expandToLinkedMembers } from "./audioClipLink";+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";/*** 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.+ * (or Linked Selection off) selects `key` alone, even inside a larger selection.*/export function selectClipWithLinks(key: string,@@ -11,7 +12,7 @@ export function selectClipWithLinks(setSelectedElementId: (id: string) => void,): void {const state = usePlayerStore.getState();- if (altKey) {+ if (altKey || !isLinkedSelectionOn()) {state.setSelection([key], key);return;}diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.tsindex 41a21dd815..327e1ca247 100644--- a/packages/studio/src/player/components/useTimelineClipDrag.ts+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts@@ -28,6 +28,7 @@ import type {} from "./timelineClipDragTypes";import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";import { linkedGestureKeys } from "./audioClipLink";+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";import type { TimelineRowGeometry } from "./timelineLayout";import {mountTimelineClipDragGestureLifecycle,@@ -228,6 +229,7 @@ export function useTimelineClipDrag({next.element,elementsRef.current,next.altKey === true,+ isLinkedSelectionOn(),);publishDraggedClip(next);},@@ -245,6 +247,7 @@ export function useTimelineClipDrag({next.element,elementsRef.current,next.altKey === true,+ isLinkedSelectionOn(),);publishResizingClip(next);},diff --git a/packages/studio/src/player/hooks/timelinePlayerSync.test.ts b/packages/studio/src/player/hooks/timelinePlayerSync.test.tsindex 1ced1ee283..1f0df8de61 100644--- a/packages/studio/src/player/hooks/timelinePlayerSync.test.ts+++ b/packages/studio/src/player/hooks/timelinePlayerSync.test.ts@@ -13,9 +13,15 @@ describe("timelineElementsChanged", () => {["audio group hidden", { audioGroupHidden: true }],["fade in", { fadeIn: 1 }],["fade out", { fadeOut: 1 }],+ ["link", { link: "lk-1" }],["source (re-pointed at its preview copy)", { src: "clip1.mp4?hf-proxy=h264" }],])("sees a clip whose %s changed with no timing change", (_name, change) => {expect(timelineElementsChanged([clip], [{ ...clip, ...change }])).toBe(true);expect(timelineElementsChanged([{ ...clip, ...change }], [{ ...clip, ...change }])).toBe(false);});++ it("sees an unlink: the same clips re-derived without their link", () => {+ const linked = { ...clip, link: "lk-1" };+ expect(timelineElementsChanged([linked], [clip])).toBe(true);+ });});diff --git a/packages/studio/src/player/hooks/timelinePlayerSync.ts b/packages/studio/src/player/hooks/timelinePlayerSync.tsindex 6991979acc..4bba7f1572 100644--- a/packages/studio/src/player/hooks/timelinePlayerSync.ts+++ b/packages/studio/src/player/hooks/timelinePlayerSync.ts@@ -16,6 +16,7 @@ const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = ["fadeIn","fadeOut","src",+ "link",];/** Whether a derived timeline changes any field that affects rendering. */diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.tsindex 089312cf4c..e0231bf32b 100644--- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts@@ -15,6 +15,7 @@ import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";import { readTimelineDurationFromDocument } from "../lib/timelineDOM";import { buildMissingCompositionElements } from "../lib/timelineIframeHelpers";import { acceptedRuntimeMessageFps } from "../lib/runtimeProtocol";+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";import {buildTimelineElementsFromClips,syncManifestTimeline,@@ -196,8 +197,10 @@ export function useTimelineSyncCallbacks({// at the authored root `data-duration` so a runtime that measures only the// furthest clip end (shorter than the authored window) can't leave a stale,// too-short total in the transport (the "0:44/0:40" bug).+ const fps = acceptedRuntimeMessageFps(data);+ useLinkedClipPreferences.getState().setCompositionFps(fps);const newDuration = resolveTimelineTotalDuration({- manifestDurationSeconds: data.durationInFrames / acceptedRuntimeMessageFps(data),+ manifestDurationSeconds: data.durationInFrames / fps,authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),});syncManifestTimeline(diff --git a/packages/studio/src/player/lib/timelineDOM.test.ts b/packages/studio/src/player/lib/timelineDOM.test.tsindex f0b03876ef..3b5790b1e0 100644--- a/packages/studio/src/player/lib/timelineDOM.test.ts+++ b/packages/studio/src/player/lib/timelineDOM.test.ts@@ -282,13 +282,15 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {expect(element.hidden).toBe(true);});- it("reads data-link on both the DOM and manifest paths", () => {+ it("reads data-link and data-sync-origin 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>+ <video id="talk" class="clip" src="t.mp4" muted data-link="lk-1" data-sync-origin="lk-1" data-start="0" data-duration="5"></video></div>`);- expect(parseTimelineFromDOM(doc, 10).find((el) => el.domId === "talk")?.link).toBe("lk-1");+ const fromDom = parseTimelineFromDOM(doc, 10).find((el) => el.domId === "talk");+ expect(fromDom?.link).toBe("lk-1");+ expect(fromDom?.syncOrigin).toBe("lk-1");const element = createTimelineElementFromManifestClip({clip: {id: "talk",@@ -308,6 +310,7 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {hostEl: doc.getElementById("talk"),});expect(element.link).toBe("lk-1");+ expect(element.syncOrigin).toBe("lk-1");});});diff --git a/packages/studio/src/player/lib/timelineDOM.ts b/packages/studio/src/player/lib/timelineDOM.tsindex 1efa59e438..23b8b68ff9 100644--- a/packages/studio/src/player/lib/timelineDOM.ts+++ b/packages/studio/src/player/lib/timelineDOM.ts@@ -155,6 +155,8 @@ export function createTimelineElementFromManifestClip(params: {if (link) entry.link = link;const compositionScope = linkScopeOf(hostEl)?.getAttribute("data-composition-id");if (compositionScope) entry.compositionScope = compositionScope;+ const syncOrigin = hostEl.getAttribute("data-sync-origin");+ if (syncOrigin) entry.syncOrigin = syncOrigin;const audioGroup = hostEl.getAttribute("data-audio-group");if (audioGroup) {entry.audioGroup = audioGroup;@@ -346,6 +348,8 @@ export function parseTimelineFromDOM(if (domLink) entry.link = domLink;const domCompositionScope = linkScopeOf(el)?.getAttribute("data-composition-id");if (domCompositionScope) entry.compositionScope = domCompositionScope;+ const domSyncOrigin = el.getAttribute("data-sync-origin");+ if (domSyncOrigin) entry.syncOrigin = domSyncOrigin;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 90f7a85206..33b612c145 100644--- a/packages/studio/src/player/store/timelineElement.ts+++ b/packages/studio/src/player/store/timelineElement.ts@@ -85,6 +85,7 @@ export interface TimelineElement {audioGroupAutomation?: string;link?: string;compositionScope?: string;+ syncOrigin?: 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.diff --git a/packages/studio/src/styles/components.css b/packages/studio/src/styles/components.cssindex 72af960356..f08933159c 100644--- a/packages/studio/src/styles/components.css+++ b/packages/studio/src/styles/components.css@@ -296,17 +296,6 @@transition: none;}-.timeline-audio-link {- position: absolute;- z-index: 4;- top: -9px;- left: 50%;- width: 1px;- height: 10px;- background: var(--timeline-audio-link);- pointer-events: none;-}-.timeline-clip.is-hovered {background-color: var(--clip-bg-hover);}@@ -362,6 +351,16 @@white-space: nowrap;}+/* Link groups share a label colour on the border and the name chip. */+.timeline-clip[data-link-color] {+ border-color: var(--clip-link-color);+}++.timeline-clip[data-link-color] .timeline-clip__label {+ box-shadow: inset 3px 0 0 var(--clip-link-color);+ padding-left: 8px;+}+.timeline-clip.is-audio .timeline-clip__label {top: 11px;left: 9px;diff --git a/packages/studio/src/styles/theme.css b/packages/studio/src/styles/theme.cssindex 6486f033fa..bb5a48cfd6 100644--- a/packages/studio/src/styles/theme.css+++ b/packages/studio/src/styles/theme.css@@ -117,7 +117,6 @@--timeline-clip-audio-bg-hover: oklch(0.49 0.12 300);--timeline-clip-audio-bg-dragging: oklch(0.42 0.12 300 / 0.96);--timeline-clip-audio-muted-bg: rgb(72, 74, 78);- --timeline-audio-link: light-dark(#626d66, #a0aaa4);--timeline-clip-selection: light-dark(#0f766e, rgba(255, 255, 255, 0.85));--timeline-clip-selection-highlight: rgb(255 255 255 / 0.55);--timeline-clip-radius: 8px;diff --git a/packages/studio/src/utils/linkedClipPreferences.ts b/packages/studio/src/utils/linkedClipPreferences.tsnew file mode 100644index 0000000000..acb8b99a7c--- /dev/null+++ b/packages/studio/src/utils/linkedClipPreferences.ts@@ -0,0 +1,34 @@+import { create } from "zustand";+import { STUDIO_PREVIEW_FPS } from "../player/lib/time";+import { readStudioUiPreferences, writeStudioUiPreferences } from "./studioUiPreferences";++interface LinkedClipPreferences {+ /** Premiere's Linked Selection: clicks and edits reach every link partner. */+ linkedSelection: boolean;+ setLinkedSelection: (enabled: boolean) => void;+ /** Red offset badges on a video and audio from one source that drifted apart. */+ syncIndicatorsVisible: boolean;+ setSyncIndicatorsVisible: (visible: boolean) => void;+ compositionFps: number;+ setCompositionFps: (fps: number) => void;+}++export const useLinkedClipPreferences = create<LinkedClipPreferences>((set) => ({+ linkedSelection: readStudioUiPreferences().linkedSelectionEnabled ?? true,+ setLinkedSelection: (enabled) => {+ writeStudioUiPreferences({ linkedSelectionEnabled: enabled });+ set({ linkedSelection: enabled });+ },+ syncIndicatorsVisible: readStudioUiPreferences().syncIndicatorsVisible ?? true,+ setSyncIndicatorsVisible: (visible) => {+ writeStudioUiPreferences({ syncIndicatorsVisible: visible });+ set({ syncIndicatorsVisible: visible });+ },+ compositionFps: STUDIO_PREVIEW_FPS,+ setCompositionFps: (fps) => {+ if (Number.isFinite(fps) && fps > 0) set({ compositionFps: fps });+ },+}));++export const isLinkedSelectionOn = (): boolean =>+ useLinkedClipPreferences.getState().linkedSelection;diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.tsindex 4e1fdc9f99..4c72902705 100644--- a/packages/studio/src/utils/studioUiPreferences.ts+++ b/packages/studio/src/utils/studioUiPreferences.ts@@ -45,6 +45,8 @@ export interface StudioUiPreferences {theme?: StudioTheme;/** The dock's serialized panel tree; parsed by `parseDockLayout` on read. */dockLayout?: SerializedDockview;+ linkedSelectionEnabled?: boolean;+ syncIndicatorsVisible?: boolean;}const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";@@ -146,6 +148,12 @@ function readStorage(storage: Storage | null, key: string): StudioUiPreferencesif (typeof parsed.agentToolsEnabled === "boolean") {preferences.agentToolsEnabled = parsed.agentToolsEnabled;}+ if (typeof parsed.linkedSelectionEnabled === "boolean") {+ preferences.linkedSelectionEnabled = parsed.linkedSelectionEnabled;+ }+ if (typeof parsed.syncIndicatorsVisible === "boolean") {+ preferences.syncIndicatorsVisible = parsed.syncIndicatorsVisible;+ }const dockLayout = parseDockLayout(parsed.dockLayout);if (dockLayout) preferences.dockLayout = dockLayout;return preferences;diff --git a/skills-manifest.json b/skills-manifest.jsonindex f380caf3df..bfe3e58016 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -34,7 +34,7 @@"files": 11},"hyperframes-core": {- "hash": "3bc49ffe4697122b",+ "hash": "539de2110ccdaa43","files": 11},"hyperframes-creative": {diff --git a/skills/hyperframes-core/references/data-attributes.md b/skills/hyperframes-core/references/data-attributes.mdindex 7949c27dd8..83d9943707 100644--- a/skills/hyperframes-core/references/data-attributes.md+++ b/skills/hyperframes-core/references/data-attributes.md@@ -36,6 +36,7 @@ The root should be `position: relative`, have explicit pixel dimensions, and hid| `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). |+| `data-sync-origin` | No | Editing contract only: a video and audio from one source file share it (written by Detach and Link, kept by Unlink). Studio flags the pair out of sync when their source-zero points differ. 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 93f7023177..72b1a51f49 100644--- a/skills/hyperframes-core/references/tracks-and-clips.md+++ b/skills/hyperframes-core/references/tracks-and-clips.md@@ -58,6 +58,7 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audiosrc="talk.mp4"muteddata-link="lk-1"+ data-sync-origin="lk-1"data-start="2"data-duration="6"data-media-start="1"@@ -67,6 +68,7 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audioid="talk-audio"src="talk.mp4"data-link="lk-1"+ data-sync-origin="lk-1"data-start="2"data-duration="6"data-media-start="1"@@ -78,6 +80,7 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audio- **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>`.+- **Sync origin.** `data-sync-origin="<id>"` marks a video and an audio from one source file; Detach and Link write it, and Unlink keeps it. When the pair drifts (their source-zero points, `data-start − data-media-start / data-playback-rate`, differ), Studio shows a red offset in frames on both halves with Move into Sync / Slip into Sync, `hyperframes timeline` prints `out-of-sync=±Nf`, and the SDK offers `syncOffset`, `moveIntoSync` and `slipIntoSync`. Leave it alone when retiming by hand; remove it only when the clips are no longer one source.- `@hyperframes/sdk` `setTiming` applies to link partners by default; pass `{ linked: false }` to edit one member, which unlinks it.## Relative Timing