Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(studio): audio gain on G, speed in clip names, additive selection and partner clamp (8/8) (#4821)
Vance Ingalls70900216f0da
diff --git a/packages/sdk/src/engine/mutate.ts b/packages/sdk/src/engine/mutate.tsindex 4d5cc7f74d..4cd3676df2 100644--- a/packages/sdk/src/engine/mutate.ts+++ b/packages/sdk/src/engine/mutate.ts@@ -17,7 +17,7 @@ import type {JsonPatchOp,} from "../types.js";import type { ParsedDocument } from "./model.js";-import { MEDIA_LINK_ATTR } from "@hyperframes/core/media-link";+import { MEDIA_LINK_ATTR, linkScopeOf } from "@hyperframes/core/media-link";import { idsToUnlink, linkedPartnerIds } from "./linkedTiming.js";import {resolveScoped,@@ -298,16 +298,96 @@ function applySetTiming(const own = handleSetTiming(parsed, ids, timing);return concatResults(own, handleSetAttribute(parsed, unlink, MEDIA_LINK_ATTR, null));}- const partners =- op.start === undefined && op.duration === undefined- ? []- : linkedPartnerIds(parsed.document, ids);- const own = handleSetTiming(parsed, ids, timing);- if (partners.length === 0) return own;- return concatResults(- own,- handleSetTiming(parsed, partners, { start: op.start, duration: op.duration }),- );+ const plan = planLinkedTiming(parsed, ids, timing);+ if (plan.refusal) throw new Error(plan.refusal);+ let result = handleSetTiming(parsed, ids, timing);+ for (const partner of plan.partners) {+ result = concatResults(result, handleSetTiming(parsed, [partner.id], partner.timing));+ }+ return result;+}++type PartnerEdit = { id: HfId; timing: { start?: number; duration?: number } };++function planLinkedTiming(+ parsed: ParsedDocument,+ ids: HfId[],+ timing: { start?: number; duration?: number },+): { partners: PartnerEdit[]; refusal: string | null } {+ if (timing.start === undefined && timing.duration === undefined) {+ return { partners: [], refusal: null };+ }+ const grabbedFor = grabbedBaselines(parsed, ids);+ const partners: PartnerEdit[] = [];+ for (const id of linkedPartnerIds(parsed.document, ids)) {+ const el = resolveScoped(parsed.document, id);+ const grabbed = el ? grabbedFor(el) : undefined;+ if (!el || !grabbed) continue;+ const partnerEdit = partnerTiming(grabbed, readClipTiming(el), timing);+ if (partnerEdit.duration !== undefined && partnerEdit.duration <= 0) {+ const tag = el.tagName.toLowerCase();+ return {+ partners: [],+ refusal: `Linked ${tag} would start after the new end — unlink or trim the ${tag} first.`,+ };+ }+ partners.push({ id, timing: partnerEdit });+ }+ return { partners, refusal: null };+}++type ClipWindow = { start: number | null; duration: number | null };++function grabbedBaselines(+ parsed: ParsedDocument,+ ids: HfId[],+): (partner: Element) => ClipWindow | undefined {+ const byScope = new Map<Element | null, Map<string, ClipWindow>>();+ for (const id of ids) {+ const el = resolveScoped(parsed.document, id);+ const link = el?.getAttribute(MEDIA_LINK_ATTR);+ if (!el || !link) continue;+ const byLink = byScope.get(linkScopeOf(el)) ?? new Map<string, ClipWindow>();+ byLink.set(link, readClipTiming(el));+ byScope.set(linkScopeOf(el), byLink);+ }+ return (partner) => {+ const link = partner.getAttribute(MEDIA_LINK_ATTR);+ return link ? byScope.get(linkScopeOf(partner))?.get(link) : undefined;+ };+}+const ALIGN_EPSILON_S = 1e-3;++/**+ * A partner follows the edit without resyncing: a start change shifts it by the+ * same delta (keeping any offset); a duration change carries over only when the+ * partner's end sat at the edited clip's end.+ */+function partnerTiming(+ grabbed: ClipWindow,+ partner: ClipWindow,+ edit: { start?: number; duration?: number },+): { start?: number; duration?: number } {+ const timing: { start?: number; duration?: number } = {};+ const [gStart, pStart] = [grabbed.start ?? 0, partner.start ?? 0];+ if (edit.start !== undefined) timing.start = pStart + (edit.start - gStart);+ const duration = partnerDuration(grabbed, partner, edit, timing.start ?? pStart);+ if (duration !== undefined) timing.duration = duration;+ return timing;+}++function partnerDuration(+ grabbed: ClipWindow,+ partner: ClipWindow,+ edit: { start?: number; duration?: number },+ partnerStart: number,+): number | undefined {+ if (edit.duration === undefined) return undefined;+ const grabbedStart = grabbed.start ?? 0;+ const grabbedEnd = grabbedStart + (grabbed.duration ?? 0);+ const partnerEnd = (partner.start ?? 0) + (partner.duration ?? 0);+ if (Math.abs(partnerEnd - grabbedEnd) >= ALIGN_EPSILON_S) return undefined;+ return (edit.start ?? grabbedStart) + edit.duration - partnerStart;}export function applyOp(parsed: ParsedDocument, op: EditOp): MutationResult {@@ -1667,7 +1747,11 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {`Element(s) not found: ${missing.join(", ")}.`,"Verify the id against comp.getElements() or comp.find().",);- return CAN_OK;+ const refusal =+ op.type === "setTiming" && op.linked !== false+ ? planLinkedTiming(parsed, ids, op).refusal+ : null;+ return refusal ? canErr("E_LINKED_PARTNER_CROSSED", refusal) : CAN_OK;}case "addElement": {if (op.parent !== null && resolveScoped(parsed.document, op.parent) === null)diff --git a/packages/sdk/src/session.linked.test.ts b/packages/sdk/src/session.linked.test.tsindex 4baac66e70..7829f284b5 100644--- a/packages/sdk/src/session.linked.test.ts+++ b/packages/sdk/src/session.linked.test.ts@@ -36,6 +36,31 @@ describe("setTiming on linked clips", () => {expect(attr(html, "hf-talk-audio", "data-duration")).toBe("6");});+ it("moves a misaligned pair by the same delta, preserving the offset", async () => {+ const html = LINKED_HTML.replace(+ 'src="talk.mp4" data-link="lk-1" data-start="2"',+ 'src="talk.mp4" data-link="lk-1" data-start="3"',+ );+ const comp = await openComposition(html);+ comp.setTiming("hf-talk", { start: 5 });+ const out = comp.serialize();+ expect(attr(out, "hf-talk", "data-start")).toBe("5");+ expect(attr(out, "hf-talk-audio", "data-start")).toBe("6");+ });++ it("keeps a common end when partners start at different times", async () => {+ const offset = LINKED_HTML.replace(+ 'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',+ 'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',+ );+ const comp = await openComposition(offset);+ comp.setTiming("hf-talk", { duration: 4 });+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-duration")).toBe("4");+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("3");+ expect(attr(html, "hf-talk-audio", "data-duration")).toBe("3");+ });+it("{ linked: false } edits one member and unlinks the pair", async () => {const comp = await openComposition(LINKED_HTML);comp.setTiming("hf-talk", { start: 5 }, { linked: false });@@ -127,4 +152,100 @@ describe("setTiming on linked clips", () => {);expect(comp.serialize()).toBe((await openComposition(html)).serialize());});++ describe("a duration edit whose new end would cross a linked partner's start", () => {+ const OFFSET_HTML = LINKED_HTML.replace(+ 'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',+ 'data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',+ );++ it.each([1, 0.5])("refuses duration %s atomically, before any mutation", async (duration) => {+ const comp = await openComposition(OFFSET_HTML);+ comp.setTiming("hf-music", { start: 1 });+ const before = comp.serialize();+ expect(comp.can({ type: "setTiming", target: "hf-talk", duration })).toMatchObject({+ ok: false,+ code: "E_LINKED_PARTNER_CROSSED",+ });+ expect(() => comp.setTiming("hf-talk", { duration })).toThrow(+ /linked audio would start after the new end/i,+ );+ expect(comp.serialize()).toBe(before);+ comp.undo();+ expect(attr(comp.serialize(), "hf-music", "data-start")).toBe("0");+ expect(comp.canUndo()).toBe(false);+ });++ it("trims the partner to the shared end while that end stays after its start", async () => {+ const comp = await openComposition(OFFSET_HTML);+ expect(comp.can({ type: "setTiming", target: "hf-talk", duration: 1.5 }).ok).toBe(true);+ comp.setTiming("hf-talk", { duration: 1.5 });+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-duration")).toBe("1.5");+ expect(attr(html, "hf-talk-audio", "data-start")).toBe("3");+ expect(attr(html, "hf-talk-audio", "data-duration")).toBe("0.5");+ });++ it("allows the same edit once the pair is unlinked", async () => {+ const comp = await openComposition(OFFSET_HTML);+ comp.setTiming("hf-talk", { duration: 0.5 }, { linked: false });+ const html = comp.serialize();+ expect(attr(html, "hf-talk", "data-duration")).toBe("0.5");+ expect(attr(html, "hf-talk-audio", "data-duration")).toBe("5");+ });+ });++ describe.each([+ { host: 'data-composition-id="child" data-composition-file="child.html"', cv: "hf-host/hf-cv" },+ { host: 'data-composition-id="child"', cv: "hf-cv" },+ ])(+ "one edit naming linked clips in two compositions that reuse a link id ($host)",+ ({ host, cv }) => {+ const TWO_SCOPES_HTML = `+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">+ <video data-hf-id="hf-v" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>+ <audio data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6" data-track-index="1"></audio>+ <div data-hf-id="hf-host" ${host} data-start="0" data-duration="10" data-track-index="2">+ <video data-hf-id="hf-cv" src="b.mp4" muted data-link="lk-1" data-start="0" data-duration="4" data-track-index="0"></video>+ <audio data-hf-id="hf-ca" src="b.mp4" data-link="lk-1" data-start="0" data-duration="4" data-track-index="1"></audio>+ </div>+</div>`.trim();++ it("trims each audio against its own video's baseline", async () => {+ const comp = await openComposition(TWO_SCOPES_HTML);+ comp.dispatch({ type: "setTiming", target: ["hf-v", cv], duration: 0.5 });+ const html = comp.serialize();+ expect([attr(html, "hf-v", "data-start"), attr(html, "hf-v", "data-duration")]).toEqual([+ "2",+ "0.5",+ ]);+ expect([attr(html, "hf-a", "data-start"), attr(html, "hf-a", "data-duration")]).toEqual([+ "2",+ "0.5",+ ]);+ expect([attr(html, "hf-cv", "data-start"), attr(html, "hf-cv", "data-duration")]).toEqual([+ "0",+ "0.5",+ ]);+ expect([attr(html, "hf-ca", "data-start"), attr(html, "hf-ca", "data-duration")]).toEqual([+ "0",+ "0.5",+ ]);+ });++ it("refuses against the scoped baseline when one scope's audio would cross its video's end", async () => {+ const crossing = TWO_SCOPES_HTML.replace(+ 'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="2" data-duration="6"',+ 'data-hf-id="hf-a" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5"',+ );+ const comp = await openComposition(crossing);+ const before = comp.serialize();+ const op = { type: "setTiming" as const, target: ["hf-v", cv], duration: 0.5 };+ expect(comp.can(op)).toMatchObject({ ok: false, code: "E_LINKED_PARTNER_CROSSED" });+ expect(() => comp.dispatch(op)).toThrow(/linked audio would start after the new end/i);+ expect(comp.serialize()).toBe(before);+ expect(comp.canUndo()).toBe(false);+ });+ },+ );});diff --git a/packages/studio/src/components/editor/mediaLinkEdits.test.ts b/packages/studio/src/components/editor/mediaLinkEdits.test.tsindex 5fbc15e534..5e9da0df07 100644--- a/packages/studio/src/components/editor/mediaLinkEdits.test.ts+++ b/packages/studio/src/components/editor/mediaLinkEdits.test.ts@@ -10,6 +10,7 @@ import {pickDetachedAudioTrack,removeElementInSource,setLinkInSource,+ sharesSourceFile,} from "./mediaLinkEdits";const automation = JSON.stringify({@@ -192,6 +193,15 @@ describe("linkInSource", () => {});});+describe("linkInSource without a sync origin", () => {+ it("writes only data-link", () => {+ const src = '<video id="v"></video><audio id="a"></audio>';+ expect(linkInSource(src, [{ id: "v" }, { id: "a" }], { syncOrigin: false })).toBe(+ '<video id="v" data-link="lk-1"></video><audio id="a" data-link="lk-1"></audio>',+ );+ });+});+describe("setLinkInSource", () => {it("writes and removes data-link on every target", () => {const src = '<video id="v"></video><audio id="a"></audio>';@@ -248,9 +258,12 @@ describe("predicates", () => {expect(findMergePair(v, [v, el("a", "audio", { src: "other.mp4" })])).toBeNull();});- it("links exactly one video and one audio of the same file and timing", () => {+ it("links exactly one unlinked video and one audio, whatever their timing or file", () => {expect(canLinkPair([el("v", "video"), el("a", "audio")])).toBe(true);- expect(canLinkPair([el("v", "video"), el("a", "audio", { start: 3 })])).toBe(false);+ expect(canLinkPair([el("v", "video"), el("a", "audio", { start: 3, duration: 2 })])).toBe(true);+ expect(canLinkPair([el("v", "video"), el("a", "audio", { src: "other.mp3" })])).toBe(true);+ expect(canLinkPair([el("v", "video", { link: "x" }), el("a", "audio")])).toBe(false);+ expect(canLinkPair([el("v", "video"), el("a", "audio", { link: "y" })])).toBe(false);expect(canLinkPair([el("v", "video"), el("w", "video")])).toBe(false);expect(canLinkPair([el("v", "video", { link: "x" }), el("a", "audio", { link: "x" })])).toBe(false,@@ -266,16 +279,16 @@ describe("predicates compare the whole asset path", () => {const v = el("v", "video", { muted: true, ...one });const a = el("a", "audio", two);expect(findMergePair(v, [v, a])).toBeNull();- expect(canLinkPair([el("v", "video", one), el("a", "audio", two)])).toBe(false);+ expect(sharesSourceFile([el("v", "video", one), el("a", "audio", two)])).toBe(false);});it("resolves each src against its own source file, and links only inside one", () => {const v = el("v", "video", { src: "../assets/talk.mp4", sourceFile: "scenes/a.html" });const a = el("a", "audio", { src: "./assets/talk.mp4", sourceFile: "index.html" });expect(canLinkPair([v, a])).toBe(false);- expect(- canLinkPair([v, { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" }]),- ).toBe(true);+ expect(sharesSourceFile([v, a])).toBe(false);+ const sameFileAudio = { ...a, src: "../assets/./talk.mp4", sourceFile: "scenes/a.html" };+ expect(sharesSourceFile([v, sameFileAudio])).toBe(true);});it("does not take a same-id link from another source file as the merge partner", () => {diff --git a/packages/studio/src/components/editor/mediaLinkEdits.ts b/packages/studio/src/components/editor/mediaLinkEdits.tsindex 999895e721..10113c77be 100644--- a/packages/studio/src/components/editor/mediaLinkEdits.ts+++ b/packages/studio/src/components/editor/mediaLinkEdits.ts@@ -1,5 +1,10 @@import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";-import { MEDIA_LINK_ATTR, SYNC_ORIGIN_ATTR, mintLinkId } from "@hyperframes/core/media-link";+import {+ MEDIA_LINK_ATTR,+ SYNC_ORIGIN_ATTR,+ mintLinkId,+ sourceZeroTime,+} from "@hyperframes/core/media-link";import { sameCompositionScope, type TimelineElement } from "../../player/store/timelineElement";import { mediaAssetIdentity, sharesLinkGroup } from "../../player/components/audioClipLink";import {@@ -62,14 +67,17 @@ export function setLinkInSource();}-/** Link the targets under one freshly minted id, which is also their sync origin. */-export function linkInSource(source: string, targets: readonly PatchTarget[]): string {+/** Link the targets under one fresh id, also their sync origin when they share a source file. */+export function linkInSource(+ source: string,+ targets: readonly PatchTarget[],+ options: { syncOrigin: boolean } = { syncOrigin: true },+): string {const linkId = mintLinkIdForSource(source);- return targets.reduce(- (html, target) =>- applyOps(html, target, [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]),- source,- );+ const ops = options.syncOrigin+ ? [dataOp(LINK_PROPERTY, linkId), dataOp(SYNC_ORIGIN_PROPERTY, linkId)]+ : [dataOp(LINK_PROPERTY, linkId)];+ return targets.reduce((html, target) => applyOps(html, target, ops), source);}/** Remove one element (open tag through its matching close tag) and its line's indentation. */@@ -242,15 +250,28 @@ export function findMergePair<T extends TimedElement>(return video.muted === true ? { video, audio } : null;}-/** Exactly one video and one audio, same file, identical timing, not already linked together. */+/** One video and one audio in one composition, neither linked: timing and file don't matter. */export function canLinkPair(selected: readonly TimedElement[]): boolean {if (selected.length !== 2) return false;const [a, b] = selected;- if (!a || !b) return false;+ if (!a || !b || a.link || b.link) return false;const tags = new Set([tagOf(a), tagOf(b)]);- if (!tags.has("video") || !tags.has("audio")) return false;- if (sharesLinkGroup(a, b)) return false;- return sameAssetInScope(a, b) && hasIdenticalTiming(a, b);+ return tags.has("video") && tags.has("audio") && sameCompositionScope(a, b);+}++export function sharesSourceFile(selected: readonly TimedElement[]): boolean {+ const [a, b] = selected;+ return selected.length === 2 && !!a && !!b && sameAssetInScope(a, b);+}++export function isPairInSync(a: TimedElement, b: TimedElement): boolean {+ const timing = (el: TimedElement) => ({+ start: el.start,+ mediaStart: el.playbackStart ?? 0,+ playbackRate: el.playbackRate ?? 1,+ });+ const [x, y] = [timing(a), timing(b)];+ return near(x.playbackRate, y.playbackRate) && near(sourceZeroTime(x), sourceZeroTime(y));}type TrackedElement = Pick<TimelineElement, "tag" | "track" | "start" | "duration"> & {diff --git a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts b/packages/studio/src/components/nle/useTimelineEditCallbacks.tsindex beacb819ed..8f66485f15 100644--- a/packages/studio/src/components/nle/useTimelineEditCallbacks.ts+++ b/packages/studio/src/components/nle/useTimelineEditCallbacks.ts@@ -72,6 +72,7 @@ export interface TimelineEditCallbackDeps {value: string | null,label: string,) => Promise<TimelineEditOutcome | void>;+ setMany?: TimelineEditCallbacks["onSetElementsAttributeQuiet"];};}@@ -228,6 +229,7 @@ export function useTimelineEditCallbacks({onGroupClips: handleGroupClips,onSetElementAttributeLive: setElementFxAttribute?.setLive,onSetElementAttributeQuiet: setElementFxAttribute?.setQuiet,+ onSetElementsAttributeQuiet: setElementFxAttribute?.setMany,onRevertElementAttributeLive: setElementFxAttribute?.revertLive,onBlockedEditAttempt: handleBlockedTimelineEdit,onSplitElement: handleTimelineElementSplit,diff --git a/packages/studio/src/contexts/TimelineEditContext.tsx b/packages/studio/src/contexts/TimelineEditContext.tsxindex 3144ee661f..48d7989111 100644--- a/packages/studio/src/contexts/TimelineEditContext.tsx+++ b/packages/studio/src/contexts/TimelineEditContext.tsx@@ -37,6 +37,7 @@ const EDIT_CALLBACK_KEY_SET: Record<keyof TimelineEditCallbacks, true> = {onGroupClips: true,onSetElementAttributeLive: true,onSetElementAttributeQuiet: true,+ onSetElementsAttributeQuiet: true,onRevertElementAttributeLive: true,onBlockedEditAttempt: true,onLinkEdit: true,diff --git a/packages/studio/src/hooks/appHotkeysDispatch.ts b/packages/studio/src/hooks/appHotkeysDispatch.tsindex 35c82f6ef2..f7dae35234 100644--- a/packages/studio/src/hooks/appHotkeysDispatch.ts+++ b/packages/studio/src/hooks/appHotkeysDispatch.ts@@ -9,6 +9,7 @@ import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";import { canSplitElement } from "../utils/timelineElementSplit";import { trackStudioEvent } from "../utils/studioTelemetry";import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";+import { openAudioGainDialog } from "../player/components/audioGainDialogStore";import type { LinkShortcutCallbacks } from "./linkShortcuts";// Extracted from useAppHotkeys.ts to keep it under the studio 600-line cap,@@ -190,6 +191,14 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa}}+ // Only with a sound clip selected, so bare G still reaches the canvas grid toggle otherwise.+ if (key === STUDIO_PLAIN_KEYS.audioGain && !event.shiftKey && !event.altKey) {+ if (!cb.readOnlyPreview && openAudioGainDialog()) {+ event.preventDefault();+ return;+ }+ }+if (key === "b" && !event.shiftKey && !event.altKey) {event.preventDefault();const { activeTool, setActiveTool } = usePlayerStore.getState();diff --git a/packages/studio/src/hooks/timelineElementsAttribute.test.ts b/packages/studio/src/hooks/timelineElementsAttribute.test.tsnew file mode 100644index 0000000000..781dd10566--- /dev/null+++ b/packages/studio/src/hooks/timelineElementsAttribute.test.ts@@ -0,0 +1,95 @@+// @vitest-environment happy-dom+import { act, createElement } from "react";+import { createRoot } from "react-dom/client";+import { describe, expect, it, vi } from "vitest";++Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", { configurable: true, value: true });+import type { TimelineElement } from "../player";++const saved = vi.hoisted(() => ({ inputs: [] as Array<Record<string, unknown>> }));+vi.mock("../utils/studioFileHistory", () => ({+ saveProjectFilesWithHistory: vi.fn(async (input: Record<string, unknown>) => {+ saved.inputs.push(input);+ return [];+ }),+}));++import { useSetElementsAttribute } from "./timelineElementsAttribute";++const clip = (id: string, sourceFile?: string): TimelineElement => ({+ id,+ domId: id,+ tag: "audio",+ start: 0,+ duration: 1,+ track: 0,+ sourceFile,+});++describe("useSetElementsAttribute", () => {+ it("writes every clip's attribute in one history entry, one builder per file", async () => {+ const showToast = vi.fn();+ let write: ReturnType<typeof useSetElementsAttribute> | null = null;+ function Probe() {+ write = useSetElementsAttribute({+ projectIdRef: { current: "p1" },+ activeCompPath: "index.html",+ showToast,+ writeProjectFile: vi.fn(async () => {}),+ recordEdit: vi.fn(async () => {}),+ previewIframeRef: { current: null },+ pendingTimelineEditPathRef: { current: new Set<string>() },+ });+ return null;+ }+ const root = createRoot(document.createElement("div"));+ act(() => root.render(createElement(Probe)));+ await write?.(+ [+ { element: clip("a"), value: "0.5" },+ { element: clip("b"), value: "2" },+ { element: clip("c", "scene.html"), value: "1.5" },+ ],+ "data-volume",+ "Audio Gain",+ );+ act(() => root.unmount());+ expect(showToast).not.toHaveBeenCalled();+ expect(saved.inputs).toHaveLength(1);+ const input = saved.inputs[0];+ expect(input?.["label"]).toBe("Audio Gain");+ const files = input?.["files"];+ if (typeof files !== "object" || files === null) throw new Error("no files");+ expect(Object.keys(files).sort()).toEqual(["index.html", "scene.html"]);+ const build = Reflect.get(files, "index.html");+ const html = '<audio id="a" data-volume="1"></audio><audio id="b"></audio>';+ const out = typeof build === "function" ? String(build(html)) : "";+ expect(out).toContain('id="a" data-volume="0.5"');+ expect(out).toMatch(/id="b"[^>]*data-volume="2"/);+ });++ it("refuses while recording, like the single-clip write", async () => {+ saved.inputs.length = 0;+ const showToast = vi.fn();+ let write: ReturnType<typeof useSetElementsAttribute> | null = null;+ function Probe() {+ write = useSetElementsAttribute({+ projectIdRef: { current: "p1" },+ activeCompPath: "index.html",+ showToast,+ writeProjectFile: vi.fn(async () => {}),+ recordEdit: vi.fn(async () => {}),+ previewIframeRef: { current: null },+ pendingTimelineEditPathRef: { current: new Set<string>() },+ isRecordingRef: { current: true },+ });+ return null;+ }+ const root = createRoot(document.createElement("div"));+ act(() => root.render(createElement(Probe)));+ await write?.([{ element: clip("a"), value: "0.5" }], "data-volume", "Audio Gain");+ act(() => root.unmount());+ expect(saved.inputs).toHaveLength(0);+ expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error");+ });+});diff --git a/packages/studio/src/hooks/timelineElementsAttribute.ts b/packages/studio/src/hooks/timelineElementsAttribute.tsnew file mode 100644index 0000000000..9254339ce9--- /dev/null+++ b/packages/studio/src/hooks/timelineElementsAttribute.ts@@ -0,0 +1,113 @@+import { useCallback } from "react";+import type { TimelineEditCallbacks } from "../player/components/timelineCallbacks";+import { syncStoredElementAttribute } from "../player/lib/automationStoreSync";+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";+import { applyPatchByTarget } from "../utils/sourcePatcher";+import {+ buildPatchTarget,+ findTimelineElementInIframe,+ readFileContent,+} from "./timelineEditingHelpers";+import type { UseTimelineElementVisibilityEditingInput } from "./timelineTrackVisibility";+import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";++type ElementAttributeEdits = Parameters<+ NonNullable<TimelineEditCallbacks["onSetElementsAttributeQuiet"]>+>[0];++type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;++function editsByFile(+ edits: ElementAttributeEdits,+ activeCompPath: string | null,+): Map<string, Array<{ target: PatchTarget; value: string | null }>> {+ const byFile = new Map<string, Array<{ target: PatchTarget; value: string | null }>>();+ for (const { element, value } of edits) {+ const target = buildPatchTarget(element);+ if (!target) throw new Error("A clip has no id to save it by");+ const path = element.sourceFile || activeCompPath || "index.html";+ byFile.set(path, [...(byFile.get(path) ?? []), { target, value }]);+ }+ return byFile;+}++function patchLive(+ iframe: HTMLIFrameElement | null,+ edits: ElementAttributeEdits,+ attr: string,+ activeCompPath: string | null,+): void {+ for (const { element, value } of edits) {+ const node = findTimelineElementInIframe(iframe, element, activeCompPath);+ if (value === null) node?.removeAttribute(attr);+ else node?.setAttribute(attr, value);+ syncStoredElementAttribute(element, attr, value);+ }+}++/** One attribute written on several clips as a single save and a single undo step. */+export function useSetElementsAttribute({+ projectIdRef,+ activeCompPath,+ showToast,+ writeProjectFile,+ recordEdit,+ previewIframeRef,+ pendingTimelineEditPathRef,+ isRecordingRef,+}: UseTimelineElementVisibilityEditingInput) {+ return useCallback(+ async (+ edits: ElementAttributeEdits,+ attr: string,+ label: string,+ ): Promise<TimelineEditOutcome> => {+ const projectId = projectForTimelineSave(+ isRecordingRef?.current,+ projectIdRef.current,+ showToast,+ );+ if (typeof projectId !== "string") return projectId;+ if (edits.length === 0) return { status: "saved" };+ try {+ const byFile = editsByFile(edits, activeCompPath);+ const files = Object.fromEntries(+ [...byFile].map(([path, patches]) => [+ path,+ (before: string) =>+ patches.reduce(+ (html, { target, value }) =>+ applyPatchByTarget(html, target, { type: "attribute", property: attr, value }),+ before,+ ),+ ]),+ );+ for (const path of byFile.keys()) pendingTimelineEditPathRef.current.add(path);+ await saveProjectFilesWithHistory({+ projectId,+ label,+ files,+ readFile: (path) => readFileContent(projectId, path),+ writeFile: writeProjectFile,+ recordEdit,+ });+ patchLive(previewIframeRef.current, edits, attr, activeCompPath);+ return { status: "saved" };+ } catch (error) {+ const reason = error instanceof Error ? error.message : "Could not save the clips";+ showToast(reason, "error");+ return { status: "failed", reason };+ }+ },+ [+ projectIdRef,+ activeCompPath,+ showToast,+ writeProjectFile,+ recordEdit,+ previewIframeRef,+ pendingTimelineEditPathRef,+ isRecordingRef,+ ],+ );+}diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts b/packages/studio/src/hooks/timelineLinkEditPlan.test.tsindex 5c95035193..644e7e89ad 100644--- a/packages/studio/src/hooks/timelineLinkEditPlan.test.ts+++ b/packages/studio/src/hooks/timelineLinkEditPlan.test.ts@@ -1,6 +1,7 @@// @vitest-environment happy-domimport { describe, expect, it } from "vitest";import type { TimelineElement } from "../player";+import { clipSyncState } from "../player/components/clipSync";import { clipsToUnlink, planLinkEdit } from "./timelineLinkEditPlan";const clip = (id: string, tag: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({@@ -111,3 +112,30 @@ describe("planLinkEdit into sync", () => {expect(html).toBe('<audio id="talk-audio" data-playback-start="0.5"></audio>');});});++describe("link edit plan", () => {+ const PAIR =+ '<div><video id="talk" src="talk.mp4" muted data-start="2" data-duration="6"></video><audio id="a" src="%SRC%" data-start="3" data-duration="3" data-media-start="1"></audio></div>';+ const linkPlan = (src: string, audioEl: TimelineElement) => {+ const v = clip("talk", "video", { muted: true });+ const plan = planLinkEdit({ kind: "link", elements: [v, audioEl] }, [v, audioEl]);+ return plan?.transform(PAIR.replace("%SRC%", src)) ?? "";+ };++ it("links a trimmed same-file audio with a sync origin that shows a nonzero offset", () => {+ const trimmed = clip("a", "audio", { start: 3, duration: 3, playbackStart: 0 });+ const out = linkPlan("talk.mp4", trimmed);+ expect(out).toMatch(/<video[^>]*data-link="lk-1"[^>]*data-sync-origin="lk-1"/);+ expect(out).toMatch(/<audio[^>]*data-link="lk-1"[^>]*data-sync-origin="lk-1"/);+ const v = clip("talk", "video", { muted: true, syncOrigin: "lk-1" });+ const a = { ...trimmed, syncOrigin: "lk-1" };+ expect(clipSyncState(a, [v, a], 30)?.frames).toBe(30);+ });++ it("links different files without a sync origin", () => {+ const music = clip("a", "audio", { src: "bgm.mp3" });+ const out = linkPlan("bgm.mp3", music);+ expect(out).toContain('data-link="lk-1"');+ expect(out).not.toContain("data-sync-origin");+ });+});diff --git a/packages/studio/src/hooks/timelineLinkEditPlan.ts b/packages/studio/src/hooks/timelineLinkEditPlan.tsindex c3d6bce414..56f293c816 100644--- a/packages/studio/src/hooks/timelineLinkEditPlan.ts+++ b/packages/studio/src/hooks/timelineLinkEditPlan.ts@@ -13,6 +13,7 @@ import {mergeAudioInSource,pickDetachedAudioTrack,setLinkInSource,+ sharesSourceFile,} from "../components/editor/mediaLinkEdits";export interface LinkEditPlan {@@ -92,7 +93,11 @@ export function planLinkEdit(const targets = targetsOf(edit.elements);const anchor = edit.elements[0];if (!targets || !anchor) return null;- return { label: "Link clips", anchor, transform: (s) => linkInSource(s, targets) };+ return {+ label: "Link clips",+ anchor,+ transform: (s) => linkInSource(s, targets, { syncOrigin: sharesSourceFile(edit.elements) }),+ };}case "detach": {const target = buildPatchTarget(edit.element);diff --git a/packages/studio/src/hooks/useAppHotkeys.test.ts b/packages/studio/src/hooks/useAppHotkeys.test.tsindex f02e3e0551..2d3a850470 100644--- a/packages/studio/src/hooks/useAppHotkeys.test.ts+++ b/packages/studio/src/hooks/useAppHotkeys.test.ts@@ -6,6 +6,7 @@ import type { DomEditSelection } from "../components/editor/domEditing";import { clearAutomationClipboard, copyRange } from "../player/components/automationClipboard";import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";import type { TimelineElement } from "../player/store/timelineElement";+import { useAudioGainDialogStore } from "../player/components/audioGainDialogStore";/** Minimal valid fixture — TimelineElement only requires these five fields. */const bgmElement: TimelineElement = {@@ -474,3 +475,36 @@ describe("hotkeys with the preview read-only", () => {expect(cb.handleDomEditElementDelete).toHaveBeenCalledTimes(1);});});++describe("dispatchPlainKey — G opens Audio Gain", () => {+ const video: TimelineElement = {+ id: "b-roll",+ key: "b-roll",+ tag: "video",+ start: 0,+ duration: 4,+ track: 1,+ };++ afterEach(() => useAudioGainDialogStore.getState().close());++ it("opens the dialog for the selected clips with sound and owns the key", () => {+ usePlayerStore.setState({+ elements: [bgmElement, video],+ selectedElementId: "bgm",+ selectedElementIds: new Set(["bgm", "b-roll"]),+ });+ const event = press("g");+ dispatchPlainKey(event, "g", callbacks());+ expect(useAudioGainDialogStore.getState().targetKeys).toEqual(["bgm"]);+ expect(event.defaultPrevented).toBe(true);+ });++ it("leaves G to the grid toggle when nothing selected has sound", () => {+ usePlayerStore.setState({ elements: [video], selectedElementId: "b-roll" });+ const event = press("g");+ dispatchPlainKey(event, "g", callbacks());+ expect(useAudioGainDialogStore.getState().targetKeys).toBeNull();+ expect(event.defaultPrevented).toBe(false);+ });+});diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.tsindex 87d4d7a657..b677c531a4 100644--- a/packages/studio/src/hooks/useRenderClipContent.ts+++ b/packages/studio/src/hooks/useRenderClipContent.ts@@ -14,6 +14,7 @@ import { AudioWaveform, rendersWaveform } from "../player/components/AudioWavefoimport { ImageThumbnail } from "../player/components/ImageThumbnail";import { AudibleVideoClipContent } from "../player/components/AudibleVideoClipContent";import { ClipPeakMarks } from "../player/components/ClipPeakMarks";+import { clipPeaksUrl, clipSourceWindow } from "../player/components/clipPeakMap";import { clipHasSound } from "../player/components/clipMenuNormalize";import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";import { usePlayerStore } from "../player/store/playerStore";@@ -91,11 +92,8 @@ function renderAudioClip(return createElement(ClipPeakMarks,{- peaksUrl: encodedRelative ? buildProjectApiPath(pid, `/peaks/${encodedRelative}`) : undefined,- sourceWindow: {- mediaStart: el.playbackStart ?? 0,- sourceSpan: el.duration * (el.playbackRate ?? 1),- },+ peaksUrl: clipPeaksUrl(el.src, pid),+ sourceWindow: clipSourceWindow(el),gain: el.volume ?? 1,},waveform,diff --git a/packages/studio/src/hooks/useTimelineEditing.ts b/packages/studio/src/hooks/useTimelineEditing.tsindex c4103daad8..3471a11e3d 100644--- a/packages/studio/src/hooks/useTimelineEditing.ts+++ b/packages/studio/src/hooks/useTimelineEditing.ts@@ -26,6 +26,7 @@ import {import type { PersistTimelineEditInput } from "./timelineEditingHelpers";import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";import { useSetElementAttribute } from "./timelineElementFxAttribute";+import { useSetElementsAttribute } from "./timelineElementsAttribute";import { useTimelineDeleteOps } from "./useTimelineDeleteOps";import { useTimelineEditGuard } from "./useTimelineEditGuard";import {@@ -409,6 +410,17 @@ export function useTimelineEditing({isRecordingRef,});+ const setElementsAttribute = useSetElementsAttribute({+ projectIdRef,+ activeCompPath,+ showToast,+ writeProjectFile,+ recordEdit,+ previewIframeRef,+ pendingTimelineEditPathRef,+ isRecordingRef,+ });+const setAudioGroupAttribute = useSetAudioGroupAttribute({projectIdRef,activeCompPath,@@ -532,6 +544,7 @@ export function useTimelineEditing({},setElementFxAttribute: {...setElementFxAttribute,+ setMany: track(guard((edits) => edits.map((edit) => edit.element), setElementsAttribute)),setQuiet: track(guard((element) => [element],diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsxindex de7d0cd473..8cc1398e0f 100644--- a/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx+++ b/packages/studio/src/hooks/useTimelineLinkEditing.test.tsx@@ -109,4 +109,16 @@ describe("useTimelineLinkEditing", () => {expect(recordEdit.mock.calls[0]?.[0].label).toBe("Unlink clips");unmount();});++ it("unlink leaves nothing selected, so a later trim moves only the grabbed clip", async () => {+ vi.spyOn(globalThis, "fetch").mockResolvedValue(+ new Response(JSON.stringify({ content: SOURCE }), { status: 200 }),+ );+ const { api, unmount } = await renderLinkEditing();+ usePlayerStore.getState().setSelection(["talk", "talk-audio"], "talk");+ await act(async () => api.handleLinkEdit({ kind: "unlink", elements: [video, audio] }));+ expect(usePlayerStore.getState().selectedElementIds.size).toBe(0);+ expect(usePlayerStore.getState().selectedElementId).toBeNull();+ unmount();+ });});diff --git a/packages/studio/src/hooks/useTimelineLinkEditing.ts b/packages/studio/src/hooks/useTimelineLinkEditing.tsindex 6423e3acee..df5377030b 100644--- a/packages/studio/src/hooks/useTimelineLinkEditing.ts+++ b/packages/studio/src/hooks/useTimelineLinkEditing.ts@@ -49,6 +49,10 @@ export function withLinkPartners(selection: readonly TimelineElement[]): Timelinreturn [...selection, ...elements.filter((el) => keys.has(keyOf(el)) && !known.has(keyOf(el)))];}+function clearSelectionOnUnlink(edit: TimelineLinkEdit): void {+ if (edit.kind === "unlink") usePlayerStore.getState().clearSelection();+}+export function useTimelineLinkEditing({projectIdRef,activeCompPath,@@ -71,6 +75,7 @@ export function useTimelineLinkEditing({const pid = projectIdRef.current;const plan = planLinkEdit(edit, usePlayerStore.getState().elements);if (!pid || !plan) return;+ clearSelectionOnUnlink(edit);const path = plan.anchor.sourceFile || activeCompPath || "index.html";pendingTimelineEditPathRef.current.add(path);const queued = editQueueRef.current.then(() =>diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.tsindex b891063737..da6e19ce2a 100644--- a/packages/studio/src/index.ts+++ b/packages/studio/src/index.ts@@ -32,6 +32,10 @@ export {formatTime,} from "./player";export { usePreviewIframeStore } from "./player/store/previewIframeStore";+export {+ openAudioGainDialog,+ useAudioGainDialogStore,+} from "./player/components/audioGainDialogStore";export type {PlayerHandle,PlayerHandleElement,diff --git a/packages/studio/src/player/components/AudioGainDialog.test.tsx b/packages/studio/src/player/components/AudioGainDialog.test.tsxnew file mode 100644index 0000000000..c70e8214db--- /dev/null+++ b/packages/studio/src/player/components/AudioGainDialog.test.tsx@@ -0,0 +1,133 @@+// @vitest-environment happy-dom+import { act } from "react";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { audioGainToDb } from "@hyperframes/core/audio-gain";+import { createHappyDomRootHarness } from "./testRootHarness";+import { AudioGainDialog } from "./AudioGainDialog";+import { usePlayerStore } from "../store/playerStore";+import type { TimelineElement } from "../store/timelineElement";++const onNotice = vi.fn();+const setQuiet = vi.fn(async () => {});+const setMany = vi.fn(+ async (_edits: ReadonlyArray<{ value: string | null }>, _attr: string, _label: string) => {},+);++vi.mock("../../contexts/StudioContext", () => ({+ useStudioShellContextOptional: () => null,+}));+vi.mock("../../contexts/TimelineEditContext", () => ({+ useTimelineEditContextOptional: () => ({+ onSetElementAttributeQuiet: setQuiet,+ onSetElementsAttributeQuiet: setMany,+ onNotice,+ }),+}));++const harness = createHappyDomRootHarness();+const clip = (id: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({+ id,+ tag: "audio",+ start: 0,+ duration: 2,+ track: 0,+ src: `${id}.wav`,+ ...extra,+});++function stubPeaks(peaks: Record<string, number[]>) {+ vi.stubGlobal(+ "fetch",+ vi.fn(async (url: string) => {+ const name = Object.keys(peaks).find((key) => String(url).includes(`/peaks/${key}.wav`));+ return name+ ? Response.json({ binSeconds: 1, bins: peaks[name] })+ : new Response("", { status: 404 });+ }),+ );+}++function open(elements: TimelineElement[]) {+ const host = document.createElement("div");+ document.body.appendChild(host);+ act(() => harness.mount(host).render(<AudioGainDialog elements={elements} onClose={() => {}} />));+}++const row = (text: string) =>+ [...document.querySelectorAll("label")].find((label) => label.textContent?.startsWith(text));+const choose = (text: string) =>+ act(() => row(text)?.querySelector<HTMLInputElement>("input[type=radio]")?.click());+function typeDb(text: string, value: string) {+ const input = row(text)?.querySelector<HTMLInputElement>("input[type=number]");+ if (!input) throw new Error(`no field for ${text}`);+ const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;+ act(() => {+ setter?.call(input, value);+ input.dispatchEvent(new Event("input", { bubbles: true }));+ });+}+const ok = () => [...document.querySelectorAll("button")].find((b) => b.textContent === "OK");+const peakText = () => document.querySelector("[data-testid='audio-gain-peak']")?.textContent;++beforeEach(() => {+ usePlayerStore.getState().beginTimelineSession("p1");+ vi.clearAllMocks();+});+afterEach(() => vi.unstubAllGlobals());++describe("AudioGainDialog", () => {+ it("shows the selection's peak amplitude at the clips' current gain", async () => {+ stubPeaks({ pk1: [0.25, 0.5] });+ open([clip("pk1", { volume: 2 })]);+ await vi.waitFor(() => expect(peakText()).toBe("Peak Amplitude: 0.0 dB"));+ });++ it("Set Gain writes every selected clip in one undo step", async () => {+ stubPeaks({});+ const a = clip("set-a");+ const b = clip("set-b", { volume: 0.5 });+ open([a, b]);+ choose("Set Gain to");+ typeDb("Set Gain to", "-6");+ await act(async () => ok()?.click());+ expect(setMany).toHaveBeenCalledTimes(1);+ const [edits, attr, label] = setMany.mock.calls[0] ?? [];+ expect(attr).toBe("data-volume");+ expect(label).toBe("Audio Gain");+ expect(edits?.map((e) => audioGainToDb(Number(e.value)))).toEqual([+ expect.closeTo(-6, 3),+ expect.closeTo(-6, 3),+ ]);+ expect(setQuiet).not.toHaveBeenCalled();+ });++ it("Normalize All Peaks brings each clip's own peak to the target", async () => {+ stubPeaks({ na1: [0.5], na2: [0.25] });+ open([clip("na1"), clip("na2")]);+ await vi.waitFor(() => expect(peakText()).not.toContain("measuring"));+ choose("Normalize All Peaks to");+ typeDb("Normalize All Peaks to", "-3");+ await act(async () => ok()?.click());+ const [edits] = setMany.mock.calls[0] ?? [];+ const gains = edits?.map((e) => Number(e.value)) ?? [];+ expect(audioGainToDb(0.5 * (gains[0] ?? 0))).toBeCloseTo(-3, 3);+ expect(audioGainToDb(0.25 * (gains[1] ?? 0))).toBeCloseTo(-3, 3);+ });++ it("refuses a peak target above 0 dB", async () => {+ stubPeaks({ over: [0.5] });+ open([clip("over")]);+ await vi.waitFor(() => expect(peakText()).not.toContain("measuring"));+ choose("Normalize Max Peak to");+ typeDb("Normalize Max Peak to", "2");+ expect(ok()?.disabled).toBe(true);+ });++ it("disables the peak options when the clip cannot be measured", async () => {+ stubPeaks({});+ open([clip("unmeasured")]);+ await vi.waitFor(() => expect(peakText()).toBe("Peak Amplitude: —"));+ expect(row("Normalize Max Peak to")?.querySelector("input")?.disabled).toBe(true);+ expect(row("Adjust Gain by")?.querySelector("input")?.disabled).toBe(false);+ });+});diff --git a/packages/studio/src/player/components/AudioGainDialog.tsx b/packages/studio/src/player/components/AudioGainDialog.tsxnew file mode 100644index 0000000000..3dceed07de--- /dev/null+++ b/packages/studio/src/player/components/AudioGainDialog.tsx@@ -0,0 +1,226 @@+import { useEffect, useMemo, useState, type ReactNode } from "react";+import { createPortal } from "react-dom";+import { audioGainToDb } from "@hyperframes/core/audio-gain";+import type { TimelineElement } from "../store/timelineElement";+import { usePlayerStore } from "../store/playerStore";+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";+import { useStudioShellContextOptional } from "../../contexts/StudioContext";+import { measureClipSourcePeak } from "./clipPeakMap";+import { AUDIO_GAIN_LABEL, normalizeClipsLoudness, writeClipGains } from "./audioGainApply";+import { useAudioGainDialogStore } from "./audioGainDialogStore";+import {+ peakAmplitudeDb,+ planAudioGain,+ type AudioGainClip,+ type AudioGainMode,+} from "./audioGainPlan";++type DialogMode = AudioGainMode | "loudness";++const PEAK_MODES: ReadonlySet<DialogMode> = new Set(["normalize-max", "normalize-all"]);++const ROWS: ReadonlyArray<{ mode: AudioGainMode; label: string }> = [+ { mode: "set", label: "Set Gain to" },+ { mode: "adjust", label: "Adjust Gain by" },+ { mode: "normalize-max", label: "Normalize Max Peak to" },+ { mode: "normalize-all", label: "Normalize All Peaks to" },+];++const keyOf = (el: TimelineElement) => el.key ?? el.id;+const currentGainDb = (el: TimelineElement | undefined) => {+ const gain = el?.volume ?? 1;+ return gain > 0 ? Math.round(audioGainToDb(gain) * 10) / 10 : -60;+};+const dbText = (db: number) => `${db < 0 ? "−" : ""}${Math.abs(db).toFixed(1)} dB`;++function useSourcePeaks(elements: readonly TimelineElement[], projectId: string | null) {+ const [peaks, setPeaks] = useState<Map<string, number | null> | null>(null);+ useEffect(() => {+ if (!projectId) return;+ let live = true;+ void Promise.all(elements.map((el) => measureClipSourcePeak(el, projectId))).then((found) => {+ if (live) setPeaks(new Map(elements.map((el, i) => [keyOf(el), found[i] ?? null])));+ });+ return () => {+ live = false;+ };+ }, [elements, projectId]);+ return peaks;+}++function Row({+ checked,+ disabled,+ label,+ onSelect,+ children,+}: {+ checked: boolean;+ disabled?: boolean;+ label: string;+ onSelect: () => void;+ children?: ReactNode;+}) {+ return (+ <label+ className={`flex items-center justify-between gap-3 py-1 ${disabled ? "opacity-40" : ""}`}+ >+ <span className="flex items-center gap-2">+ <input+ type="radio"+ name="audio-gain-mode"+ checked={checked}+ disabled={disabled}+ onChange={onSelect}+ />+ {label}+ </span>+ {children}+ </label>+ );+}++/** Premiere's Audio Gain dialog for the clips the store names. */+export function AudioGainDialog({+ elements,+ onClose,+}: {+ elements: readonly TimelineElement[];+ onClose: () => void;+}) {+ const shell = useStudioShellContextOptional();+ const edit = useTimelineEditContextOptional();+ const sessionProjectId = usePlayerStore((s) => s.timelineProjectId);+ const projectId = shell?.projectId ?? sessionProjectId;+ const showToast = shell?.showToast ?? edit.onNotice;+ const peaks = useSourcePeaks(elements, projectId);+ const [mode, setMode] = useState<DialogMode>("adjust");+ const [values, setValues] = useState<Record<AudioGainMode, number>>(() => ({+ set: currentGainDb(elements[0]),+ adjust: 0,+ "normalize-max": 0,+ "normalize-all": 0,+ }));+ const clips: AudioGainClip[] = elements.map((el) => ({+ key: keyOf(el),+ gain: el.volume ?? 1,+ sourcePeak: peaks?.get(keyOf(el)) ?? null,+ }));+ const peakDb = peakAmplitudeDb(clips);+ const outOfRange = PEAK_MODES.has(mode) && mode !== "loudness" && values[mode] > 0;+ const canApply = !outOfRange && !(PEAK_MODES.has(mode) && peakDb === null);++ const apply = async () => {+ if (!canApply) return;+ onClose();+ try {+ if (mode === "loudness") {+ if (!projectId) return;+ showToast?.(await normalizeClipsLoudness(projectId, elements, edit), "info");+ return;+ }+ const byKey = new Map(elements.map((el) => [keyOf(el), el]));+ const plan = planAudioGain(clips, { mode, db: values[mode] });+ const edits = plan.flatMap(({ key, gain }) => {+ const element = byKey.get(key);+ return element ? [{ element, gain }] : [];+ });+ await writeClipGains(edits, edit, AUDIO_GAIN_LABEL);+ } catch (error) {+ showToast?.(error instanceof Error ? error.message : String(error), "error");+ }+ };++ const field = (rowMode: AudioGainMode) => (+ <span className="flex items-center gap-1">+ <input+ type="number"+ step={0.1}+ max={PEAK_MODES.has(rowMode) ? 0 : undefined}+ aria-label={`${ROWS.find((row) => row.mode === rowMode)?.label ?? ""} dB`}+ value={values[rowMode]}+ disabled={mode !== rowMode}+ className="w-16 rounded border border-neutral-700 bg-neutral-950 px-1 text-right disabled:opacity-50"+ onChange={(event) =>+ setValues((prev) => ({ ...prev, [rowMode]: Number(event.target.value) || 0 }))+ }+ />+ dB+ </span>+ );++ return createPortal(+ <div+ className="fixed inset-0 z-[300] flex items-center justify-center bg-black/50"+ onPointerDown={(event) => event.target === event.currentTarget && onClose()}+ >+ <div+ role="dialog"+ aria-modal="true"+ aria-label={AUDIO_GAIN_LABEL}+ className="w-[340px] rounded-md border border-neutral-700 bg-neutral-900 p-4 text-xs text-neutral-200 shadow-xl"+ onKeyDown={(event) => {+ event.stopPropagation();+ if (event.key === "Escape") onClose();+ if (event.key !== "Enter") return;+ event.preventDefault();+ void apply();+ }}+ >+ <div className="mb-3 text-sm font-medium">{AUDIO_GAIN_LABEL}</div>+ {ROWS.map((row) => (+ <Row+ key={row.mode}+ label={row.label}+ checked={mode === row.mode}+ disabled={PEAK_MODES.has(row.mode) && peaks !== null && peakDb === null}+ onSelect={() => setMode(row.mode)}+ >+ {field(row.mode)}+ </Row>+ ))}+ <Row+ label="Normalize loudness to −16 LUFS"+ checked={mode === "loudness"}+ onSelect={() => setMode("loudness")}+ />+ <div className="mt-3 text-neutral-400" data-testid="audio-gain-peak">+ Peak Amplitude: {peaks === null ? "measuring…" : peakDb === null ? "—" : dbText(peakDb)}+ </div>+ {outOfRange && <div className="mt-1 text-red-400">Peak targets must be 0 dB or lower.</div>}+ <div className="mt-4 flex justify-end gap-2">+ <button+ type="button"+ className="rounded px-3 py-1 text-neutral-300 hover:bg-neutral-800"+ onClick={onClose}+ >+ Cancel+ </button>+ <button+ type="button"+ disabled={!canApply}+ autoFocus+ className="rounded bg-blue-500 px-3 py-1 text-white disabled:opacity-40"+ onClick={() => void apply()}+ >+ OK+ </button>+ </div>+ </div>+ </div>,+ document.body,+ );+}++/** Mounted in the timeline's overlays so Studio and embedders that mount the Timeline both get it. */+export function TimelineAudioGainOverlay() {+ const targetKeys = useAudioGainDialogStore((s) => s.targetKeys);+ const close = useAudioGainDialogStore((s) => s.close);+ const elements = usePlayerStore((s) => s.elements);+ const targets = useMemo(() => {+ const wanted = new Set(targetKeys ?? []);+ return elements.filter((el) => wanted.has(keyOf(el)));+ }, [elements, targetKeys]);+ if (!targetKeys || targets.length === 0) return null;+ return <AudioGainDialog key={targetKeys.join("\n")} elements={targets} onClose={close} />;+}diff --git a/packages/studio/src/player/components/ClipBadges.test.tsx b/packages/studio/src/player/components/ClipBadges.test.tsxindex e03e8c6617..57a53fc813 100644--- a/packages/studio/src/player/components/ClipBadges.test.tsx+++ b/packages/studio/src/player/components/ClipBadges.test.tsx@@ -2,7 +2,7 @@import { act } from "react";import { createRoot, type Root } from "react-dom/client";-import { afterEach, describe, expect, it } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import type { TimelineElement } from "../store/playerStore";import { usePreviewIframeStore } from "../store/previewIframeStore";import { ClipBadges } from "./ClipBadges";@@ -54,29 +54,53 @@ function mountPreview(html: string): Document {}describe("ClipBadges", () => {- it("renders nothing for an untouched clip", () => {+ it("shows a grey fx badge and no volume on an untouched clip", () => {render(talk);- expect(document.querySelector("[data-testid='clip-badges']")).toBeNull();+ expect(labels()).toEqual(["fx:fx"]);+ const fx = document.querySelector("[data-badge='fx']");+ expect(fx?.getAttribute("data-fx-active")).toBe("false");+ expect(fx?.getAttribute("title")).toBe("No effects");});it("falls back to the store's volume without a preview", () => {render({ ...talk, volume: 1.8 });- expect(labels()).toEqual(["volume:180%"]);+ expect(labels()).toEqual(["volume:180%", "fx:fx"]);});- it("reads the live node and follows an agent's attribute edit", async () => {+ it("lights the fx badge from the live node, lists the effects, and shows no link badge", async () => {const doc = mountPreview(`<video id="talk" data-has-audio="true" data-link="talk-pair" style="clip-path: inset(10px)"></video>`,);render(talk);- expect(labels()).toEqual(["link:🔗", "crop:Crop"]);+ const fx = () => document.querySelector("[data-badge='fx']");+ expect(labels()).toEqual(["fx:fx"]);+ expect(fx()?.getAttribute("data-fx-active")).toBe("true");+ expect(fx()?.getAttribute("title")).toBe("Crop");const node = doc.getElementById("talk");await act(async () => {node?.setAttribute("data-color-grading", '{"preset":"warm-daylight","intensity":1}');node?.setAttribute("data-volume", "0.6");await new Promise((resolve) => setTimeout(resolve, 0));});- expect(labels()).toEqual(["link:🔗", "look:Warm daylight", "crop:Crop", "more:+1"]);- expect(document.querySelector("[data-badge='more']")?.getAttribute("title")).toBe("60%");+ expect(labels()).toEqual(["volume:60%", "fx:fx"]);+ expect(fx()?.getAttribute("title")).toBe("Look: Warm daylight · Crop");+ });++ it("opens the clip menu from the fx badge without reaching the clip", () => {+ const host = document.createElement("div");+ document.body.append(host);+ const onOpenMenu = vi.fn();+ const onClipClick = vi.fn();+ root = createRoot(host);+ act(() =>+ root?.render(+ <div onClick={onClipClick}>+ <ClipBadges el={talk} onOpenMenu={onOpenMenu} />+ </div>,+ ),+ );+ act(() => document.querySelector<HTMLElement>("[data-badge='fx']")?.click());+ expect(onOpenMenu).toHaveBeenCalledTimes(1);+ expect(onClipClick).not.toHaveBeenCalled();});});diff --git a/packages/studio/src/player/components/ClipBadges.tsx b/packages/studio/src/player/components/ClipBadges.tsxindex 9792ae8039..3e3c514b9a 100644--- a/packages/studio/src/player/components/ClipBadges.tsx+++ b/packages/studio/src/player/components/ClipBadges.tsx@@ -1,6 +1,6 @@-import { memo } from "react";+import { memo, type MouseEvent } from "react";import type { TimelineElement } from "../store/playerStore";-import { readClipBadges, splitVisibleBadges, type ClipBadge } from "./clipToolAttrs";+import { clipVolumeBadge, readClipEffects } from "./clipToolAttrs";import { useClipToolState } from "./useClipToolState";function SpeakerGlyph({ muted }: { muted: boolean }) {@@ -21,47 +21,53 @@ function SpeakerGlyph({ muted }: { muted: boolean }) {);}-function BadgeContent({ badge }: { badge: ClipBadge }) {- if (badge.kind === "link") return <span aria-hidden="true">🔗</span>;- if (badge.kind === "volume") {- const muted = badge.label === "Muted";- return (- <>- <SpeakerGlyph muted={muted} />- {muted ? null : <span>{badge.label}</span>}- </>- );- }- return <span>{badge.label}</span>;-}-const BADGE_CLASS =- "inline-flex items-center gap-0.5 rounded-[3px] border border-white/20 bg-black/55 px-1 text-[9px] leading-[14px] text-white/90 whitespace-nowrap";+ "timeline-clip__badge inline-flex items-center gap-0.5 rounded-[3px] border bg-black/55 px-1 text-[9px] leading-[14px] whitespace-nowrap";+const FX_ON = "border-white/40 text-white font-semibold";+const FX_OFF = "border-white/10 text-white/35";-/** What is applied to a clip, read from its attributes: a link badge, then at most two more and `+N`. */-export const ClipBadges = memo(function ClipBadges({ el }: { el: TimelineElement }) {+/** Premiere's fx badge — grey with no effects, white with any; hover lists them, click opens the clip menu. */+export const ClipBadges = memo(function ClipBadges({+ el,+ onOpenMenu,+}: {+ el: TimelineElement;+ onOpenMenu?: (event: MouseEvent) => void;+}) {const state = useClipToolState(el);- const { visible, hidden } = splitVisibleBadges(readClipBadges(state));- if (visible.length === 0) return null;+ const effects = readClipEffects(state);+ const volume = clipVolumeBadge(state);+ const hasEffects = effects.length > 0;+ const openMenu = (event: MouseEvent) => {+ event.stopPropagation();+ onOpenMenu?.(event);+ };return (<spanclassName="pointer-events-none absolute right-1.5 top-0.5 z-[3] flex gap-1"data-testid="clip-badges">- {visible.map((badge) => (- <span key={badge.kind} className={BADGE_CLASS} title={badge.label} data-badge={badge.kind}>- <BadgeContent badge={badge} />- </span>- ))}- {hidden.length > 0 && (+ {volume && (<span- className={`${BADGE_CLASS} pointer-events-auto`}- title={hidden.map((badge) => badge.label).join(", ")}- data-badge="more"+ className={`${BADGE_CLASS} border-white/20 text-white/90`}+ title={volume}+ data-badge="volume">- +{hidden.length}+ <SpeakerGlyph muted={volume === "Muted"} />+ {volume === "Muted" ? null : <span>{volume}</span>}</span>)}+ <span+ className={`${BADGE_CLASS} pointer-events-auto cursor-pointer ${hasEffects ? FX_ON : FX_OFF}`}+ title={hasEffects ? effects.join(" · ") : "No effects"}+ data-badge="fx"+ data-fx-active={hasEffects ? "true" : "false"}+ onPointerDown={(event) => event.stopPropagation()}+ onClick={openMenu}+ onContextMenu={openMenu}+ >+ fx+ </span></span>);});diff --git a/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsxindex dd3f660b49..c0ac08d96e 100644--- a/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx+++ b/packages/studio/src/player/components/ClipContextMenu.groups.test.tsx@@ -84,7 +84,7 @@ describe("ClipContextMenu order", () => {const expected = ["Split at 2.00s","Freeze frame",- "Normalize loudness",+ "Audio Gain…","Voice","Detach audio","Unlink from audio",diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsxindex 438b09def5..37bddac8fa 100644--- a/packages/studio/src/player/components/ClipContextMenu.tsx+++ b/packages/studio/src/player/components/ClipContextMenu.tsx@@ -175,7 +175,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({</div><div role="group" aria-label="Sound" className={GROUP_CLASS}>- <ClipMenuAudioItems part="normalize" element={element} onClose={onClose} />+ <ClipMenuAudioItems part="gain" element={element} onClose={onClose} /><ClipMenuToolItemsgroup="sound"element={element}diff --git a/packages/studio/src/player/components/ClipPeakMarks.tsx b/packages/studio/src/player/components/ClipPeakMarks.tsxindex e8af8cc59c..064a436866 100644--- a/packages/studio/src/player/components/ClipPeakMarks.tsx+++ b/packages/studio/src/player/components/ClipPeakMarks.tsx@@ -1,18 +1,6 @@import { useEffect, useState, type ReactNode } from "react";-import { clipPeakRuns, isPeakMap, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";--const peakMapRequests = new Map<string, Promise<PeakMap | null>>();--function loadPeakMap(url: string): Promise<PeakMap | null> {- const pending = peakMapRequests.get(url);- if (pending) return pending;- const request = fetch(url)- .then((res) => (res.ok ? res.json() : null))- .then((body: unknown) => (isPeakMap(body) ? body : null))- .catch(() => null);- peakMapRequests.set(url, request);- return request;-}+import { clipPeakRuns, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";+import { loadPeakMap } from "./clipPeakMap";const dbText = (db: number) => `${db < 0 ? "−" : "+"}${Math.abs(db).toFixed(1)} dBFS`;diff --git a/packages/studio/src/player/components/TimelineClip.test.tsx b/packages/studio/src/player/components/TimelineClip.test.tsxindex 3c4786be67..8a9ebe7f8c 100644--- a/packages/studio/src/player/components/TimelineClip.test.tsx+++ b/packages/studio/src/player/components/TimelineClip.test.tsx@@ -133,6 +133,47 @@ describe("TimelineClip", () => {act(() => root.unmount());});+ it("names a speed-changed clip like Premiere: [150%] for a constant rate, [ramp] for a lane", () => {+ const fast = renderClip({+ element: {+ id: "a",+ label: "Hero",+ tag: "video",+ start: 0,+ duration: 2,+ track: 0,+ playbackRate: 1.5,+ },+ });+ expect(fast.host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero [150%]");+ act(() => fast.root.unmount());+ const automation = JSON.stringify({+ version: 1,+ lanes: [+ {+ target: "rate",+ points: [+ { t: 0, v: 0.5 },+ { t: 1, v: 1 },+ ],+ },+ ],+ });+ const ramp = renderClip({+ element: {+ id: "b",+ label: "Hero",+ tag: "video",+ start: 0,+ duration: 2,+ track: 0,+ automation,+ },+ });+ expect(ramp.host.querySelector(".timeline-clip__label")?.textContent).toBe("Hero [ramp]");+ act(() => ramp.root.unmount());+ });+it("drops the label chip under 60px even when the clip is selected", () => {const { host, root } = renderClip({element: { id: "fx", label: "FX", tag: "div", start: 0, duration: 1, track: 0 },diff --git a/packages/studio/src/player/components/TimelineClip.tsx b/packages/studio/src/player/components/TimelineClip.tsxindex 2b63755c05..c5d959c883 100644--- a/packages/studio/src/player/components/TimelineClip.tsx+++ b/packages/studio/src/player/components/TimelineClip.tsx@@ -14,6 +14,7 @@ import { rendersWaveform } from "./AudioWaveform";import { ClipBadges } from "./ClipBadges";import { linkLabelColor } from "./linkLabelColor";import { OutOfSyncBadge } from "./OutOfSyncBadge";+import { clipSpeedSuffix } from "./clipToolAttrs";interface TimelineClipProps {el: TimelineElement;@@ -68,7 +69,7 @@ export const TimelineClip = memo(function TimelineClip({const leftPx = el.start * pps;const widthPx = Math.max(el.duration * pps, 4);const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });- const displayLabel = el.label || el.id || el.tag;+ const displayLabel = `${el.label || el.id || el.tag}${clipSpeedSuffix(el.playbackRate, el.automation)}`;const ladder = clipWidthLadder(widthPx);const showHandles = handleOpacity > 0.01 && (widthPx >= 32 || isSelected);const showLabel = ladder === "labeled";@@ -210,7 +211,7 @@ export const TimelineClip = memo(function TimelineClip({</div>)}{showLabel && <span className="timeline-clip__label">{displayLabel}</span>}- {showLabel && !isGestureActor && <ClipBadges el={el} />}+ {showLabel && !isGestureActor && <ClipBadges el={el} onOpenMenu={onContextMenu} />}{!isGestureActor && el.syncOrigin && <OutOfSyncBadge el={el} />}{showDefaultText && (<span className="timeline-clip__timecode">diff --git a/packages/studio/src/player/components/TimelineLanes.test.tsx b/packages/studio/src/player/components/TimelineLanes.test.tsxindex 6b374ea93f..8a2e6834f9 100644--- a/packages/studio/src/player/components/TimelineLanes.test.tsx+++ b/packages/studio/src/player/components/TimelineLanes.test.tsx@@ -83,8 +83,14 @@ interface RenderLanesOptions {hoveredClip?: string | null;renderClipContent?: React.ComponentProps<typeof TimelineLanes>["renderClipContent"];snapGuide?: { time: number; type: "beat" | "clip-edge" | "playhead" } | null;+ withoutSelectHandler?: boolean;}+const selectHandlerFor = (+ options: RenderLanesOptions,+ handler: (element: TimelineElement | null) => void,+) => (options.withoutSelectHandler ? undefined : handler);+function renderLanes(options: RenderLanesOptions = {}): {host: HTMLDivElement;root: Root;@@ -163,7 +169,6 @@ function renderLanes(options: RenderLanesOptions = {}): {setResizingClip={vi.fn()}setDraggedClip={vi.fn()}setSelectedElementId={setSelectedElementId}- shiftClickClipRef={createRef()}getPreviewElement={(el) => el}getTrackStyle={getTrackStyle}gsapAnimations={gsapAnimations}@@ -174,7 +179,7 @@ function renderLanes(options: RenderLanesOptions = {}): {onTogglePropertyGroupKeyframe={vi.fn()}onResizeElement={vi.fn()}onMoveElement={vi.fn()}- onSelectElement={onSelectElement}+ onSelectElement={selectHandlerFor(next, onSelectElement)}onRazorSplit={vi.fn()}onRazorSplitAll={vi.fn()}/>,@@ -439,6 +444,44 @@ describe("TimelineLanes selection", () => {expect(view.onSelectElement).toHaveBeenCalledWith(selected);act(() => view.root.unmount());});++ it.each([["shiftKey"], ["metaKey"], ["ctrlKey"]])(+ "%s-click adds a clip to the selection instead of replacing it",+ (modifier) => {+ const first = element("clip-a", TRACK_A);+ const second = element("clip-b", TRACK_B);+ usePlayerStore.getState().setElements([first, second]);+ usePlayerStore.getState().setSelection([first.id], first.id);+ const view = renderLanes({ elements: [first, second] });+ const clipB = view.host.querySelector('[data-el-id="clip-b"]');+ const click = (init: MouseEventInit) =>+ act(() => clipB?.dispatchEvent(new MouseEvent("click", { bubbles: true, ...init })));++ click({ [modifier]: true });+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["clip-a", "clip-b"]));+ expect(view.setSelectedElementId).not.toHaveBeenCalled();+ expect(view.onSelectElement).toHaveBeenLastCalledWith(second);++ click({ [modifier]: true });+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["clip-a"]));+ expect(view.onSelectElement).toHaveBeenLastCalledWith(first);+ act(() => view.root.unmount());+ },+ );+ it("Cmd-click adds a clip in a host that passes no onSelectElement", () => {+ const first = element("clip-a", TRACK_A);+ const second = element("clip-b", TRACK_B);+ usePlayerStore.getState().setElements([first, second]);+ usePlayerStore.getState().setSelection([first.id], first.id);+ const view = renderLanes({ elements: [first, second], withoutSelectHandler: true });+ act(() =>+ view.host+ .querySelector('[data-el-id="clip-b"]')+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true, metaKey: true })),+ );+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["clip-a", "clip-b"]));+ act(() => view.root.unmount());+ });});describe("TimelineLanes clip thumbnails", () => {diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsxindex 6ccedb5856..5652419c09 100644--- a/packages/studio/src/player/components/TimelineLanes.tsx+++ b/packages/studio/src/player/components/TimelineLanes.tsx@@ -77,7 +77,6 @@ export function TimelineLanes({setResizingClip,setDraggedClip,setSelectedElementId,- shiftClickClipRef,getPreviewElement,getTrackStyle,keyframeCache,@@ -404,7 +403,6 @@ export function TimelineLanes({onRazorSplit,onRazorSplitAll,blockedClipRef,- shiftClickClipRef,suppressClickRef,scrollRef,setShowPopover,diff --git a/packages/studio/src/player/components/TimelineOverlays.tsx b/packages/studio/src/player/components/TimelineOverlays.tsxindex 561b1b6522..97fa10d70c 100644--- a/packages/studio/src/player/components/TimelineOverlays.tsx+++ b/packages/studio/src/player/components/TimelineOverlays.tsx@@ -1,3 +1,4 @@+import { TimelineAudioGainOverlay } from "./AudioGainDialog";import { useEffect, useMemo } from "react";import type { TimelineElement } from "../store/playerStore";import { EditPopover } from "./EditModal";@@ -222,6 +223,7 @@ export function TimelineOverlays() {<TimelineKeyframeMenuOverlay /><TimelineClipMenuOverlay /><TimelineGapMenuOverlay />+ <TimelineAudioGainOverlay /></>);}diff --git a/packages/studio/src/player/components/audioClipLink.test.ts b/packages/studio/src/player/components/audioClipLink.test.tsindex c4e81bb248..3a023cec66 100644--- a/packages/studio/src/player/components/audioClipLink.test.ts+++ b/packages/studio/src/player/components/audioClipLink.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";import {audioPillFlags,expandToLinkedMembers,+ dropMisalignedTrimPartners,linkedGestureKeys,linkedMembersOf,mediaAssetIdentity,@@ -204,6 +205,53 @@ describe("selectClipWithLinks", () => {});});+describe("toggleClipWithLinks", () => {+ const clips = [+ { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },+ { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },+ { id: "title", tag: "div", start: 0, duration: 4, track: 2 },+ { id: "music", tag: "audio", start: 0, duration: 4, track: 3 },+ ];++ async function store() {+ const { usePlayerStore } = await import("../store/playerStore");+ const { toggleClipWithLinks } = await import("./timelineLinkSelection");+ usePlayerStore.getState().setElements(clips);+ usePlayerStore.getState().setSelection(["title"], "title");+ return { usePlayerStore, toggle: toggleClipWithLinks };+ }++ it("adds an unlinked clip to the selection and makes it primary", async () => {+ const { usePlayerStore, toggle } = await store();+ expect(toggle("music", false)?.id).toBe("music");+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["title", "music"]));+ expect(usePlayerStore.getState().selectedElementId).toBe("music");+ });++ it("adding a linked clip adds its partner too", async () => {+ const { usePlayerStore, toggle } = await store();+ toggle("talk-audio", false);+ expect(usePlayerStore.getState().selectedElementIds).toEqual(+ new Set(["title", "talk", "talk-audio"]),+ );+ });++ it("toggling a selected clip removes it and its partner, keeping the rest", async () => {+ const { usePlayerStore, toggle } = await store();+ toggle("talk", false);+ expect(toggle("talk", false)?.id).toBe("title");+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["title"]));+ expect(toggle("title", false)).toBeNull();+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set());+ });++ it("Alt adds only the clicked member of a linked pair", async () => {+ const { usePlayerStore, toggle } = await store();+ toggle("talk", true);+ expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["title", "talk"]));+ });+});+describe("Linked Selection off", () => {const linkedPair = [{ id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },@@ -229,3 +277,15 @@ describe("Linked Selection off", () => {}});});++describe("dropMisalignedTrimPartners", () => {+ const v = { id: "v", link: "lk", start: 2, duration: 6 };+ const a = { id: "a", link: "lk", start: 3, duration: 5 };+ const keys = new Set(["v", "a"]);+ it("keeps a partner whose grabbed edge is at the same time", () => {+ expect(dropMisalignedTrimPartners(keys, v, [v, a], "end")).toEqual(keys);+ });+ it("trims only the grabbed clip when the partner's edge is elsewhere", () => {+ expect(dropMisalignedTrimPartners(keys, v, [v, a], "start")).toEqual(new Set(["v"]));+ });+});diff --git a/packages/studio/src/player/components/audioClipLink.ts b/packages/studio/src/player/components/audioClipLink.tsindex 355659d0b6..b5e8e322cf 100644--- a/packages/studio/src/player/components/audioClipLink.ts+++ b/packages/studio/src/player/components/audioClipLink.ts@@ -1,4 +1,5 @@import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";+import { syncPartnerOf } from "./clipSync";type LinkScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;type LinkedElement = Pick<TimelineElement, "id" | "key" | "link"> & LinkScoped;@@ -78,3 +79,79 @@ export function linkedGestureKeys(const base = selected.has(grabbedKey) ? selected : [grabbedKey];return expandToLinkedMembers(base, elements, linked);}++type TimedLinked = LinkedElement & Pick<TimelineElement, "start" | "duration">;++const edgeTime = (el: Pick<TimelineElement, "start" | "duration">, edge: "start" | "end") =>+ edge === "start" ? el.start : el.start + el.duration;++export function dropMisalignedTrimPartners(+ keys: ReadonlySet<string>,+ grabbed: TimedLinked,+ elements: readonly TimedLinked[],+ edge: "start" | "end",+): Set<string> {+ const kept = new Set(keys);+ if (!isLinked(grabbed)) return kept;+ for (const el of elements) {+ if (!sharesLinkGroup(el, grabbed) || keyOf(el) === keyOf(grabbed)) continue;+ if (Math.abs(edgeTime(el, edge) - edgeTime(grabbed, edge)) > 1e-3) kept.delete(keyOf(el));+ }+ return kept;+}++type BoundedElement = Pick<+ TimelineElement,+ | "id"+ | "key"+ | "tag"+ | "start"+ | "duration"+ | "link"+ | "syncOrigin"+ | "playbackStart"+ | "playbackRate"+ | "sourceFile"+>;++const tagOf = (el: Pick<TimelineElement, "tag">) => el.tag.trim().toLowerCase();++function partnerVideoBounds(+ audio: BoundedElement,+ elements: readonly BoundedElement[],+): { videoKey: string; start: number; end: number } | null {+ if (tagOf(audio) !== "audio") return null;+ const linkedVideo = isLinked(audio)+ ? elements.find((el) => sharesLinkGroup(el, audio) && tagOf(el) === "video")+ : undefined;+ const video = linkedVideo ?? syncPartnerOf(audio, elements);+ return video+ ? { videoKey: keyOf(video), start: video.start, end: video.start + video.duration }+ : null;+}++export function heldAudioShiftRange(+ movers: readonly BoundedElement[],+ elements: readonly BoundedElement[],+ moving: ReadonlySet<string>,+): { min: number; max: number } {+ let min = Number.NEGATIVE_INFINITY;+ let max = Number.POSITIVE_INFINITY;+ for (const mover of movers) {+ const bounds = heldPartnerVideoBounds(mover, elements, moving);+ if (!bounds) continue;+ const low = bounds.start - mover.start;+ min = Math.max(min, low);+ max = Math.min(max, Math.max(low, bounds.end - mover.duration - mover.start));+ }+ return { min, max };+}++export function heldPartnerVideoBounds(+ audio: BoundedElement,+ elements: readonly BoundedElement[],+ gestureKeys: ReadonlySet<string>,+): { start: number; end: number } | null {+ const bounds = partnerVideoBounds(audio, elements);+ return bounds && !gestureKeys.has(bounds.videoKey) ? bounds : null;+}diff --git a/packages/studio/src/player/components/audioGainApply.test.ts b/packages/studio/src/player/components/audioGainApply.test.tsnew file mode 100644index 0000000000..5bdb60bd5b--- /dev/null+++ b/packages/studio/src/player/components/audioGainApply.test.ts@@ -0,0 +1,87 @@+// @vitest-environment happy-dom+import { afterEach, describe, expect, it, vi } from "vitest";+import type { TimelineElement } from "../store/timelineElement";+import { normalizeClipsLoudness, writeClipGains } from "./audioGainApply";++const clip = (id: string, extra: Partial<TimelineElement> = {}): TimelineElement => ({+ id,+ domId: id,+ tag: "audio",+ src: `${id}.mp3`,+ start: 0,+ duration: 4,+ track: 0,+ ...extra,+});++const volumeLane = JSON.stringify({+ version: 1,+ lanes: [{ target: "volume", points: [{ t: 0, v: 0.25 }] }],+});+const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };++afterEach(() => vi.unstubAllGlobals());++describe("normalizeClipsLoudness", () => {+ it("refuses a clip whose volume lane owns its gain, before measuring or writing", async () => {+ const fetchSpy = vi.fn(async () => Response.json({ plan }));+ vi.stubGlobal("fetch", fetchSpy);+ const onSetElementAttributeQuiet = vi.fn(async () => ({ status: "saved" as const }));+ await expect(+ normalizeClipsLoudness("p1", [clip("vo", { automation: volumeLane })], {+ onSetElementAttributeQuiet,+ }),+ ).rejects.toThrow(/volume is automated/);+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(onSetElementAttributeQuiet).not.toHaveBeenCalled();+ });++ it("rejects instead of claiming success when the save fails", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn(async () => Response.json({ plan })),+ );+ const onSetElementAttributeQuiet = vi.fn(async () => ({+ status: "failed" as const,+ reason: "disk full",+ }));+ await expect(+ normalizeClipsLoudness("p1", [clip("vo")], { onSetElementAttributeQuiet }),+ ).rejects.toThrow("disk full");+ });+});++describe("writeClipGains", () => {+ it("stops at the first refused single save", async () => {+ const onSetElementAttributeQuiet = vi.fn(async () => ({+ status: "refused" as const,+ reason: "Cannot edit timeline while recording",+ }));+ await expect(+ writeClipGains(+ [+ { element: clip("a"), gain: 2 },+ { element: clip("b"), gain: 2 },+ ],+ { onSetElementAttributeQuiet },+ ),+ ).rejects.toThrow("Cannot edit timeline while recording");+ expect(onSetElementAttributeQuiet).toHaveBeenCalledTimes(1);+ });++ it("surfaces a failed multi-clip save", async () => {+ const onSetElementsAttributeQuiet = vi.fn(async () => ({+ status: "failed" as const,+ reason: "disk full",+ }));+ await expect(+ writeClipGains(+ [+ { element: clip("a"), gain: 2 },+ { element: clip("b"), gain: 2 },+ ],+ { onSetElementsAttributeQuiet },+ ),+ ).rejects.toThrow("disk full");+ });+});diff --git a/packages/studio/src/player/components/audioGainApply.ts b/packages/studio/src/player/components/audioGainApply.tsnew file mode 100644index 0000000000..081e08a746--- /dev/null+++ b/packages/studio/src/player/components/audioGainApply.ts@@ -0,0 +1,57 @@+import { formatAudioGain } from "@hyperframes/core/audio-gain";+import type { TimelineElement } from "../store/timelineElement";+import type { TimelineEditCallbacks } from "./timelineCallbacks";+import {+ normalizeToastText,+ requestNormalizePlan,+ throwUnlessSaved,+ VOLUME_LANE_REFUSAL,+ volumeLaneOwnsGain,+} from "./clipMenuNormalize";++export const AUDIO_GAIN_LABEL = "Audio Gain";++type VolumeWriters = Pick<+ TimelineEditCallbacks,+ "onSetElementAttributeQuiet" | "onSetElementsAttributeQuiet"+>;++/** Every clip's new gain as `data-volume`, one undo step when the host can save them together. */+export async function writeClipGains(+ edits: ReadonlyArray<{ element: TimelineElement; gain: number }>,+ writers: VolumeWriters,+ label = AUDIO_GAIN_LABEL,+): Promise<void> {+ if (edits.some(({ element }) => volumeLaneOwnsGain(element))) {+ throw new Error(VOLUME_LANE_REFUSAL);+ }+ const values = edits.map(({ element, gain }) => ({ element, value: formatAudioGain(gain) }));+ if (values.length > 1 && writers.onSetElementsAttributeQuiet) {+ throwUnlessSaved(await writers.onSetElementsAttributeQuiet(values, "data-volume", label));+ return;+ }+ for (const { element, value } of values) {+ throwUnlessSaved(+ await writers.onSetElementAttributeQuiet?.(element, "data-volume", value, label),+ );+ }+}++/** Measure each clip against −16 LUFS, write the gains, and say what happened. */+export async function normalizeClipsLoudness(+ projectId: string,+ elements: readonly TimelineElement[],+ writers: VolumeWriters,+): Promise<string> {+ if (elements.some(volumeLaneOwnsGain)) throw new Error(VOLUME_LANE_REFUSAL);+ const plans = await Promise.all(elements.map((el) => requestNormalizePlan(projectId, el)));+ await writeClipGains(+ elements.map((element, index) => ({ element, gain: plans[index]?.volume ?? 1 })),+ writers,+ "Normalize loudness",+ );+ const [only] = plans;+ return plans.length === 1 && only+ ? normalizeToastText(only)+ : `Normalized ${plans.length} clips to −16 LUFS`;+}diff --git a/packages/studio/src/player/components/audioGainDialogStore.ts b/packages/studio/src/player/components/audioGainDialogStore.tsnew file mode 100644index 0000000000..af0bc397c2--- /dev/null+++ b/packages/studio/src/player/components/audioGainDialogStore.ts@@ -0,0 +1,36 @@+import { create } from "zustand";+import { usePlayerStore, type TimelineElement } from "../store/playerStore";+import { clipHasSound } from "./clipMenuNormalize";++interface AudioGainDialogState {+ targetKeys: readonly string[] | null;+ open: (keys: readonly string[]) => void;+ close: () => void;+}++/** Which clips the Audio Gain dialog (G) is open for. */+export const useAudioGainDialogStore = create<AudioGainDialogState>((set) => ({+ targetKeys: null,+ open: (keys) => set({ targetKeys: keys }),+ close: () => set({ targetKeys: null }),+}));++const keyOf = (el: TimelineElement) => el.key ?? el.id;++/** The selected clips with sound, or just `clicked` when it is outside the selection. */+function audioGainTargetKeys(clicked?: TimelineElement): string[] {+ const { elements, selectedElementId, selectedElementIds } = usePlayerStore.getState();+ const selected = new Set(selectedElementIds);+ if (selectedElementId) selected.add(selectedElementId);+ if (clicked && !selected.has(keyOf(clicked)))+ return clipHasSound(clicked) ? [keyOf(clicked)] : [];+ return elements.filter((el) => selected.has(keyOf(el)) && clipHasSound(el)).map(keyOf);+}++/** Open Audio Gain for the selection (or the clicked clip); false when none of it has sound. */+export function openAudioGainDialog(clicked?: TimelineElement): boolean {+ const keys = audioGainTargetKeys(clicked);+ if (keys.length === 0) return false;+ useAudioGainDialogStore.getState().open(keys);+ return true;+}diff --git a/packages/studio/src/player/components/audioGainPlan.test.ts b/packages/studio/src/player/components/audioGainPlan.test.tsnew file mode 100644index 0000000000..b55594efbc--- /dev/null+++ b/packages/studio/src/player/components/audioGainPlan.test.ts@@ -0,0 +1,82 @@+import { describe, expect, it } from "vitest";+import { audioGainToDb, MAX_AUDIO_GAIN } from "@hyperframes/core/audio-gain";+import { peakAmplitudeDb, planAudioGain, type AudioGainClip } from "./audioGainPlan";++const clip = (key: string, gain: number, sourcePeak: number | null): AudioGainClip => ({+ key,+ gain,+ sourcePeak,+});+const db = (gain: number | undefined) => audioGainToDb(gain ?? Number.NaN);+const gainOf = (plan: ReturnType<typeof planAudioGain>, key: string) =>+ plan.find((edit) => edit.key === key)?.gain;++describe("planAudioGain", () => {+ it("Set Gain to puts every clip at the same gain", () => {+ const plan = planAudioGain([clip("a", 2, 0.5), clip("b", 0.5, null)], { mode: "set", db: -6 });+ expect(db(gainOf(plan, "a"))).toBeCloseTo(-6, 6);+ expect(db(gainOf(plan, "b"))).toBeCloseTo(-6, 6);+ });++ it("Adjust Gain by moves each clip by the same dB from where it is", () => {+ const plan = planAudioGain([clip("a", 2, null), clip("b", 0.5, null)], {+ mode: "adjust",+ db: 3,+ });+ expect(db(gainOf(plan, "a"))).toBeCloseTo(db(2) + 3, 6);+ expect(db(gainOf(plan, "b"))).toBeCloseTo(db(0.5) + 3, 6);+ });++ it("Normalize Max Peak moves all clips together until the loudest peak hits the target", () => {+ const plan = planAudioGain([clip("loud", 1, 0.5), clip("quiet", 1, 0.25)], {+ mode: "normalize-max",+ db: -1,+ });+ expect(db(0.5 * (gainOf(plan, "loud") ?? 0))).toBeCloseTo(-1, 6);+ expect(db(gainOf(plan, "loud")) - db(gainOf(plan, "quiet"))).toBeCloseTo(0, 6);+ });++ it("Normalize Max Peak counts each clip's current gain", () => {+ const plan = planAudioGain([clip("a", 0.5, 0.8), clip("b", 2, 0.25)], {+ mode: "normalize-max",+ db: -3,+ });+ expect(db(0.25 * (gainOf(plan, "b") ?? 0))).toBeCloseTo(-3, 6);+ });++ it("Normalize All Peaks brings each clip's own peak to the target", () => {+ const plan = planAudioGain([clip("a", 1, 0.5), clip("b", 3, 0.25)], {+ mode: "normalize-all",+ db: -3,+ });+ expect(db(0.5 * (gainOf(plan, "a") ?? 0))).toBeCloseTo(-3, 6);+ expect(db(0.25 * (gainOf(plan, "b") ?? 0))).toBeCloseTo(-3, 6);+ });++ it("leaves clips it could not measure out of a normalize", () => {+ const plan = planAudioGain([clip("a", 1, 0.5), clip("b", 1, null), clip("c", 1, 0)], {+ mode: "normalize-all",+ db: -1,+ });+ expect(plan.map((edit) => edit.key)).toEqual(["a"]);+ });++ it("clamps to the +12 dB ceiling and to silence", () => {+ const loud = planAudioGain([clip("a", 1, 0.001)], { mode: "normalize-all", db: 0 });+ expect(gainOf(loud, "a")).toBe(MAX_AUDIO_GAIN);+ expect(gainOf(planAudioGain([clip("a", 1, null)], { mode: "set", db: 40 }), "a")).toBe(+ MAX_AUDIO_GAIN,+ );+ expect(gainOf(planAudioGain([clip("a", 0, null)], { mode: "adjust", db: 6 }), "a")).toBe(0);+ });+});++describe("peakAmplitudeDb", () => {+ it("is the loudest peak across the selection at each clip's gain", () => {+ expect(peakAmplitudeDb([clip("a", 1, 0.5), clip("b", 2, 0.5)])).toBeCloseTo(0, 6);+ });++ it("is null when nothing was measured", () => {+ expect(peakAmplitudeDb([clip("a", 1, null)])).toBeNull();+ });+});diff --git a/packages/studio/src/player/components/audioGainPlan.ts b/packages/studio/src/player/components/audioGainPlan.tsnew file mode 100644index 0000000000..b0b4c898f5--- /dev/null+++ b/packages/studio/src/player/components/audioGainPlan.ts@@ -0,0 +1,53 @@+import { audioDbToGain, audioGainToDb, clampAudioGain } from "@hyperframes/core/audio-gain";++export type AudioGainMode = "set" | "adjust" | "normalize-max" | "normalize-all";++export interface AudioGainChoice {+ mode: AudioGainMode;+ db: number;+}++/** A selected clip: its `data-volume` gain and its source's linear sample peak over the played window. */+export interface AudioGainClip {+ key: string;+ gain: number;+ sourcePeak: number | null;+}++export interface AudioGainEdit {+ key: string;+ gain: number;+}++function isMeasured(clip: AudioGainClip): clip is AudioGainClip & { sourcePeak: number } {+ return clip.sourcePeak !== null && clip.sourcePeak > 0;+}++const heardPeak = (clip: AudioGainClip & { sourcePeak: number }) => clip.sourcePeak * clip.gain;++/** Premiere's Audio Gain options as new `data-volume` gains, clamped to silence..+12 dB. */+export function planAudioGain(+ clips: readonly AudioGainClip[],+ choice: AudioGainChoice,+): AudioGainEdit[] {+ const target = audioDbToGain(choice.db);+ const edit = (clip: AudioGainClip, gain: number) => ({+ key: clip.key,+ gain: clampAudioGain(gain),+ });+ if (choice.mode === "set") return clips.map((clip) => edit(clip, target));+ if (choice.mode === "adjust") return clips.map((clip) => edit(clip, clip.gain * target));+ const measured = clips.filter(isMeasured);+ if (choice.mode === "normalize-all") {+ return measured.map((clip) => edit(clip, target / clip.sourcePeak));+ }+ const loudest = Math.max(0, ...measured.map(heardPeak));+ if (loudest <= 0) return [];+ return measured.map((clip) => edit(clip, (clip.gain * target) / loudest));+}++/** The loudest peak the selection plays at its current gains, in dBFS. */+export function peakAmplitudeDb(clips: readonly AudioGainClip[]): number | null {+ const loudest = Math.max(0, ...clips.filter(isMeasured).map(heardPeak));+ return loudest > 0 ? audioGainToDb(loudest) : null;+}diff --git a/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsxindex a91d2e4768..63665b7ed2 100644--- a/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx+++ b/packages/studio/src/player/components/clipMenuAudioItems.noShell.test.tsx@@ -3,6 +3,7 @@ import { act } from "react";import { afterEach, describe, expect, it, vi } from "vitest";import { createHappyDomRootHarness } from "./testRootHarness";import { ClipMenuAudioItems } from "./clipMenuAudioItems";+import { AudioGainDialog } from "./AudioGainDialog";import { usePlayerStore } from "../store/playerStore";import { usePreviewIframeStore } from "../store/previewIframeStore";import type { TimelineElement } from "../store/timelineElement";@@ -38,7 +39,7 @@ function mountPreview(): void {usePreviewIframeStore.getState().setIframe(iframe);}-function render(part: "normalize" | "duck") {+function render(part: "gain" | "duck") {const host = document.createElement("div");document.body.appendChild(host);act(() =>@@ -55,23 +56,30 @@ afterEach(() => {});describe("ClipMenuAudioItems in a host without Studio's shell", () => {- it("offers Normalize and Duck from the timeline session and the live preview", () => {+ it("offers Audio Gain and Duck from the timeline session and the live preview", () => {usePlayerStore.getState().beginTimelineSession("p1");mountPreview();- expect(render("normalize").textContent).toContain("Normalize loudness");+ expect(render("gain").textContent).toContain("Audio Gain…");expect(render("duck").textContent).toContain("Duck under voice");});- it("normalizes through the session's project and reports through onNotice", async () => {+ it("the dialog's loudness row normalizes through the session's project and 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());+ const host = document.createElement("div");+ document.body.appendChild(host);+ act(() => harness.mount(host).render(<AudioGainDialog elements={[tour]} onClose={() => {}} />));+ const loudness = [...document.querySelectorAll("label")].find((l) =>+ l.textContent?.includes("−16 LUFS"),+ );+ act(() => loudness?.querySelector("input")?.click());+ const ok = [...document.querySelectorAll("button")].find((b) => b.textContent === "OK");+ await act(async () => ok?.click());await vi.waitFor(() => expect(onNotice).toHaveBeenCalled());- expect(String(fetchSpy.mock.calls[0]?.[0])).toContain("/api/projects/p1/loudness/normalize");+ const urls = fetchSpy.mock.calls.map((call) => String(call[0]));+ expect(urls).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 a73119a647..50dccc2780 100644--- a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx@@ -4,6 +4,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";import { createHappyDomRootHarness } from "./testRootHarness";import { ClipMenuAudioItems } from "./clipMenuAudioItems";import type { TimelineElement } from "../store/timelineElement";+import { useAudioGainDialogStore } from "./audioGainDialogStore";const showToast = vi.fn();const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});@@ -27,7 +28,7 @@ vi.mock("../../contexts/TimelineEditContext", () => ({const harness = createHappyDomRootHarness();-function render(element: TimelineElement, part: "normalize" | "duck" = "normalize") {+function render(element: TimelineElement, part: "gain" | "duck" = "gain") {const host = document.createElement("div");document.body.appendChild(host);act(() =>@@ -39,7 +40,6 @@ function render(element: TimelineElement, part: "normalize" | "duck" = "normaliz}const base = { start: 0, duration: 4, track: 0 };-const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };const clickItem = async (host: HTMLElement, label: string) => {const button = [...host.querySelectorAll("button")].find((b) => b.textContent?.includes(label));await act(async () => button?.click());@@ -95,12 +95,8 @@ describe("ClipMenuAudioItems", () => {});});- 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(- "fetch",- vi.fn(async () => Response.json({ plan })),- );+ it("Audio Gain… opens the G dialog for the clicked clip", async () => {+ useAudioGainDialogStore.getState().close();const element: TimelineElement = {...base,id: "a-roll",@@ -110,42 +106,12 @@ describe("ClipMenuAudioItems", () => {};const host = render(element);const button = [...host.querySelectorAll("button")].find((b) =>- b.textContent?.includes("Normalize loudness"),+ b.textContent?.includes("Audio Gain…"),);+ expect(button?.textContent).toBe("Audio Gain…G");await act(async () => button?.click());- await vi.waitFor(() => expect(setQuiet).toHaveBeenCalled());- expect(setQuiet).toHaveBeenCalledWith(element, "data-volume", "2", "Normalize loudness");- expect(showToast).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");- vi.unstubAllGlobals();- });-- it("refuses to normalize a clip whose volume lane owns its gain", async () => {- const fetchSpy = vi.fn(async () => Response.json({ plan }));- vi.stubGlobal("fetch", fetchSpy);- const automation = JSON.stringify({- version: 1,- lanes: [{ target: "volume", points: [{ t: 0, v: 0.25 }] }],- });- const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3", automation });- await clickItem(host, "Normalize loudness");- await vi.waitFor(() => expect(showToast).toHaveBeenCalled());- expect(showToast).toHaveBeenCalledWith(expect.stringContaining("volume is automated"), "error");- expect(setQuiet).not.toHaveBeenCalled();- expect(fetchSpy).not.toHaveBeenCalled();- vi.unstubAllGlobals();- });-- it("reports a failed save instead of claiming the clip was normalized", async () => {- vi.stubGlobal(- "fetch",- vi.fn(async () => Response.json({ plan })),- );- setQuiet.mockResolvedValue({ status: "failed", reason: "disk full" });- const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3" });- await clickItem(host, "Normalize loudness");- await vi.waitFor(() => expect(showToast).toHaveBeenCalledWith("disk full", "error"));- expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Normalized"), "info");- vi.unstubAllGlobals();+ expect(useAudioGainDialogStore.getState().targetKeys).toEqual(["a-roll"]);+ expect(host.textContent).not.toContain("Normalize loudness");});it("stops ducking at the first refused save and says why", async () => {diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsxindex 5488d84301..a543593416 100644--- a/packages/studio/src/player/components/clipMenuAudioItems.tsx+++ b/packages/studio/src/player/components/clipMenuAudioItems.tsx@@ -1,18 +1,10 @@-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,- requestNormalizePlan,- throwUnlessSaved,- TimelineSaveError,- VOLUME_LANE_REFUSAL,- volumeLaneOwnsGain,-} from "./clipMenuNormalize";+import { clipHasSound, throwUnlessSaved, TimelineSaveError } from "./clipMenuNormalize";+import { openAudioGainDialog } from "./audioGainDialogStore";import { offersDuck, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";const ITEM_CLASS =@@ -25,13 +17,13 @@ const DUCK_TOAST: Record<DuckOutcome, string> = {aborted: "Could not group the voices to duck under.",};-/** Normalize loudness (one-shot) or Duck under voice (toggle), placed separately in the sound group. */+/** Audio Gain… (opens the G dialog) or Duck under voice (toggle), placed separately in the sound group. */export function ClipMenuAudioItems({part,element,onClose,}: {- part: "normalize" | "duck";+ part: "gain" | "duck";element: TimelineElement;onClose: () => void;}) {@@ -48,28 +40,6 @@ export function ClipMenuAudioItems({return null;}- const normalize = async () => {- onClose();- if (volumeLaneOwnsGain(element)) {- showToast(VOLUME_LANE_REFUSAL, "error");- return;- }- try {- const plan = await requestNormalizePlan(projectId, element);- throwUnlessSaved(- await onSetElementAttributeQuiet(- element,- "data-volume",- formatAudioGain(plan.volume),- "Normalize loudness",- ),- );- showToast(normalizeToastText(plan), "info");- } catch (error) {- showToast(error instanceof Error ? error.message : String(error), "error");- }- };-const toggleDuck = async () => {onClose();if (!doc || !bed) return;@@ -93,10 +63,19 @@ export function ClipMenuAudioItems({showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");};- if (part === "normalize") {+ if (part === "gain") {return (- <button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}>- <span>Normalize loudness</span>+ <button+ type="button"+ role="menuitem"+ className={ITEM_CLASS}+ onClick={() => {+ onClose();+ openAudioGainDialog(element);+ }}+ >+ <span>Audio Gain…</span>+ <span className="text-neutral-500 text-[10px] ml-3">G</span></button>);}diff --git a/packages/studio/src/player/components/clipMenuLinkItems.test.ts b/packages/studio/src/player/components/clipMenuLinkItems.test.tsindex 2c94db56b1..1a4c9e30ea 100644--- a/packages/studio/src/player/components/clipMenuLinkItems.test.ts+++ b/packages/studio/src/player/components/clipMenuLinkItems.test.ts@@ -48,6 +48,51 @@ describe("resolveLinkMenuItems", () => {expect(labels(audio, [video, audio], ["talk", "talk-audio"])[0]).toBe("Link to video");});+ it("offers Link to the lone same-file partner on another track when one clip is right-clicked", () => {+ const video = clip("talk", "video", { track: 0 });+ const audio = clip("talk-audio", "audio", { track: 1, start: 2 });+ expect(labels(audio, [video, audio], ["talk-audio"])[0]).toBe("Link to video");+ expect(labels(video, [video, audio])[0]).toBe("Link to audio");+ });++ it("dispatches the convenience link with the clip and its partner", () => {+ const onLinkEdit = vi.fn();+ const video = clip("talk", "video", { track: 0 });+ const audio = clip("talk-audio", "audio", { track: 1 });+ const [link] = resolveLinkMenuItems({+ element: audio,+ elements: [video, audio],+ selectedKeys: new Set(["talk-audio"]),+ onLinkEdit,+ });+ link?.run();+ expect(onLinkEdit).toHaveBeenCalledWith({ kind: "link", elements: [audio, video] });+ });++ it("offers no convenience Link when the partner is ambiguous, linked, another file or the same track", () => {+ const audio = clip("talk-audio", "audio", { track: 1 });+ const video = clip("talk", "video", { track: 0 });+ const twin = clip("talk-2", "video", { track: 2 });+ expect(labels(audio, [video, twin, audio], ["talk-audio"])).not.toContain("Link to video");+ const linked = clip("talk", "video", { track: 0, link: "lk-9" });+ expect(labels(audio, [linked, audio], ["talk-audio"])).not.toContain("Link to video");+ const other = clip("other", "video", { track: 0, src: "other.mp4" });+ expect(labels(audio, [other, audio], ["talk-audio"])).not.toContain("Link to video");+ const sameTrack = clip("talk", "video", { track: 1 });+ expect(labels(audio, [sameTrack, audio], ["talk-audio"])).not.toContain("Link to video");+ });++ it("offers no convenience Link while other clips are also selected", () => {+ const audio = clip("talk-audio", "audio", { track: 1 });+ const video = clip("talk", "video", { track: 0 });+ const title = clip("title", "div", { track: 2 });+ expect(+ labels(audio, [video, audio, title], ["talk-audio", "title"]).some((l) =>+ l.startsWith("Link"),+ ),+ ).toBe(false);+ });+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" });@@ -87,4 +132,43 @@ describe("resolveLinkMenuItems", () => {})[0]?.run();expect(onLinkEdit).toHaveBeenCalledWith({ kind: "detach", element: talk });});++ it("offers Link for a trimmed audio and its video (timing does not matter)", () => {+ const video = clip("talk", "video", { muted: true });+ const audio = clip("talk-audio", "audio", { start: 1, duration: 2, playbackStart: 1 });+ expect(labels(video, [video, audio], ["talk", "talk-audio"])[0]).toBe("Link to audio");+ });++ it("offers Link for a pair of different files", () => {+ const video = clip("talk", "video", { muted: true });+ const music = clip("bgm", "audio", { src: "bgm.mp3" });+ expect(labels(music, [video, music], ["talk", "bgm"])).toEqual(["Link to video"]);+ });++ it("offers no Link when one selected clip is already linked elsewhere", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-9" });+ const audio = clip("bgm", "audio", { src: "bgm.mp3" });+ const partner = clip("talk-audio", "audio", { link: "lk-9" });+ expect(labels(audio, [video, audio, partner], ["talk", "bgm"])).toEqual([]);+ });++ it("disables Merge back with a tooltip while the pair is out of sync", () => {+ const video = clip("talk", "video", { muted: true, link: "lk-1" });+ const audio = clip("talk-audio", "audio", { link: "lk-1", start: 0.5 });+ const merge = resolveLinkMenuItems({+ element: audio,+ elements: [video, audio],+ selectedKeys: new Set(),+ onLinkEdit: vi.fn(),+ }).find((item) => item.label === "Merge audio back into video");+ expect(merge?.disabledReason).toBe("Move into Sync first");+ const synced = clip("talk-audio", "audio", { link: "lk-1" });+ const enabled = resolveLinkMenuItems({+ element: synced,+ elements: [video, synced],+ selectedKeys: new Set(),+ onLinkEdit: vi.fn(),+ }).find((item) => item.label === "Merge audio back into video");+ expect(enabled?.disabledReason).toBeUndefined();+ });});diff --git a/packages/studio/src/player/components/clipMenuLinkItems.tsx b/packages/studio/src/player/components/clipMenuLinkItems.tsxindex 4931b09d7e..3c46a314d8 100644--- a/packages/studio/src/player/components/clipMenuLinkItems.tsx+++ b/packages/studio/src/player/components/clipMenuLinkItems.tsx@@ -2,12 +2,19 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";import type { TimelineLinkEdit } from "./timelineCallbacks";import { linkedMembersOf } from "./audioClipLink";-import { canDetachAudio, canLinkPair, findMergePair } from "../../components/editor/mediaLinkEdits";+import {+ canDetachAudio,+ canLinkPair,+ findMergePair,+ isPairInSync,+ sharesSourceFile,+} from "../../components/editor/mediaLinkEdits";interface LinkMenuItem {label: string;shortcut?: string;destructive?: boolean;+ disabledReason?: string;run: () => void;}@@ -15,6 +22,22 @@ const keyOf = (el: TimelineElement) => el.key ?? el.id;const tagOf = (el: TimelineElement) => el.tag.trim().toLowerCase();+function loneSameFilePartner(+ element: TimelineElement,+ elements: readonly TimelineElement[],+): TimelineElement | null {+ const opposite = { video: "audio", audio: "video" }[tagOf(element)];+ if (!opposite || element.link) return null;+ const candidates = elements.filter(+ (el) =>+ !el.link &&+ tagOf(el) === opposite &&+ el.track !== element.track &&+ sharesSourceFile([element, el]),+ );+ return candidates.length === 1 ? (candidates[0] ?? null) : null;+}+function partnerSuffix(element: TimelineElement, others: readonly TimelineElement[]): string {const partners = others.filter((el) => keyOf(el) !== keyOf(element));const [partner] = partners;@@ -23,6 +46,26 @@ function partnerSuffix(element: TimelineElement, others: readonly TimelineElemenreturn pair === "audio+video" ? ` ${tagOf(partner)}` : "";}+function linkItem(+ element: TimelineElement,+ elements: readonly TimelineElement[],+ selected: TimelineElement[],+ selectedKeys: ReadonlySet<string>,+ onLinkEdit: (edit: TimelineLinkEdit) => unknown,+): LinkMenuItem | null {+ const selectedPair = canLinkPair(selected) && selectedKeys.has(keyOf(element));+ const soleSelection = selected.every((el) => keyOf(el) === keyOf(element));+ const partner = !selectedPair && soleSelection ? loneSameFilePartner(element, elements) : null;+ const linkPair = selectedPair ? selected : partner ? [element, partner] : null;+ if (!linkPair) return null;+ const suffix = partnerSuffix(element, linkPair);+ return {+ label: `Link${suffix && ` to${suffix}`}`,+ ...(selectedPair ? { shortcut: "⌘L" } : {}),+ run: () => onLinkEdit({ kind: "link", elements: linkPair }),+ };+}+/** The link-model items for a clip, in wireframe order (detach · unlink/link · merge · delete-one). */export function resolveLinkMenuItems(input: {element: TimelineElement;@@ -50,17 +93,15 @@ export function resolveLinkMenuItems(input: {shortcut: "⌘L",run: () => onLinkEdit({ kind: "unlink", elements: members }),});- } else if (canLinkPair(selected) && selectedKeys.has(keyOf(element))) {- items.push({- label: `Link${partnerSuffix(element, selected) && ` to${partnerSuffix(element, selected)}`}`,- shortcut: "⌘L",- run: () => onLinkEdit({ kind: "link", elements: selected }),- });+ } else {+ const link = linkItem(element, elements, selected, selectedKeys, onLinkEdit);+ if (link) items.push(link);}const pair = findMergePair(element, elements);if (pair) {items.push({label: "Merge audio back into video",+ disabledReason: isPairInSync(pair.video, pair.audio) ? undefined : "Move into Sync first",run: () => onLinkEdit({ kind: "merge", ...pair }),});}@@ -102,8 +143,12 @@ export function ClipMenuLinkItems({key={item.label}type="button"role="menuitem"- className={`w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden cursor-pointer hover:bg-neutral-800 focus-visible:bg-neutral-800 ${- item.destructive ? "text-red-400" : "text-neutral-300"+ disabled={item.disabledReason !== undefined}+ title={item.disabledReason}+ className={`w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden ${+ item.disabledReason !== undefined+ ? "text-neutral-600 cursor-not-allowed"+ : `cursor-pointer hover:bg-neutral-800 focus-visible:bg-neutral-800 ${item.destructive ? "text-red-400" : "text-neutral-300"}`}`}onClick={() => {item.run();diff --git a/packages/studio/src/player/components/clipMenuToolItems.test.tsx b/packages/studio/src/player/components/clipMenuToolItems.test.tsxindex 72230c4b3c..b1219588a6 100644--- a/packages/studio/src/player/components/clipMenuToolItems.test.tsx+++ b/packages/studio/src/player/components/clipMenuToolItems.test.tsx@@ -2,7 +2,7 @@import { act } from "react";import { createRoot, type Root } from "react-dom/client";-import { afterEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import type { TimelineElement } from "../store/playerStore";import { TimelineEditProvider } from "../../contexts/TimelineEditContext";import { useCropPresetBarStore } from "../../components/editor/cropPresetStore";@@ -15,7 +15,10 @@ Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {let root: Root | null = null;+beforeEach(() => vi.useFakeTimers());+afterEach(() => {+ vi.useRealTimers();act(() => root?.unmount());root = null;document.body.innerHTML = "";@@ -31,7 +34,14 @@ const video: TimelineElement = {hasAudio: true,};-function renderItems(group: ClipMenuToolGroup, element: TimelineElement, currentTime = 2) {+function renderItems(+ group: ClipMenuToolGroup,+ element: TimelineElement,+ currentTime = 2,+ withLive = true,+) {+ const setLive = vi.fn((_el: TimelineElement, _attr: string, _value: string | null) => undefined);+ const revertLive = vi.fn((_el: TimelineElement, _attr: string) => undefined);const setQuiet = vi.fn(async (_el: TimelineElement, _attr: string, _value: string | null, _label: string) => undefined,);@@ -42,7 +52,15 @@ function renderItems(group: ClipMenuToolGroup, element: TimelineElement, currentroot = createRoot(host);act(() => {root?.render(- <TimelineEditProvider value={{ onSetElementAttributeQuiet: setQuiet, onFreezeFrame: freeze }}>+ <TimelineEditProvider+ value={{+ onSetElementAttributeQuiet: setQuiet,+ onFreezeFrame: freeze,+ ...(withLive+ ? { onSetElementAttributeLive: setLive, onRevertElementAttributeLive: revertLive }+ : {}),+ }}+ ><ClipMenuToolItemsgroup={group}element={element}@@ -52,7 +70,7 @@ function renderItems(group: ClipMenuToolGroup, element: TimelineElement, current</TimelineEditProvider>,);});- return { setQuiet, onClose, freeze };+ return { setQuiet, onClose, freeze, setLive, revertLive };}function openSubmenu(label: string) {@@ -136,4 +154,112 @@ describe("ClipMenuToolItems", () => {renderItems("time", { ...video, tag: "img" });expect(document.body.textContent).toBe("");});++ describe("Look hover preview", () => {+ function option(text: string) {+ const found = Array.from(+ document.querySelectorAll<HTMLButtonElement>('[role="menuitemradio"]'),+ ).find((button) => button.textContent?.endsWith(text));+ if (!found) throw new Error(`no option ${text}`);+ return found;+ }+ const enter = (text: string) =>+ option(text).dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));+ const hover = (text: string) => {+ act(() => {+ enter(text);+ vi.advanceTimersByTime(100);+ });+ };+ const leave = () => {+ const wrapper = document.querySelector('[role="menu"]')?.parentElement;+ act(() => {+ wrapper?.dispatchEvent(+ new MouseEvent("mouseout", { bubbles: true, relatedTarget: document.body }),+ );+ });+ };++ it("hover applies the look live after the debounce, without saving", () => {+ const { setLive, setQuiet } = renderItems("picture", video);+ openSubmenu("Look");+ act(() => {+ enter("Warm daylight");+ vi.advanceTimersByTime(40);+ });+ expect(setLive).not.toHaveBeenCalled();+ act(() => vi.advanceTimersByTime(60));+ expect(setLive).toHaveBeenCalledWith(+ video,+ "data-color-grading",+ '{"preset":"warm-daylight","intensity":1}',+ );+ expect(setQuiet).not.toHaveBeenCalled();+ });++ it("opening the submenu by click does not preview the auto-focused first option", () => {+ const { setLive } = renderItems("picture", video);+ openSubmenu("Look");+ act(() => vi.advanceTimersByTime(200));+ expect(setLive).not.toHaveBeenCalled();+ });++ it("keyboard focus previews and None previews no look", () => {+ const { setLive } = renderItems("picture", video);+ openSubmenu("Look");+ act(() => {+ option("None").dispatchEvent(new FocusEvent("focusin", { bubbles: true }));+ vi.advanceTimersByTime(100);+ });+ expect(setLive).toHaveBeenCalledWith(video, "data-color-grading", null);+ });++ it("leaving the submenu reverts to the saved look", () => {+ const { revertLive } = renderItems("picture", video);+ openSubmenu("Look");+ hover("Warm daylight");+ leave();+ expect(revertLive).toHaveBeenCalledWith(video, "data-color-grading");+ });++ it("leaving before the debounce fires never previews or reverts", () => {+ const { setLive, revertLive } = renderItems("picture", video);+ openSubmenu("Look");+ act(() => enter("Warm daylight"));+ leave();+ act(() => vi.advanceTimersByTime(200));+ expect(setLive).not.toHaveBeenCalled();+ expect(revertLive).not.toHaveBeenCalled();+ });++ it("clicking commits once and does not revert afterwards", () => {+ const { setQuiet, revertLive } = renderItems("picture", video);+ openSubmenu("Look");+ hover("Warm daylight");+ act(() => option("Warm daylight").click());+ act(() => root?.unmount());+ root = null;+ expect(setQuiet).toHaveBeenCalledTimes(1);+ expect(revertLive).not.toHaveBeenCalled();+ });++ it("closing the menu while previewing reverts", () => {+ const { revertLive } = renderItems("picture", video);+ openSubmenu("Look");+ hover("Warm daylight");+ act(() => root?.unmount());+ root = null;+ expect(revertLive).toHaveBeenCalledWith(video, "data-color-grading");+ });++ it("does nothing when the host has no live callbacks", () => {+ const { setQuiet } = renderItems("picture", video, 2, false);+ openSubmenu("Look");+ expect(() => {+ hover("Warm daylight");+ leave();+ }).not.toThrow();+ expect(setQuiet).not.toHaveBeenCalled();+ });+ });});diff --git a/packages/studio/src/player/components/clipMenuToolItems.tsx b/packages/studio/src/player/components/clipMenuToolItems.tsxindex 4acffdca5a..0348514a66 100644--- a/packages/studio/src/player/components/clipMenuToolItems.tsx+++ b/packages/studio/src/player/components/clipMenuToolItems.tsx@@ -1,4 +1,4 @@-import { useRef, useState, type KeyboardEvent } from "react";+import { useEffect, useRef, useState, type KeyboardEvent } from "react";import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";import { HF_COLOR_GRADING_ATTR } from "@hyperframes/core/color-grading";import type { TimelineElement } from "../store/playerStore";@@ -30,6 +30,47 @@ const ROW_CLASS =const DISABLED_ROW_CLASS ="w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-none text-neutral-600 cursor-not-allowed";const SUBMENU_WIDTH = 170;+const HOVER_PREVIEW_DELAY_MS = 80;++interface HoverPreview {+ apply: (id: string | null) => void;+ clear: () => void;+}++function useHoverPreview(preview: HoverPreview | undefined) {+ const previewRef = useRef(preview);+ previewRef.current = preview;+ const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);+ const activeRef = useRef(false);++ const cancelTimer = () => {+ if (timerRef.current === null) return;+ clearTimeout(timerRef.current);+ timerRef.current = null;+ };+ const end = () => {+ cancelTimer();+ if (!activeRef.current) return;+ activeRef.current = false;+ previewRef.current?.clear();+ };+ const settle = () => {+ cancelTimer();+ activeRef.current = false;+ };+ const start = (id: string | null) => {+ if (!previewRef.current) return;+ cancelTimer();+ timerRef.current = setTimeout(() => {+ timerRef.current = null;+ activeRef.current = true;+ previewRef.current?.apply(id);+ }, HOVER_PREVIEW_DELAY_MS);+ };++ useEffect(() => end, []);+ return { start, end, settle };+}interface ChoiceSection {heading?: string;@@ -48,22 +89,36 @@ function ChoiceSubmenu({sections,activeId,onPick,+ preview,}: {label: string;sections: readonly ChoiceSection[];activeId: string | null;onPick: (id: string | null) => void;+ preview?: HoverPreview;}) {const [open, setOpen] = useState(false);const [flipLeft, setFlipLeft] = useState(false);const rowRef = useRef<HTMLButtonElement | null>(null);const submenuRef = useRef<HTMLDivElement | null>(null);+ const hover = useHoverPreview(preview);+ const openingFocusRef = useRef(false);++ const hideSubmenu = () => {+ hover.end();+ setOpen(false);+ };const show = (focusFirst: boolean) => {const rect = rowRef.current?.getBoundingClientRect();setFlipLeft(rect ? rect.right + SUBMENU_WIDTH > window.innerWidth : false);setOpen(true);- if (focusFirst) requestAnimationFrame(() => focusSibling(submenuRef.current, 1));+ if (!focusFirst) return;+ openingFocusRef.current = true;+ requestAnimationFrame(() => {+ focusSibling(submenuRef.current, 1);+ openingFocusRef.current = false;+ });};const onSubmenuKeyDown = (event: KeyboardEvent) => {@@ -74,7 +129,7 @@ function ChoiceSubmenu({} else if (event.key === "ArrowLeft") {event.preventDefault();event.stopPropagation();- setOpen(false);+ hideSubmenu();rowRef.current?.focus();}};@@ -86,7 +141,15 @@ function ChoiceSubmenu({role="menuitemradio"aria-checked={activeId === id}className={ROW_CLASS}- onClick={() => onPick(id)}+ onClick={() => {+ hover.settle();+ onPick(id);+ }}+ onMouseEnter={() => hover.start(id)}+ onFocus={() => {+ if (openingFocusRef.current) openingFocusRef.current = false;+ else hover.start(id);+ }}><span className="flex items-center gap-1.5"><span aria-hidden="true" className="w-3 text-center">@@ -98,7 +161,7 @@ function ChoiceSubmenu({);return (- <div className="relative" onMouseEnter={() => show(false)} onMouseLeave={() => setOpen(false)}>+ <div className="relative" onMouseEnter={() => show(false)} onMouseLeave={hideSubmenu}><buttonref={rowRef}type="button"@@ -182,7 +245,8 @@ export function ClipMenuToolItems(props: ClipMenuToolItemsProps) {}function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsProps) {- const { onSetElementAttributeQuiet } = useTimelineEditContextOptional();+ const { onSetElementAttributeQuiet, onSetElementAttributeLive, onRevertElementAttributeLive } =+ useTimelineEditContextOptional();const state = useClipToolState(element);const openCropBar = useCropPresetBarStore((s) => s.open);if (!onSetElementAttributeQuiet) return null;@@ -209,6 +273,14 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPr}if (!isPictureClip(state.tag)) return null;+ const lookPreview =+ onSetElementAttributeLive && onRevertElementAttributeLive+ ? {+ apply: (id: string | null) =>+ onSetElementAttributeLive(element, HF_COLOR_GRADING_ATTR, lookAttrValue(id)),+ clear: () => onRevertElementAttributeLive(element, HF_COLOR_GRADING_ATTR),+ }+ : undefined;return (<><ChoiceSubmenu@@ -216,6 +288,7 @@ function ClipMenuAttributeItems({ group, element, onClose }: ClipMenuToolItemsPrsections={LOOK_SECTIONS}activeId={activeLook(state.colorGrading)}onPick={(id) => write(HF_COLOR_GRADING_ATTR, lookAttrValue(id), "Look")}+ preview={lookPreview}/><buttontype="button"diff --git a/packages/studio/src/player/components/clipPeakMap.ts b/packages/studio/src/player/components/clipPeakMap.tsnew file mode 100644index 0000000000..e6eeaee6bb--- /dev/null+++ b/packages/studio/src/player/components/clipPeakMap.ts@@ -0,0 +1,46 @@+import { buildProjectApiPath } from "../../utils/projectRouting";+import { resolvePreviewRelative } from "../../utils/previewRelativePath";+import type { TimelineElement } from "../store/timelineElement";+import { clipSourcePeak, isPeakMap, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";+import { encodePreviewPath, resolveMediaPreviewUrl } from "./thumbnailUtils";++const peakMapRequests = new Map<string, Promise<PeakMap | null>>();++/** One fetch per peak-map URL per session; a failed or malformed answer reads as null. */+export function loadPeakMap(url: string): Promise<PeakMap | null> {+ const pending = peakMapRequests.get(url);+ if (pending) return pending;+ const request = fetch(url)+ .then((res) => (res.ok ? res.json() : null))+ .then((body: unknown) => (isPeakMap(body) ? body : null))+ .catch(() => null);+ peakMapRequests.set(url, request);+ return request;+}++/** The studio-server `/peaks/*` URL for a clip's project media, or undefined for outside media. */+export function clipPeaksUrl(src: string | undefined, projectId: string): string | undefined {+ const origin = window.location.origin;+ const relative = resolvePreviewRelative(+ resolveMediaPreviewUrl(src ?? "", projectId, origin),+ projectId,+ origin,+ );+ return relative+ ? buildProjectApiPath(projectId, `/peaks/${encodePreviewPath(relative)}`)+ : undefined;+}++export function clipSourceWindow(el: TimelineElement): ClipSourceWindow {+ return { mediaStart: el.playbackStart ?? 0, sourceSpan: el.duration * (el.playbackRate ?? 1) };+}++/** The clip's source peak, linear, over the part it plays; null when it cannot be measured. */+export async function measureClipSourcePeak(+ el: TimelineElement,+ projectId: string,+): Promise<number | null> {+ const url = clipPeaksUrl(el.src, projectId);+ const map = url ? await loadPeakMap(url) : null;+ return map ? clipSourcePeak(map, clipSourceWindow(el)) : null;+}diff --git a/packages/studio/src/player/components/clipPeakRuns.test.ts b/packages/studio/src/player/components/clipPeakRuns.test.tsindex 5aed064218..5a7140e817 100644--- a/packages/studio/src/player/components/clipPeakRuns.test.ts+++ b/packages/studio/src/player/components/clipPeakRuns.test.ts@@ -1,5 +1,5 @@import { describe, expect, it } from "vitest";-import { clipPeakRuns } from "./clipPeakRuns";+import { clipPeakRuns, clipSourcePeak } from "./clipPeakRuns";const map = (bins: number[]) => ({ binSeconds: 1, bins });@@ -36,3 +36,16 @@ describe("clipPeakRuns", () => {expect(clipPeakRuns(map([1]), { mediaStart: 0, sourceSpan: 0 }, 1).runs).toEqual([]);});});++describe("clipSourcePeak", () => {+ it("is the loudest bin inside the played source window only", () => {+ const bins = map([0.9, 0.2, 0.4, 0.3, 1]);+ expect(clipSourcePeak(bins, { mediaStart: 1, sourceSpan: 3 })).toBe(0.4);+ expect(clipSourcePeak(bins, { mediaStart: 0, sourceSpan: 5 })).toBe(1);+ });++ it("is null for an empty window or one past the file's end", () => {+ expect(clipSourcePeak(map([0.5]), { mediaStart: 0, sourceSpan: 0 })).toBeNull();+ expect(clipSourcePeak(map([0.5]), { mediaStart: 4, sourceSpan: 2 })).toBeNull();+ });+});diff --git a/packages/studio/src/player/components/clipPeakRuns.ts b/packages/studio/src/player/components/clipPeakRuns.tsindex 5478d231fc..fdb5088f6f 100644--- a/packages/studio/src/player/components/clipPeakRuns.ts+++ b/packages/studio/src/player/components/clipPeakRuns.ts@@ -48,6 +48,17 @@ export function clipPeakRuns(return { runs, peakDbfs: runs.length > 0 ? 20 * Math.log10(loudest) : null };}+export function clipSourcePeak(map: PeakMap, window: ClipSourceWindow): number | null {+ if (!(window.sourceSpan > 0) || !(map.binSeconds > 0)) return null;+ const first = Math.max(0, Math.floor(window.mediaStart / map.binSeconds));+ const last = Math.min(+ map.bins.length,+ Math.ceil((window.mediaStart + window.sourceSpan) / map.binSeconds),+ );+ if (last <= first) return null;+ return map.bins.slice(first, last).reduce((loudest, bin) => Math.max(loudest, bin), 0);+}+export function isPeakMap(value: unknown): value is PeakMap {if (typeof value !== "object" || value === null) return false;const bins: unknown = Reflect.get(value, "bins");diff --git a/packages/studio/src/player/components/clipToolAttrs.test.ts b/packages/studio/src/player/components/clipToolAttrs.test.tsindex d54d061df8..52a2a0da63 100644--- a/packages/studio/src/player/components/clipToolAttrs.test.ts+++ b/packages/studio/src/player/components/clipToolAttrs.test.ts@@ -5,11 +5,12 @@ import {activeLook,activeVoicePreset,chainWithVoicePreset,+ clipSpeedSuffix,hasCrop,isDucked,+ clipVolumeBadge,lookAttrValue,- readClipBadges,- splitVisibleBadges,+ readClipEffects,type ClipToolState,} from "./clipToolAttrs";@@ -98,7 +99,6 @@ const baseState: ClipToolState = {colorGrading: null,clipPath: null,carve: null,- link: null,};const rampAutomation = JSON.stringify({@@ -114,48 +114,64 @@ const rampAutomation = JSON.stringify({],});-describe("readClipBadges", () => {- it("shows nothing for a plain clip at 100%", () => {- expect(readClipBadges(baseState)).toEqual([]);- });-- it("lists every applied tool in the wireframe's order", () => {- const labels = readClipBadges({- ...baseState,- volume: 1.8,- fxChain: chainWithVoicePreset(null, "voice-clean"),- automation: rampAutomation,- colorGrading: lookAttrValue("warm-daylight"),- clipPath: "inset(0px 20px)",- carve: "{}",- link: "talk",- }).map((b) => b.label);- expect(labels).toEqual([- "Linked",- "Warm daylight",- "Voice: Clean",- "Ramp",- "Crop",- "Ducked",- "180%",- ]);+describe("readClipEffects", () => {+ it("lists nothing for a plain clip, so the fx badge stays grey", () => {+ expect(readClipEffects(baseState)).toEqual([]);+ expect(readClipEffects({ ...baseState, automation: rampAutomation, volume: 1.8 })).toEqual([]);});- it("badges a muted audio clip but not muted b-roll", () => {- expect(readClipBadges({ ...baseState, tag: "audio", muted: true })[0]?.label).toBe("Muted");- expect(readClipBadges({ ...baseState, hasSound: false, muted: true })).toEqual([]);+ it("lists every applied effect in the tooltip's order", () => {+ expect(+ readClipEffects({+ ...baseState,+ fxChain: chainWithVoicePreset(null, "voice-clean"),+ colorGrading: lookAttrValue("warm-daylight"),+ clipPath: "inset(0px 20px)",+ carve: "{}",+ }),+ ).toEqual(["Look: Warm daylight", "Voice: Clean", "Crop", "Ducked"]);});- it("caps at two visible badges plus the link badge", () => {- const badges = readClipBadges({- ...baseState,- link: "talk",- colorGrading: lookAttrValue("mono-clean"),- clipPath: "inset(5px)",- volume: 0.6,+ it("names a hand-added effect and skips disabled and carve-generated nodes", () => {+ const chain = serializeAudioFxChain({+ version: 1,+ nodes: [+ { id: "a", type: "highpass", enabled: true, params: { frequency: 80 } },+ { id: "b", type: "gain", enabled: false, params: {} },+ { id: "c", type: "gain", enabled: true, fromCarve: true, params: {} },+ ],});- const { visible, hidden } = splitVisibleBadges(badges);- expect(visible.map((b) => b.label)).toEqual(["Linked", "Mono", "Crop"]);- expect(hidden.map((b) => b.label)).toEqual(["60%"]);+ const effects = readClipEffects({ ...baseState, fxChain: chain });+ expect(effects).toHaveLength(1);+ expect(effects[0]).not.toBe("highpass");+ });++ it("reads a hand-made grading without a menu preset as a Look", () => {+ expect(readClipEffects({ ...baseState, colorGrading: '{"adjust":{"contrast":0.2}}' })).toEqual([+ "Look",+ ]);+ });+});++describe("clipVolumeBadge", () => {+ it("shows volume off 100% and Muted only on a clip with sound", () => {+ expect(clipVolumeBadge({ ...baseState, volume: 1.8 })).toBe("180%");+ expect(clipVolumeBadge(baseState)).toBeNull();+ expect(clipVolumeBadge({ ...baseState, tag: "audio", muted: true })).toBe("Muted");+ expect(clipVolumeBadge({ ...baseState, hasSound: false, muted: true })).toBeNull();+ });+});++describe("clipSpeedSuffix", () => {+ it("shows a constant speed as a percentage and hides 100%", () => {+ expect(clipSpeedSuffix(1.5, null)).toBe(" [150%]");+ expect(clipSpeedSuffix(0.35, null)).toBe(" [35%]");+ expect(clipSpeedSuffix(1, null)).toBe("");+ expect(clipSpeedSuffix(undefined, null)).toBe("");+ });++ it("shows a rate lane as a ramp, whatever the base rate", () => {+ expect(clipSpeedSuffix(2, rampAutomation)).toBe(" [ramp]");+ expect(clipSpeedSuffix(1, rampAutomation)).toBe(" [ramp]");});});diff --git a/packages/studio/src/player/components/clipToolAttrs.ts b/packages/studio/src/player/components/clipToolAttrs.tsindex e7418b7073..47c782ea47 100644--- a/packages/studio/src/player/components/clipToolAttrs.ts+++ b/packages/studio/src/player/components/clipToolAttrs.ts@@ -4,11 +4,13 @@*/import {+ getAudioFxDef,parseAudioFxChain,serializeAudioFxChain,type HfAudioFxChain,+ type HfAudioFxNode,} from "@hyperframes/core/audio-fx";-import { activeAudioFxPresetIds } from "@hyperframes/core/audio-fx-presets";+import { activeAudioFxPresetIds, getAudioFxPreset } from "@hyperframes/core/audio-fx-presets";import { normalizeHfColorGrading } from "@hyperframes/core/color-grading";import { parseRateLane } from "@hyperframes/core/speed-ramp";import { applyPresetToChain } from "../../components/editor/useApplyAudioFxPreset";@@ -117,6 +119,17 @@ function hasRateRamp(rawAutomation: string | null | undefined): boolean {return parseRateLane(rawAutomation) !== null;}+/** Premiere's speed cue on the clip name: ` [ramp]` under a rate lane, else ` [150%]` off 100%. */+export function clipSpeedSuffix(+ playbackRate: number | null | undefined,+ rawAutomation: string | null | undefined,+): string {+ if (hasRateRamp(rawAutomation)) return " [ramp]";+ const rate = playbackRate ?? 1;+ if (!Number.isFinite(rate) || Math.abs(rate - 1) < 0.005) return "";+ return ` [${Math.round(rate * 100)}%]`;+}+const ZERO_INSET = /^inset\(\s*0(px|%)?\s*\)$/i;export function hasCrop(clipPath: string | null | undefined): boolean {@@ -124,13 +137,6 @@ export function hasCrop(clipPath: string | null | undefined): boolean {return value !== "" && value !== "none" && !ZERO_INSET.test(value);}-export type ClipBadgeKind = "link" | "look" | "voice" | "ramp" | "crop" | "ducked" | "volume";--export interface ClipBadge {- kind: ClipBadgeKind;- label: string;-}-/** What a clip's attributes say is applied; the element's own attributes, as read off its node. */export interface ClipToolState {tag: string;@@ -142,46 +148,43 @@ export interface ClipToolState {colorGrading: string | null;clipPath: string | null;carve: string | null;- link: string | null;}-function volumeBadge(state: ClipToolState): ClipBadge | null {- const isAudio = state.tag === "audio";- if (!isAudio && !state.hasSound) return null;- if (state.muted) return { kind: "volume", label: "Muted" };+export function clipVolumeBadge(state: ClipToolState): string | null {+ if (state.tag !== "audio" && !state.hasSound) return null;+ if (state.muted) return "Muted";const volume = state.volume ?? 1;if (Math.abs(volume - 1) < 0.005) return null;- return { kind: "volume", label: `${Math.round(volume * 100)}%` };-}--/** Badges in the wireframe's order: look, voice, ramp, crop, ducked, volume. The link badge leads. */-export function readClipBadges(state: ClipToolState): ClipBadge[] {- const look = lookLabel(activeLook(state.colorGrading));- const voice = voicePresetLabel(activeVoicePreset(state.fxChain));- const volume = volumeBadge(state);- const badges: Array<ClipBadge | null> = [- state.link ? { kind: "link", label: "Linked" } : null,- look ? { kind: "look", label: look } : null,- voice ? { kind: "voice", label: `Voice: ${voice}` } : null,- hasRateRamp(state.automation) ? { kind: "ramp", label: "Ramp" } : null,- hasCrop(state.clipPath) ? { kind: "crop", label: "Crop" } : null,- isDucked(state.carve) ? { kind: "ducked", label: "Ducked" } : null,- volume,+ return `${Math.round(volume * 100)}%`;+}++function lookEffect(rawGrading: string | null): string | null {+ const grading = normalizeHfColorGrading(parseJson(rawGrading));+ if (!grading) return null;+ const label = lookLabel(grading.preset ?? null);+ return label ? `Look: ${label}` : "Look";+}++function presetEffect(presetId: string): string {+ const voice = voicePresetLabel(presetId);+ return voice ? `Voice: ${voice}` : (getAudioFxPreset(presetId)?.label ?? presetId);+}++function chainNodeEffect(node: HfAudioFxNode): string | null {+ if (node.enabled === false || node.fromCarve) return null;+ if (node.fromPreset) return presetEffect(node.fromPreset);+ if (node.fromEq) return "EQ";+ if (node.fromLeveller) return "Leveller";+ return node.label ?? getAudioFxDef(node.type)?.label ?? node.type;+}++/** Every effect on the clip, in the fx badge tooltip's order; empty means a grey badge. */+export function readClipEffects(state: ClipToolState): string[] {+ const effects: Array<string | null> = [+ lookEffect(state.colorGrading),+ ...parseChainOrEmpty(state.fxChain).nodes.map(chainNodeEffect),+ hasCrop(state.clipPath) ? "Crop" : null,+ isDucked(state.carve) ? "Ducked" : null,];- return badges.filter((badge): badge is ClipBadge => badge !== null);-}--const MAX_VISIBLE_BADGES = 2;--/** The link badge is always shown; the rest cap at two, then `+N`. */-export function splitVisibleBadges(badges: readonly ClipBadge[]): {- visible: ClipBadge[];- hidden: ClipBadge[];-} {- const link = badges.filter((badge) => badge.kind === "link");- const rest = badges.filter((badge) => badge.kind !== "link");- return {- visible: [...link, ...rest.slice(0, MAX_VISIBLE_BADGES)],- hidden: rest.slice(MAX_VISIBLE_BADGES),- };+ return [...new Set(effects.filter((effect): effect is string => effect !== null))];}diff --git a/packages/studio/src/player/components/studioShortcuts.ts b/packages/studio/src/player/components/studioShortcuts.tsindex 94334f302d..ea8216c0cb 100644--- a/packages/studio/src/player/components/studioShortcuts.ts+++ b/packages/studio/src/player/components/studioShortcuts.ts@@ -4,6 +4,7 @@ export const STUDIO_PLAIN_KEYS = {split: "s",record: "r",addKeyframe: "k",+ audioGain: "g",} as const;export interface ShortcutHint {@@ -51,6 +52,7 @@ export const DEFAULT_SHORTCUT_SECTIONS: readonly ShortcutSection[] = [{ key: "⌘V", label: "Paste element" },{ key: "⌘X", label: "Cut element" },{ key: hintKey(STUDIO_PLAIN_KEYS.split), label: "Split clip at playhead" },+ { key: hintKey(STUDIO_PLAIN_KEYS.audioGain), label: "Audio Gain for clips with sound" },{ key: "⇧Click", label: "Razor tool: split all tracks" },{ key: "[", label: "Select clips starting before the playhead" },{ key: "]", label: "Select clips running at or after the playhead" },diff --git a/packages/studio/src/player/components/timelineCallbacks.ts b/packages/studio/src/player/components/timelineCallbacks.tsindex 56b96dacc8..bfaf084270 100644--- a/packages/studio/src/player/components/timelineCallbacks.ts+++ b/packages/studio/src/player/components/timelineCallbacks.ts@@ -122,6 +122,12 @@ export interface TimelineEditCallbacks {value: string | null,label: string,) => Promise<TimelineEditOutcome | void>;+ /** One attribute on several clips, saved as one undo step. */+ onSetElementsAttributeQuiet?: (+ edits: ReadonlyArray<{ element: TimelineElement; value: string | null }>,+ attr: string,+ label: string,+ ) => Promise<TimelineEditOutcome | void>;onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;onLinkEdit?: (edit: TimelineLinkEdit) => Promise<void> | void;onDeleteElementOnly?: (element: TimelineElement) => Promise<void> | void;diff --git a/packages/studio/src/player/components/timelineClipDragPreview.test.ts b/packages/studio/src/player/components/timelineClipDragPreview.test.tsindex f1be7cbb43..1b0b18b8f4 100644--- a/packages/studio/src/player/components/timelineClipDragPreview.test.ts+++ b/packages/studio/src/player/components/timelineClipDragPreview.test.ts@@ -726,3 +726,99 @@ describe("a nested clip's drop stops at its host's start in the preview", () =>expect(await saved(early, 1)).toBe(1);});});++describe("an audio clip stays inside its partner video", () => {+ const video = (extra: Partial<TimelineElement> = {}) => ({+ ...clip("v", 0, 10, 20, 1),+ syncOrigin: "lk-1",+ ...extra,+ });+ const audio = (extra: Partial<TimelineElement> = {}) => ({+ ...clip("a", 1, 12, 8, 0, "audio"),+ syncOrigin: "lk-1",+ ...extra,+ });+ const audioCtx = (elements: TimelineElement[], selected: string[] = []) => ({+ ...ctx(undefined, elements),+ trackOrder: [0, 1],+ audioTracks: new Set([1]),+ selectedKeys: new Set(selected),+ });++ it("a drag past the video's end stops with the audio's end on it", () => {+ const a = audio();+ const { drag, clientX, clientY } = horizontalDrag(a, 1.5, 30);+ const next = computeDragPreview(drag, clientX, clientY, audioCtx([video(), a]));+ expect(next.previewStart).toBe(22);+ expect(next.pointerClientX).toBe(drag.originClientX + 10 * PPS);+ });++ it("a drag before the video's start stops at it, linked or same-source", () => {+ const linked = audio({ syncOrigin: undefined, link: "lk-9" });+ const { drag, clientX, clientY } = horizontalDrag(linked, 1.5, -10);+ const elements = [video({ syncOrigin: undefined, link: "lk-9" }), linked];+ expect(computeDragPreview(drag, clientX, clientY, audioCtx(elements)).previewStart).toBe(10);+ });++ it("moves freely with no partner video, or when the video moves with it", () => {+ const loose = audio({ syncOrigin: undefined });+ const free = horizontalDrag(loose, 1.5, 30);+ expect(+ computeDragPreview(free.drag, free.clientX, free.clientY, audioCtx([video(), loose]))+ .previewStart,+ ).toBe(42);+ const a = audio();+ const both = horizontalDrag(a, 1.5, 30);+ expect(+ computeDragPreview(both.drag, both.clientX, both.clientY, audioCtx([video(), a], ["v", "a"]))+ .previewStart,+ ).toBe(42);+ });++ it("rejects a drop that collision placement would push outside the video", () => {+ const a = audio();+ const obstacle = clip("o", 1, 20, 10, 0, "audio");+ const { drag, clientX, clientY } = horizontalDrag(a, 1.5, 10);+ const next = computeDragPreview(drag, clientX, clientY, audioCtx([video(), a, obstacle]));+ expect(next.previewStart).toBeGreaterThanOrEqual(10);+ expect(next.previewStart + a.duration).toBeLessThanOrEqual(30);+ });++ it("keeps an audio carried in a multi-selection inside its video", () => {+ const a = audio();+ const title = clip("t", 0, 40, 4, 0, "text");+ const { drag, clientX, clientY } = horizontalDrag(title, 0.5, 30);+ const elements = [video(), a, title];+ const next = computeDragPreview(drag, clientX, clientY, audioCtx(elements, ["t", "a"]));+ expect(next.previewStart).toBe(50);+ });++ const trim = (edge: "start" | "end", deltaSeconds: number, gestureKeys: string[] = []) =>+ computeResizePreview(+ {+ element: audio({ sourceDuration: 100, playbackStart: 20 }),+ edge,+ originClientX: 0,+ previewStart: 12,+ previewDuration: 8,+ started: true,+ },+ deltaSeconds * 100,+ {+ scroll: fakeScroll(),+ pps: 100,+ buildSnapTargets: () => [],+ elements: [video(), audio()],+ gestureKeys: new Set(["a", ...gestureKeys]),+ },+ );++ it("a trim cannot extend past the video's start or end", () => {+ expect(trim("end", 50)).toMatchObject({ previewStart: 12, previewDuration: 18 });+ expect(trim("start", -10)).toMatchObject({ previewStart: 10, previewDuration: 10 });+ });++ it("a trim carried by the video too is not held to the video's old span", () => {+ expect(trim("end", 50, ["v"]).previewDuration).toBe(58);+ });+});diff --git a/packages/studio/src/player/components/timelineClipDragPreview.ts b/packages/studio/src/player/components/timelineClipDragPreview.tsindex 52668e7af7..8275c78b95 100644--- a/packages/studio/src/player/components/timelineClipDragPreview.ts+++ b/packages/studio/src/player/components/timelineClipDragPreview.ts@@ -23,6 +23,7 @@ import {import { groupMoveFloor, resolveGroupMovers } from "./timelineMultiDragPreview";import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";import { STUDIO_PREVIEW_FPS } from "../lib/time";+import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";/** Snap-target builder closure supplied by the hook (closes over refs + store). */type BuildSnapTargets = (@@ -111,6 +112,7 @@ interface GroupDrag {obstacles: TimelineElement[];/** Lowest start the grabbed clip may take (see groupMoveFloor). */floor: number;+ moving: ReadonlySet<string>;}function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): GroupDrag {@@ -119,14 +121,20 @@ function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): Grouctx.selectedKeys,drag.element.key ?? drag.element.id,);- if (!movers) return { obstacles: ctx.elements, floor: groupMoveFloor(drag.element, []) };+ if (!movers) {+ const moving = new Set([drag.element.key ?? drag.element.id]);+ return { obstacles: ctx.elements, floor: groupMoveFloor(drag.element, []), moving };+ }const moving = new Set(movers.map((e) => e.key ?? e.id));return {obstacles: ctx.elements.filter((e) => !moving.has(e.key ?? e.id)),floor: groupMoveFloor(drag.element, movers),+ moving,};}+const SHIFT_EPSILON_S = 1e-6;+/** Recompute the dragged-clip preview (move + snap + group clamp + drop placement). */export function computeDragPreview(drag: DraggedClipState,@@ -179,13 +187,25 @@ export function computeDragPreview();// A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.const group = resolveGroupDrag(drag, ctx);- const previewStart = Math.max(snap.start, group.floor);+ const dragKey = drag.element.key ?? drag.element.id;+ const passengers = ctx.elements.filter(+ (el) => (el.key ?? el.id) !== dragKey && group.moving.has(el.key ?? el.id),+ );+ const movers = [drag.element, ...passengers];+ const shift = heldAudioShiftRange(movers, ctx.elements, group.moving);+ const origin = drag.element.start;+ const floored = Math.max(snap.start, group.floor);+ const previewStart = origin + Math.max(shift.min, Math.min(floored - origin, shift.max));const placement = resolveDropPlacement(drag, clientY, previewStart, nextMove.track, ctx, group);+ const placedShift = placement.start - origin;+ if (placedShift < shift.min - SHIFT_EPSILON_S || placedShift > shift.max + SHIFT_EPSILON_S) {+ return { ...drag, started: true };+ }const { track: previewTrack, insertRow } = placement;return {...drag,started: true,- pointerClientX: clientX,+ pointerClientX: clientX - (floored - previewStart) * pps,pointerClientY: clientY,previewStart: placement.start,previewTrack,@@ -210,6 +230,8 @@ export interface ResizePreviewContext {scroll: HTMLDivElement | null;pps: number;buildSnapTargets: BuildSnapTargets;+ elements?: readonly TimelineElement[];+ gestureKeys?: ReadonlySet<string>;}export interface ResizePreviewResult {@@ -253,14 +275,18 @@ export function computeResizePreview(// rightward and, after a far move, collapsed a clip to the sliver between its// start and the comp end (the 8s→0.95s audio incident). Images/text/shapes// have no source, so they extend freely.- const maxEnd = resize.element.start + sourceRemaining;+ const video = ctx.elements+ ? heldPartnerVideoBounds(resize.element, ctx.elements, ctx.gestureKeys ?? new Set())+ : null;+ const minStart = Math.max(clampToHostStart(resize.element, 0), video?.start ?? 0);+ const maxEnd = Math.min(resize.element.start + sourceRemaining, video?.end ?? Infinity);let nextResize = resolveTimelineResize({start: resize.element.start,duration: resize.element.duration,originClientX: resize.originClientX,pixelsPerSecond: pps,- minStart: clampToHostStart(resize.element, 0),+ minStart,maxEnd,playbackStart:resize.edge === "start" && canSeedPlaybackStart@@ -303,8 +329,7 @@ export function computeResizePreview(const { time: snapped, target } = snapTimelineTime(nextResize.start, trimTargets, snapSecs);const clip = { ...nextResize, playbackRate: resize.element.playbackRate };const delta = snapped - nextResize.start;- const floor = clampToHostStart(resize.element, 0);- const bounds = clipStartTrimDeltaBounds(clip, floor, resolveTimelineMinDuration());+ const bounds = clipStartTrimDeltaBounds(clip, minStart, resolveTimelineMinDuration());if (target && delta >= bounds.minDelta - 1e-6 && delta <= bounds.maxDelta + 1e-6) {if (snapped !== nextResize.start) nextResize = applyClipStartTrimDelta(clip, delta);snap = target;diff --git a/packages/studio/src/player/components/timelineClipGestureHandlers.ts b/packages/studio/src/player/components/timelineClipGestureHandlers.tsindex 885d3692cf..4d69d460fb 100644--- a/packages/studio/src/player/components/timelineClipGestureHandlers.ts+++ b/packages/studio/src/player/components/timelineClipGestureHandlers.ts@@ -8,7 +8,7 @@ import {import type { TimelineEditCapabilities } from "./timelineEditCapabilities";import type { TimelineEditCallbacks } from "./timelineCallbacks";import { CLIP_HANDLE_W } from "./timelineLayout";-import { selectClipWithLinks } from "./timelineLinkSelection";+import { selectClipWithLinks, toggleClipWithLinks } from "./timelineLinkSelection";import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";export interface ClipGestureDeps {@@ -18,11 +18,6 @@ export interface ClipGestureDeps {onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;onRazorSplitAll?: (splitTime: number) => Promise<void> | void;blockedClipRef: React.RefObject<BlockedClipState | null>;- shiftClickClipRef: React.RefObject<{- element: TimelineElement;- anchorX: number;- anchorY: number;- } | null>;suppressClickRef: React.RefObject<boolean>;scrollRef: React.RefObject<HTMLDivElement | null>;setShowPopover(v: boolean): void;@@ -45,9 +40,11 @@ function canStartResize(return capabilities.canTrimEnd;}+const isAdditiveClick = (e: { shiftKey: boolean; metaKey: boolean; ctrlKey: boolean }) =>+ e.shiftKey || e.metaKey || e.ctrlKey;+type PointerDownAction =| { kind: "ignore" }- | { kind: "arm-shift-click" }| { kind: "block"; intent: BlockedTimelineEditIntent; rect: DOMRect }| { kind: "move"; rect: DOMRect };@@ -82,7 +79,7 @@ function resolvePointerDownAction(): PointerDownAction {if (e.button !== 0) return { kind: "ignore" };if (usePlayerStore.getState().activeTool === "razor") return { kind: "ignore" };- if (e.shiftKey) return { kind: "arm-shift-click" };+ if (isAdditiveClick(e)) return { kind: "ignore" };const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();const intent = resolveBlockedTimelineEditIntent({@@ -119,7 +116,6 @@ export function createClipGestureHandlers(onRazorSplit,onRazorSplitAll,blockedClipRef,- shiftClickClipRef,suppressClickRef,scrollRef,setShowPopover,@@ -154,11 +150,6 @@ export function createClipGestureHandlers(const action = resolvePointerDownAction(e, capabilities, onResizeElement, onMoveElement);if (action.kind === "ignore") return;- if (action.kind === "arm-shift-click") {- shiftClickClipRef.current = { element: el, anchorX: e.clientX, anchorY: e.clientY };- return;- }-if (action.kind === "block") {blockedClipRef.current = {pointerId: e.pointerId,@@ -197,26 +188,30 @@ export function createClipGestureHandlers(});};+ const razorSplit = (e: ReactMouseEvent, split: NonNullable<typeof onRazorSplit>): void => {+ const clipRect = (e.currentTarget as HTMLElement).getBoundingClientRect();+ const splitTime = previewElement.start + (e.clientX - clipRect.left) / pps;+ const clampedTime = Math.max(+ previewElement.start + SPLIT_BOUNDARY_EPSILON_S,+ Math.min(+ previewElement.start + previewElement.duration - SPLIT_BOUNDARY_EPSILON_S,+ splitTime,+ ),+ );+ if (e.shiftKey && onRazorSplitAll) onRazorSplitAll(clampedTime);+ else split(el, clampedTime);+ };+const onClick = (e: ReactMouseEvent): void => {e.stopPropagation();if (suppressClickRef.current) return;- const { activeTool } = usePlayerStore.getState();- if (activeTool === "razor" && onRazorSplit) {- const clipRect = (e.currentTarget as HTMLElement).getBoundingClientRect();- const clickOffsetX = e.clientX - clipRect.left;- const splitTime = previewElement.start + clickOffsetX / pps;- const clampedTime = Math.max(- previewElement.start + SPLIT_BOUNDARY_EPSILON_S,- Math.min(- previewElement.start + previewElement.duration - SPLIT_BOUNDARY_EPSILON_S,- splitTime,- ),- );- if (e.shiftKey && onRazorSplitAll) {- onRazorSplitAll(clampedTime);- } else {- onRazorSplit(el, clampedTime);- }+ if (usePlayerStore.getState().activeTool === "razor" && onRazorSplit) {+ razorSplit(e, onRazorSplit);+ return;+ }+ if (isAdditiveClick(e)) {+ const primary = toggleClipWithLinks(elementKey, e.altKey);+ onSelectElement?.(primary);return;}// Clip selection is idempotent; empty timeline space owns deselection.diff --git a/packages/studio/src/player/components/timelineEditing.test.ts b/packages/studio/src/player/components/timelineEditing.test.tsindex 638ab1f6de..534163f047 100644--- a/packages/studio/src/player/components/timelineEditing.test.ts+++ b/packages/studio/src/player/components/timelineEditing.test.ts@@ -1,6 +1,5 @@import { describe, expect, it } from "vitest";import {- buildClipRangeSelection,buildPromptCopyText,buildTimelineElementAgentPrompt,buildTimelineAgentPrompt,@@ -607,18 +606,6 @@ describe("resolveBlockedTimelineEditIntent", () => {});});-describe("buildClipRangeSelection", () => {- it("anchors the full clip range at the click position", () => {- expect(- buildClipRangeSelection({ start: 1.25, duration: 3.5 }, { anchorX: 320, anchorY: 180 }),- ).toEqual({- start: 1.25,- end: 4.75,- anchorX: 320,- anchorY: 180,- });- });-});describe("resolveTimelineAutoScroll", () => {it("does not scroll when the pointer stays away from the edges", () => {expect(diff --git a/packages/studio/src/player/components/timelineEditing.ts b/packages/studio/src/player/components/timelineEditing.tsindex c5d471db0c..e6cea2885a 100644--- a/packages/studio/src/player/components/timelineEditing.ts+++ b/packages/studio/src/player/components/timelineEditing.ts@@ -382,17 +382,6 @@ export function resolveBlockedTimelineEditIntent(input: {return "move";}-export function buildClipRangeSelection(- clip: { start: number; duration: number },- anchor: { anchorX: number; anchorY: number },-): TimelineRangeSelection {- return {- start: clip.start,- end: clip.start + clip.duration,- anchorX: anchor.anchorX,- anchorY: anchor.anchorY,- };-}export function buildTimelineAgentPrompt({rangeStart,rangeEnd,diff --git a/packages/studio/src/player/components/timelineLaneProps.ts b/packages/studio/src/player/components/timelineLaneProps.tsindex f0299256cc..a2893929d5 100644--- a/packages/studio/src/player/components/timelineLaneProps.ts+++ b/packages/studio/src/player/components/timelineLaneProps.ts@@ -66,11 +66,6 @@ export interface TimelineLaneBaseProps {setResizingClip: (v: ResizingClipState | null) => void;setDraggedClip: (v: DraggedClipState | null) => void;setSelectedElementId: (id: string | null) => void;- shiftClickClipRef: React.RefObject<{- element: TimelineElement;- anchorX: number;- anchorY: number;- } | null>;getPreviewElement: (element: TimelineElement) => TimelineElement;getTrackStyle: (tag: string) => TrackVisualStyle;keyframeCache?: Map<string, KeyframeCacheEntry>;diff --git a/packages/studio/src/player/components/timelineLinkSelection.ts b/packages/studio/src/player/components/timelineLinkSelection.tsindex 231ee2df94..3d5db3de61 100644--- a/packages/studio/src/player/components/timelineLinkSelection.ts+++ b/packages/studio/src/player/components/timelineLinkSelection.ts@@ -1,5 +1,5 @@-import { usePlayerStore } from "../store/playerStore";-import { expandToLinkedMembers } from "./audioClipLink";+import { usePlayerStore, type TimelineElement } from "../store/playerStore";+import { expandToLinkedMembers, linkedMembersOf } from "./audioClipLink";import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";/**@@ -21,3 +21,21 @@ export function selectClipWithLinks(const expanded = expandToLinkedMembers(selectedElementIds, elements);if (expanded.size > selectedElementIds.size) state.setSelection(expanded, key);}++export function toggleClipWithLinks(key: string, altKey: boolean): TimelineElement | null {+ const state = usePlayerStore.getState();+ const element = state.elements.find((el) => (el.key ?? el.id) === key);+ const members = element+ ? linkedMembersOf(element, state.elements, !altKey && isLinkedSelectionOn())+ : [];+ const memberKeys = members.length > 0 ? members.map((el) => el.key ?? el.id) : [key];+ const next = new Set(state.selectedElementIds);+ const removing = next.has(key);+ for (const memberKey of memberKeys) {+ if (removing) next.delete(memberKey);+ else next.add(memberKey);+ }+ state.setSelection(next, removing ? state.selectedElementId : key);+ const primary = usePlayerStore.getState().selectedElementId;+ return state.elements.find((el) => (el.key ?? el.id) === primary) ?? null;+}diff --git a/packages/studio/src/player/components/useClipToolState.ts b/packages/studio/src/player/components/useClipToolState.tsindex 364ce9585e..b99c91fcc7 100644--- a/packages/studio/src/player/components/useClipToolState.ts+++ b/packages/studio/src/player/components/useClipToolState.ts@@ -11,14 +11,11 @@ import { committedClipPath } from "../../components/editor/cropPresetStore";import { isAudibleVideoNode } from "../lib/timelineElementHelpers";import type { ClipToolState } from "./clipToolAttrs";-const LINK_ATTR = "data-link";-const WATCHED_ATTRS = [HF_AUDIO_FX_ATTR,HF_AUDIO_AUTOMATION_ATTR,HF_AUDIO_CARVE_ATTR,HF_COLOR_GRADING_ATTR,- LINK_ATTR,"data-volume","data-has-audio","muted",@@ -42,7 +39,6 @@ function toolStateFromNode(node: Element): ClipToolState {colorGrading: node.getAttribute(HF_COLOR_GRADING_ATTR),clipPath: committedClipPath(node),carve: node.getAttribute(HF_AUDIO_CARVE_ATTR),- link: node.getAttribute(LINK_ATTR),};}@@ -58,7 +54,6 @@ function toolStateFromElement(el: TimelineElement): ClipToolState {colorGrading: null,clipPath: null,carve: null,- link: null,};}diff --git a/packages/studio/src/player/components/useTimelineClipDrag.ts b/packages/studio/src/player/components/useTimelineClipDrag.tsindex 327e1ca247..65772912a5 100644--- a/packages/studio/src/player/components/useTimelineClipDrag.ts+++ b/packages/studio/src/player/components/useTimelineClipDrag.ts@@ -27,7 +27,7 @@ import type {BlockedClipState,} from "./timelineClipDragTypes";import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";-import { linkedGestureKeys } from "./audioClipLink";+import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";import type { TimelineRowGeometry } from "./timelineLayout";import {@@ -242,12 +242,17 @@ export function useTimelineClipDrag({return;}beginGesture("resize", next.pointerId);- gestureSelectedKeysRef.current = linkedGestureKeys(- gestureSelectedKeysRef.current,+ gestureSelectedKeysRef.current = dropMisalignedTrimPartners(+ linkedGestureKeys(+ gestureSelectedKeysRef.current,+ next.element,+ elementsRef.current,+ next.altKey === true,+ isLinkedSelectionOn(),+ ),next.element,elementsRef.current,- next.altKey === true,- isLinkedSelectionOn(),+ next.edge,);publishResizingClip(next);},@@ -324,6 +329,8 @@ export function useTimelineClipDrag({scroll: scrollRef.current,pps: ppsRef.current,buildSnapTargets,+ elements: elementsRef.current,+ gestureKeys: gestureSelectedKeysRef.current,});trimSeekOriginRef.current ??= usePlayerStore.getState().currentTime;const setResizeState = (v: ResizePreviewResult) => {diff --git a/packages/studio/src/player/components/useTimelineOverlaysState.ts b/packages/studio/src/player/components/useTimelineOverlaysState.tsindex 15acbdc36c..dbdc498e29 100644--- a/packages/studio/src/player/components/useTimelineOverlaysState.ts+++ b/packages/studio/src/player/components/useTimelineOverlaysState.ts@@ -32,7 +32,6 @@ type OverlayStateInputs = Omit<export type TimelineOverlaysStateResult = {overlays: TimelineOverlaysState;- shiftClickClipRef: ReturnType<typeof useTimelineRangeSelection>["shiftClickClipRef"];marqueeRect: ReturnType<typeof useTimelineRangeSelection>["marqueeRect"];isScrubbing: ReturnType<typeof useTimelineRangeSelection>["isScrubbing"];handlePointerDown: ReturnType<typeof useTimelineRangeSelection>["handlePointerDown"];@@ -55,7 +54,6 @@ export function useTimelineOverlaysState({const {rangeSelection,setRangeSelection,- shiftClickClipRef,marqueeRect,isScrubbing,handlePointerDown,@@ -86,7 +84,6 @@ export function useTimelineOverlaysState({onCloseAllTrackGaps: gap.closeAllTrackGaps,onHoverGapAction: gap.setHoveredGapAction,},- shiftClickClipRef,marqueeRect,isScrubbing,handlePointerDown,diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsxindex bb67de3585..d5c9d461a5 100644--- a/packages/studio/src/player/components/useTimelineProviderState.tsx+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx@@ -420,7 +420,6 @@ export function useTimelineProviderState({gapHighlight,openGapMenu,onContextMenuClip,- shiftClickClipRef,marqueeRect,isScrubbing,handlePointerDown,@@ -503,7 +502,6 @@ export function useTimelineProviderState({setResizingClip,setDraggedClip,setSelectedElementId,- shiftClickClipRef,getPreviewElement,getTrackStyle,keyframeCache,diff --git a/packages/studio/src/player/components/useTimelineRangeSelection.ts b/packages/studio/src/player/components/useTimelineRangeSelection.tsindex 3213548a99..efa232698f 100644--- a/packages/studio/src/player/components/useTimelineRangeSelection.ts+++ b/packages/studio/src/player/components/useTimelineRangeSelection.ts@@ -1,6 +1,5 @@import { useRef, useState, useCallback, useEffect } from "react";import {- buildClipRangeSelection,applyTimelineAutoScrollStep,resolveTimelineAutoScrollLoopAction,type TimelineRangeSelection,@@ -149,11 +148,6 @@ export function useTimelineRangeSelection({// rendering). Drives the playhead head's filled-vs-hollow state.const [isScrubbing, setIsScrubbing] = useState(false);const [rangeSelection, setRangeSelection] = useState<TimelineRangeSelection | null>(null);- const shiftClickClipRef = useRef<{- element: TimelineElement;- anchorX: number;- anchorY: number;- } | null>(null);const seekRafRef = useRef(0);const pendingClientXRef = useRef(0);@@ -322,7 +316,6 @@ export function useTimelineRangeSelection({beginRangeSelection(e);return;}- shiftClickClipRef.current = null;if ((e.target as HTMLElement).closest("[data-clip]")) return;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);activePointerIdRef.current = e.pointerId;@@ -427,13 +420,7 @@ export function useTimelineRangeSelection({// clip range), otherwise clear it.const finishRangeSelection = useCallback(() => {isRangeSelecting.current = false;- const pendingShiftClick = shiftClickClipRef.current;- shiftClickClipRef.current = null;setRangeSelection((prev) => {- if (prev && pendingShiftClick && Math.abs(prev.end - prev.start) <= 0.2) {- setShowPopover(true);- return buildClipRangeSelection(pendingShiftClick.element, pendingShiftClick);- }if (prev && Math.abs(prev.end - prev.start) > 0.2) {setShowPopover(true);return prev;@@ -589,7 +576,6 @@ export function useTimelineRangeSelection({return {rangeSelection,setRangeSelection,- shiftClickClipRef,marqueeRect,isScrubbing,handlePointerDown,diff --git a/packages/studio/src/utils/sdkCutover.linkedTiming.test.ts b/packages/studio/src/utils/sdkCutover.linkedTiming.test.tsnew file mode 100644index 0000000000..414b43f04d--- /dev/null+++ b/packages/studio/src/utils/sdkCutover.linkedTiming.test.ts@@ -0,0 +1,52 @@+import { describe, expect, it, vi } from "vitest";+import { openComposition } from "@hyperframes/sdk";+import { cutoverCommittedOrThrow, sdkTimingBatchPersist } from "./sdkCutover";+import { getStudioSaveErrorMessage } from "./studioSaveDiagnostics";++vi.mock("../components/editor/manualEditingAvailability", () => ({+ STUDIO_SDK_CUTOVER_ENABLED: true,+ STUDIO_SDK_RESOLVER_SHADOW_ENABLED: false,+}));+vi.mock("./studioTelemetry", () => ({+ trackStudioEvent: vi.fn(),+}));++const OFFSET_LINKED_HTML = `+<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px" data-duration="10">+ <video data-hf-id="hf-talk" src="talk.mp4" muted data-link="lk-1" data-start="2" data-duration="6" data-track-index="0"></video>+ <audio data-hf-id="hf-talk-audio" src="talk.mp4" data-link="lk-1" data-start="3" data-duration="5" data-track-index="2"></audio>+</div>+`.trim();++describe("a linked trim the SDK refuses", () => {+ it("fails the cutover with the SDK's reason, which the resize toast shows, and writes nothing", async () => {+ const session = await openComposition(OFFSET_LINKED_HTML);+ const before = session.serialize();+ const deps = {+ editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },+ writeProjectFile: vi.fn().mockResolvedValue(undefined),+ reloadPreview: vi.fn(),+ publishSession: vi.fn(),+ createCandidateSession: async () => session,+ };+ const result = await sdkTimingBatchPersist(+ [{ hfId: "hf-talk", timingUpdate: { start: 2, duration: 0.5 } }],+ "index.html",+ session,+ deps,+ );+ expect(result.status).toBe("failed");+ let thrown: unknown;+ try {+ cutoverCommittedOrThrow(result);+ } catch (error) {+ thrown = error;+ }+ expect(getStudioSaveErrorMessage(thrown)).toBe(+ "Linked audio would start after the new end — unlink or trim the audio first.",+ );+ expect(deps.writeProjectFile).not.toHaveBeenCalled();+ expect(deps.editHistory.recordEdit).not.toHaveBeenCalled();+ expect(session.serialize()).toBe(before);+ });+});diff --git a/packages/studio/src/utils/typingTarget.test.ts b/packages/studio/src/utils/typingTarget.test.tsindex d39528a5d6..86812349a9 100644--- a/packages/studio/src/utils/typingTarget.test.ts+++ b/packages/studio/src/utils/typingTarget.test.ts@@ -54,6 +54,14 @@ describe("isTypingTarget", () => {expect(isTypingTarget(mount('<h1 contenteditable="false">Hi</h1>'))).toBe(false);});+ it("keeps a modal dialog's buttons out of the global shortcuts", () => {+ const host = mount('<div role="dialog" aria-modal="true"><button>OK</button></div>');+ expect(isTypingTarget(host.querySelector("button"))).toBe(true);+ expect(+ isTypingTarget(mount('<div role="dialog"><button>OK</button></div>').querySelector("button")),+ ).toBe(false);+ });+it("says no to nothing at all", () => {expect(isTypingTarget(null)).toBe(false);expect(isTypingTarget({} as EventTarget)).toBe(false);diff --git a/packages/studio/src/utils/typingTarget.ts b/packages/studio/src/utils/typingTarget.tsindex 23d6c27008..a21094b69c 100644--- a/packages/studio/src/utils/typingTarget.ts+++ b/packages/studio/src/utils/typingTarget.ts@@ -45,6 +45,7 @@ const TYPING_SELECTOR = [// `input` and matched above. Without this row the shared Toggle would let a// global shortcut claim Space instead of flipping the control (KTD13)."[role='switch']",+ "[role='dialog'][aria-modal='true']",".cm-editor",].join(",");diff --git a/skills-manifest.json b/skills-manifest.jsonindex bfe3e58016..27cc9fe3c6 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -34,7 +34,7 @@"files": 11},"hyperframes-core": {- "hash": "539de2110ccdaa43",+ "hash": "96756e9138ed43d9","files": 11},"hyperframes-creative": {diff --git a/skills/hyperframes-core/references/data-attributes.md b/skills/hyperframes-core/references/data-attributes.mdindex 83d9943707..eb1b485f94 100644--- a/skills/hyperframes-core/references/data-attributes.md+++ b/skills/hyperframes-core/references/data-attributes.md@@ -36,7 +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). |+| `data-sync-origin` | No | Editing contract only: a video and audio from one source file share it (written by Detach, and by Link for same-file pairs; 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 72b1a51f49..2e9f3ffdde 100644--- a/skills/hyperframes-core/references/tracks-and-clips.md+++ b/skills/hyperframes-core/references/tracks-and-clips.md@@ -76,11 +76,12 @@ Each video segment keeps its sound: the sound stays on the clip (`data-has-audio></audio>```+- **Link offer.** Studio offers Link for exactly one video and one audio, neither already linked; their timing and source file don't matter. A linked pair that is offset moves together (the offset is kept), and a trim carries to the partner only when its edge sits at the same time. Merge back needs the same file and an in-sync pair.- **Keep members in sync.** Every member needs the same `data-start`, `data-duration`, `data-media-start` (absent = 0) and `data-playback-rate` (absent = 1). Track index, volume, fades and FX may differ. When you retime one member by hand, retime all of them, or `lint` warns `linked_clips_out_of_sync`.- **Unlink** by removing `data-link` from every member. Removing it from one leaves the other alone with the id, which `lint` flags as `linked_clip_orphan`.- The render ignores `data-link`: an out-of-sync pair still plays exactly what its timings say.- Prefer a single `<video data-has-audio="true">` for footage with sound. Link only when the sound needs its own clip (its own track, volume or FX); to undo a detach, move the audio attributes back onto the video and delete the `<audio>`.-- **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.+- **Sync origin.** `data-sync-origin="<id>"` marks a video and an audio from one source file; Detach writes it, Link writes it only for a pair from one source file, 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