@hyperframes/studio 0.8.107 → 0.8.109

package/src/player/components/clipToolAttrs.ts

@@ -0,0 +1,187 @@
+/**
+ * The attribute each clip-menu tool writes, and what a clip's attributes say is applied.
+ * Pure over strings so the menu, the badges and an agent's hand edits all agree.
+ */
+
+import {
+  parseAudioFxChain,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import { activeAudioFxPresetIds } 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";
+
+export interface ClipToolChoice {
+  id: string;
+  label: string;
+}
+
+export const VOICE_CHOICES: readonly ClipToolChoice[] = [
+  { id: "voice-clean", label: "Clean" },
+  { id: "voice-broadcast", label: "Broadcast" },
+  { id: "voice-warm", label: "Warm" },
+];
+
+export const CHARACTER_CHOICES: readonly ClipToolChoice[] = [
+  { id: "telephone", label: "Telephone" },
+  { id: "radio-am", label: "AM Radio" },
+  { id: "megaphone", label: "Megaphone" },
+];
+
+export const LOOK_CHOICES: readonly ClipToolChoice[] = [
+  { id: "warm-daylight", label: "Warm daylight" },
+  { id: "clean-studio", label: "Clean studio" },
+  { id: "vintage-wash", label: "Vintage wash" },
+  { id: "mono-clean", label: "Mono" },
+  { id: "deep-contrast", label: "Deep contrast" },
+  { id: "home-movie-8mm", label: "Home movie" },
+];
+
+const VOICE_MENU_IDS = new Set([...VOICE_CHOICES, ...CHARACTER_CHOICES].map((c) => c.id));
+
+const EMPTY_CHAIN: HfAudioFxChain = { version: 1, nodes: [] };
+
+function parseChainOrEmpty(raw: string | null | undefined): HfAudioFxChain {
+  if (!raw) return EMPTY_CHAIN;
+  try {
+    return parseAudioFxChain(raw);
+  } catch {
+    return EMPTY_CHAIN;
+  }
+}
+
+function labelFor(choices: readonly ClipToolChoice[], id: string | null): string | null {
+  return choices.find((choice) => choice.id === id)?.label ?? null;
+}
+
+export function activeVoicePreset(rawChain: string | null | undefined): string | null {
+  const ids = activeAudioFxPresetIds(parseChainOrEmpty(rawChain));
+  return ids.find((id) => VOICE_MENU_IDS.has(id)) ?? null;
+}
+
+function voicePresetLabel(id: string | null): string | null {
+  return labelFor(VOICE_CHOICES, id) ?? labelFor(CHARACTER_CHOICES, id);
+}
+
+/**
+ * The `data-fx-chain` after choosing a voice preset, or `null` to drop the attribute.
+ * Single choice: the other menu presets' nodes go; carve, leveller and hand-added nodes stay.
+ */
+export function chainWithVoicePreset(
+  rawChain: string | null | undefined,
+  presetId: string | null,
+): string | null {
+  const chain = parseChainOrEmpty(rawChain);
+  const others = chain.nodes.filter(
+    (node) =>
+      !node.fromPreset || !VOICE_MENU_IDS.has(node.fromPreset) || node.fromPreset === presetId,
+  );
+  const kept: HfAudioFxChain = { ...chain, nodes: others };
+  const next = presetId ? (applyPresetToChain(kept, presetId, undefined) ?? kept) : kept;
+  return next.nodes.length > 0 ? serializeAudioFxChain(next) : null;
+}
+
+function parseJson(raw: string | null | undefined): unknown {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function activeLook(rawGrading: string | null | undefined): string | null {
+  return normalizeHfColorGrading(parseJson(rawGrading))?.preset ?? null;
+}
+
+function lookLabel(id: string | null): string | null {
+  return labelFor(LOOK_CHOICES, id);
+}
+
+export function lookAttrValue(presetId: string | null): string | null {
+  return presetId ? JSON.stringify({ preset: presetId, intensity: 1 }) : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function isDucked(rawCarve: string | null | undefined): boolean {
+  const carve = parseJson(rawCarve);
+  return isRecord(carve) && carve["enabled"] !== false;
+}
+
+function hasRateRamp(rawAutomation: string | null | undefined): boolean {
+  return parseRateLane(rawAutomation) !== null;
+}
+
+const ZERO_INSET = /^inset\(\s*0(px|%)?\s*\)$/i;
+
+export function hasCrop(clipPath: string | null | undefined): boolean {
+  const value = clipPath?.trim() ?? "";
+  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;
+  hasSound: boolean;
+  volume: number | null;
+  muted: boolean;
+  fxChain: string | null;
+  automation: string | null;
+  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" };
+  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 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),
+  };
+}

package/src/player/components/linkLabelColor.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { LINK_LABEL_COLORS, linkLabelColor } from "./linkLabelColor";
+
+describe("linkLabelColor", () => {
+  it("has no colour for an unlinked clip", () => {
+    expect(linkLabelColor(undefined)).toBeNull();
+    expect(linkLabelColor("")).toBeNull();
+  });
+
+  it("walks the palette in lk-N order, wrapping", () => {
+    expect(linkLabelColor("lk-1")).toBe(LINK_LABEL_COLORS[0]);
+    expect(linkLabelColor("lk-2")).toBe(LINK_LABEL_COLORS[1]);
+    expect(linkLabelColor(`lk-${LINK_LABEL_COLORS.length + 1}`)).toBe(LINK_LABEL_COLORS[0]);
+  });
+
+  it("is deterministic for hand-written ids", () => {
+    expect(linkLabelColor("talk-pair")).toBe(linkLabelColor("talk-pair"));
+    expect(LINK_LABEL_COLORS).toContain(linkLabelColor("talk-pair"));
+  });
+});

package/src/player/components/linkLabelColor.ts

@@ -0,0 +1,24 @@
+/** Link-group label colours; teal, violet, white and red belong to clips, selection and the sync badge. */
+export const LINK_LABEL_COLORS = [
+  "var(--color-amber-500)",
+  "var(--color-sky-400)",
+  "var(--color-green-400)",
+  "var(--color-pink-400)",
+  "var(--color-orange-400)",
+  "var(--color-amber-300)",
+] as const;
+
+function stableIndex(link: string): number {
+  const numbered = /^lk-(\d+)$/.exec(link);
+  if (numbered) return Number(numbered[1]) - 1;
+  let hash = 0;
+  for (const char of link) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+  return hash;
+}
+
+/** The same colour for every member of a link group, from its id alone. */
+export function linkLabelColor(link: string | undefined): string | null {
+  if (!link) return null;
+  const count = LINK_LABEL_COLORS.length;
+  return LINK_LABEL_COLORS[((stableIndex(link) % count) + count) % count] ?? null;
+}

package/src/player/components/timelineCallbacks.ts

@@ -39,6 +39,14 @@ export interface TimelineDropCallbacks {
   ) => Promise<void> | void;
 }
 
+export type TimelineLinkEdit =
+  | { kind: "unlink"; elements: readonly TimelineElement[] }
+  | { kind: "link"; elements: readonly TimelineElement[] }
+  | { kind: "detach"; element: TimelineElement }
+  | { kind: "merge"; video: TimelineElement; audio: TimelineElement }
+  | { kind: "move-into-sync"; element: TimelineElement; start: number }
+  | { kind: "slip-into-sync"; element: TimelineElement; mediaStart: number };
+
 export interface TimelineEditCallbacks {
   onMoveElement?: (
     element: TimelineElement,
@@ -115,9 +123,13 @@ export interface TimelineEditCallbacks {
     label: string,
   ) => Promise<TimelineEditOutcome | void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
+  onLinkEdit?: (edit: TimelineLinkEdit) => Promise<void> | void;
+  onDeleteElementOnly?: (element: TimelineElement) => Promise<void> | void;
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
+  onFreezeFrame?: (element: TimelineElement, time: number) => Promise<void> | void;
+  onNotice?: (message: string, tone?: "error" | "info") => void;
   onDeleteKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
   onDeleteAllKeyframes?: (element: TimelineElement, animationId?: string) => void;
   onMoveKeyframeToPlayhead?: (element: TimelineElement, keyframe: TimelineKeyframeTarget) => void;

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -70,6 +70,7 @@ interface TimelineClipDragGestureLifecycleInput {
   onBlockedEditAttemptRef: RefObject<
     ((element: TimelineElement, intent: BlockedClipState["intent"]) => void) | undefined
   >;
+  onLinkEditRef: RefObject<TimelineEditCallbacks["onLinkEdit"]>;
   readZIndexRef: RefObject<((element: TimelineElement) => number) | undefined>;
   onStackingPatchesRef: RefObject<
     ((patches: StackingPatch[]) => Promise<unknown> | void) | undefined
@@ -107,6 +108,7 @@ export function mountTimelineClipDragGestureLifecycle({
   onResizeElementRef,
   onResizeElementsRef,
   onBlockedEditAttemptRef,
+  onLinkEditRef,
   readZIndexRef,
   onStackingPatchesRef,
   refreshAfterLaneMoveRef,
@@ -228,6 +230,11 @@ export function mountTimelineClipDragGestureLifecycle({
     if (drag && pointerMatchesGesture(event)) handleDragPointerMove(event, drag);
   };
 
+  const unlinkAltEdited = (gesture: { element: TimelineElement; altKey?: boolean }) => {
+    if (!gesture.altKey || !gesture.element.link) return;
+    void onLinkEditRef.current?.({ kind: "unlink", elements: [gesture.element] });
+  };
+
   const commitResizePointerUp = (
     resize: ResizingClipState,
     groupSession: TimelineGroupResizeSession | null,
@@ -271,6 +278,7 @@ export function mountTimelineClipDragGestureLifecycle({
       ]);
       console.error("[Timeline] Failed to persist clip resize", error);
     });
+    unlinkAltEdited(resize);
   };
 
   const finishBlockedPointerUp = (blocked: BlockedClipState) => {
@@ -293,6 +301,7 @@ export function mountTimelineClipDragGestureLifecycle({
       onStackingPatches: onStackingPatchesRef.current,
       refreshAfterLaneMove: refreshAfterLaneMoveRef.current,
     });
+    unlinkAltEdited(drag);
   };
 
   /** Group gestures commit atomically: one missing member cancels the whole resize. */

package/src/player/components/timelineClipDragTypes.ts

@@ -33,6 +33,7 @@ export interface DraggedClipState {
   snapTime: number | null;
   snapType: TimelineSnapType | null;
   started: boolean;
+  altKey?: boolean;
 }
 
 export interface ResizingClipState {
@@ -63,6 +64,7 @@ export interface ResizingClipState {
     playbackStart?: number;
   }[];
   started: boolean;
+  altKey?: boolean;
 }
 
 export interface BlockedClipState {

package/src/player/components/timelineClipGestureHandlers.ts

@@ -8,6 +8,7 @@ import {
 import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { CLIP_HANDLE_W } from "./timelineLayout";
+import { selectClipWithLinks } from "./timelineLinkSelection";
 import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 
 export interface ClipGestureDeps {
@@ -145,6 +146,7 @@ export function createClipGestureHandlers(
       previewDuration: el.duration,
       previewPlaybackStart: el.playbackStart,
       started: false,
+      altKey: e.altKey,
     });
   };
 
@@ -191,6 +193,7 @@ export function createClipGestureHandlers(
       snapTime: null,
       snapType: null,
       started: false,
+      altKey: e.altKey,
     });
   };
 
@@ -217,7 +220,7 @@ export function createClipGestureHandlers(
       return;
     }
     // Clip selection is idempotent; empty timeline space owns deselection.
-    setSelectedElementId(elementKey);
+    selectClipWithLinks(elementKey, e.altKey, setSelectedElementId);
     onSelectElement?.(el);
   };
 

package/src/player/components/timelineLinkSelection.ts

@@ -0,0 +1,23 @@
+import { usePlayerStore } from "../store/playerStore";
+import { expandToLinkedMembers } from "./audioClipLink";
+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
+
+/**
+ * Select `key` the way a clip click does, then widen to link partners; Alt
+ * (or Linked Selection off) selects `key` alone, even inside a larger selection.
+ */
+export function selectClipWithLinks(
+  key: string,
+  altKey: boolean,
+  setSelectedElementId: (id: string) => void,
+): void {
+  const state = usePlayerStore.getState();
+  if (altKey || !isLinkedSelectionOn()) {
+    state.setSelection([key], key);
+    return;
+  }
+  setSelectedElementId(key);
+  const { selectedElementIds, elements } = usePlayerStore.getState();
+  const expanded = expandToLinkedMembers(selectedElementIds, elements);
+  if (expanded.size > selectedElementIds.size) state.setSelection(expanded, key);
+}

package/src/player/components/useClipToolState.ts

@@ -0,0 +1,92 @@
+import { useEffect, useState } from "react";
+import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
+import { HF_AUDIO_CARVE_ATTR } from "@hyperframes/core/audio-carve";
+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";
+import { useLivePreviewIframe } from "../store/previewIframeStore";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { findTimelineElementInIframe } from "../../hooks/timelineEditingHelpers";
+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",
+  "style",
+];
+
+function readVolume(node: Element): number | null {
+  const volume = Number.parseFloat(node.getAttribute("data-volume") ?? "");
+  return Number.isFinite(volume) ? volume : null;
+}
+
+function toolStateFromNode(node: Element): ClipToolState {
+  const tag = node.tagName.toLowerCase();
+  return {
+    tag,
+    hasSound: tag === "audio" || isAudibleVideoNode(node),
+    volume: readVolume(node),
+    muted: node.hasAttribute("muted"),
+    fxChain: node.getAttribute(HF_AUDIO_FX_ATTR),
+    automation: node.getAttribute(HF_AUDIO_AUTOMATION_ATTR),
+    colorGrading: node.getAttribute(HF_COLOR_GRADING_ATTR),
+    clipPath: committedClipPath(node),
+    carve: node.getAttribute(HF_AUDIO_CARVE_ATTR),
+    link: node.getAttribute(LINK_ATTR),
+  };
+}
+
+function toolStateFromElement(el: TimelineElement): ClipToolState {
+  const tag = el.tag.trim().toLowerCase();
+  return {
+    tag,
+    hasSound: tag === "audio" || el.hasAudio === true,
+    volume: el.volume ?? null,
+    muted: el.muted === true,
+    fxChain: el.fxChain ?? null,
+    automation: el.automation ?? null,
+    colorGrading: null,
+    clipPath: null,
+    carve: null,
+    link: null,
+  };
+}
+
+/** Inline style changes every frame under a tween; only a changed reading re-renders. */
+function keepIfUnchanged(prev: ClipToolState, next: ClipToolState): ClipToolState {
+  return JSON.stringify(prev) === JSON.stringify(next) ? prev : next;
+}
+
+/** A clip's tool attributes as the live preview node holds them, kept current as they change. */
+export function useClipToolState(el: TimelineElement): ClipToolState {
+  const iframe = useLivePreviewIframe();
+  const activeCompPath = useStudioShellContextOptional()?.activeCompPath ?? null;
+  const [state, setState] = useState<ClipToolState>(() => toolStateFromElement(el));
+
+  useEffect(() => {
+    const node = findTimelineElementInIframe(iframe, el, activeCompPath);
+    if (!node) {
+      setState(toolStateFromElement(el));
+      return;
+    }
+    const refresh = () => setState((prev) => keepIfUnchanged(prev, toolStateFromNode(node)));
+    refresh();
+    const view = node.ownerDocument.defaultView;
+    if (!view) return;
+    const observer = new view.MutationObserver(refresh);
+    observer.observe(node, { attributes: true, attributeFilter: WATCHED_ATTRS });
+    return () => observer.disconnect();
+  }, [iframe, el, activeCompPath]);
+
+  return state;
+}

package/src/player/components/useTimelineClipContextMenu.ts

@@ -1,6 +1,7 @@
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { ClipContextMenuState } from "./TimelineProvider";
+import { selectClipWithLinks } from "./timelineLinkSelection";
 
 /** A clicked member of an active multi-selection keeps the whole group
  *  selected, so the context menu it opens acts on all of it. */
@@ -16,7 +17,7 @@ export function useClipContextMenu(
       e.preventDefault();
       const id = el.key ?? el.id;
       if (!(selectedElementIds.size > 1 && selectedElementIds.has(id))) {
-        setSelectedElementId(id);
+        selectClipWithLinks(id, e.altKey, setSelectedElementId);
         onSelectElement?.(el);
       }
       dismissGapMenu();

package/src/player/components/useTimelineClipDrag.ts

@@ -27,6 +27,8 @@ import type {
   BlockedClipState,
 } from "./timelineClipDragTypes";
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
+import { linkedGestureKeys } from "./audioClipLink";
+import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import {
   mountTimelineClipDragGestureLifecycle,
@@ -65,6 +67,7 @@ interface UseTimelineClipDragInput {
   ) => Promise<void> | void;
   onResizeElements?: NonNullable<TimelineEditCallbacks["onResizeElements"]>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedClipState["intent"]) => void;
+  onLinkEdit?: TimelineEditCallbacks["onLinkEdit"];
   /** Seeks the preview; a trim shows the frame at its dragged edge. */
   onSeek?: (time: number, options?: { keepPlaying?: boolean; follow?: boolean }) => void;
   setShowPopover: (show: boolean) => void;
@@ -95,6 +98,7 @@ export function useTimelineClipDrag({
   onResizeElement,
   onResizeElements,
   onBlockedEditAttempt,
+  onLinkEdit,
   onSeek,
   setShowPopover,
   setRangeSelectionRef,
@@ -220,6 +224,13 @@ export function useTimelineClipDrag({
         return;
       }
       beginGesture("drag", next.pointerId);
+      gestureSelectedKeysRef.current = linkedGestureKeys(
+        gestureSelectedKeysRef.current,
+        next.element,
+        elementsRef.current,
+        next.altKey === true,
+        isLinkedSelectionOn(),
+      );
       publishDraggedClip(next);
     },
     [beginGesture, publishDraggedClip],
@@ -231,6 +242,13 @@ export function useTimelineClipDrag({
         return;
       }
       beginGesture("resize", next.pointerId);
+      gestureSelectedKeysRef.current = linkedGestureKeys(
+        gestureSelectedKeysRef.current,
+        next.element,
+        elementsRef.current,
+        next.altKey === true,
+        isLinkedSelectionOn(),
+      );
       publishResizingClip(next);
     },
     [beginGesture, publishResizingClip],
@@ -249,6 +267,8 @@ export function useTimelineClipDrag({
   onMoveElementsRef.current = onMoveElements;
   const onBlockedEditAttemptRef = useRef(onBlockedEditAttempt);
   onBlockedEditAttemptRef.current = onBlockedEditAttempt;
+  const onLinkEditRef = useRef(onLinkEdit);
+  onLinkEditRef.current = onLinkEdit;
   const onResizeElementRef = useRef(onResizeElement);
   onResizeElementRef.current = onResizeElement;
   const onResizeElementsRef = useRef(onResizeElements);
@@ -422,6 +442,7 @@ export function useTimelineClipDrag({
       refreshAfterLaneMoveRef,
       readZIndexRef,
       onBlockedEditAttemptRef,
+      onLinkEditRef,
       onResizeElementsRef,
       onResizeElementRef,
       onMoveElementsRef,

package/src/player/components/useTimelineProviderState.tsx

@@ -86,6 +86,7 @@ export function useTimelineProviderState({
     onResizeElement,
     onResizeElements,
     onBlockedEditAttempt,
+    onLinkEdit,
     onSplitElement,
     onRazorSplitAll,
     onDeleteKeyframe,
@@ -105,6 +106,7 @@ export function useTimelineProviderState({
   const readOnlyPress = useTimelineReadOnlyPress();
   const oneShotEdits = refuseWhenReadOnly(readOnlyPress, {
     onBlockedEditAttempt,
+    onLinkEdit,
     onRazorSplitAll,
     onToggleTrackHidden: editContext.onToggleTrackHidden,
     onTogglePropertyGroupKeyframe: editContext.onTogglePropertyGroupKeyframe,
@@ -217,6 +219,7 @@ export function useTimelineProviderState({
     onResizeElement: pinnedOnResizeElement,
     onResizeElements: pinnedOnResizeElements,
     onBlockedEditAttempt: oneShotEdits.onBlockedEditAttempt,
+    onLinkEdit: oneShotEdits.onLinkEdit,
     onSeek,
     setShowPopover,
     setRangeSelectionRef,

package/src/player/hooks/timelinePlayerSync.test.ts

@@ -13,9 +13,15 @@ describe("timelineElementsChanged", () => {
     ["audio group hidden", { audioGroupHidden: true }],
     ["fade in", { fadeIn: 1 }],
     ["fade out", { fadeOut: 1 }],
+    ["link", { link: "lk-1" }],
     ["source (re-pointed at its preview copy)", { src: "clip1.mp4?hf-proxy=h264" }],
   ])("sees a clip whose %s changed with no timing change", (_name, change) => {
     expect(timelineElementsChanged([clip], [{ ...clip, ...change }])).toBe(true);
     expect(timelineElementsChanged([{ ...clip, ...change }], [{ ...clip, ...change }])).toBe(false);
   });
+
+  it("sees an unlink: the same clips re-derived without their link", () => {
+    const linked = { ...clip, link: "lk-1" };
+    expect(timelineElementsChanged([linked], [clip])).toBe(true);
+  });
 });

package/src/player/hooks/timelinePlayerSync.ts

@@ -16,6 +16,7 @@ const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
   "fadeIn",
   "fadeOut",
   "src",
+  "link",
 ];
 
 /** Whether a derived timeline changes any field that affects rendering. */

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -15,6 +15,7 @@ import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
 import { readTimelineDurationFromDocument } from "../lib/timelineDOM";
 import { buildMissingCompositionElements } from "../lib/timelineIframeHelpers";
 import { acceptedRuntimeMessageFps } from "../lib/runtimeProtocol";
+import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
 import {
   buildTimelineElementsFromClips,
   syncManifestTimeline,
@@ -196,8 +197,10 @@ export function useTimelineSyncCallbacks({
       // at the authored root `data-duration` so a runtime that measures only the
       // furthest clip end (shorter than the authored window) can't leave a stale,
       // too-short total in the transport (the "0:44/0:40" bug).
+      const fps = acceptedRuntimeMessageFps(data);
+      useLinkedClipPreferences.getState().setCompositionFps(fps);
       const newDuration = resolveTimelineTotalDuration({
-        manifestDurationSeconds: data.durationInFrames / acceptedRuntimeMessageFps(data),
+        manifestDurationSeconds: data.durationInFrames / fps,
         authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
       });
       syncManifestTimeline(

package/src/player/lib/timelineDOM.test.ts

@@ -281,6 +281,37 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
 
     expect(element.hidden).toBe(true);
   });
+
+  it("reads data-link and data-sync-origin on both the DOM and manifest paths", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <video id="talk" class="clip" src="t.mp4" muted data-link="lk-1" data-sync-origin="lk-1" data-start="0" data-duration="5"></video>
+      </div>
+    `);
+    const fromDom = parseTimelineFromDOM(doc, 10).find((el) => el.domId === "talk");
+    expect(fromDom?.link).toBe("lk-1");
+    expect(fromDom?.syncOrigin).toBe("lk-1");
+    const element = createTimelineElementFromManifestClip({
+      clip: {
+        id: "talk",
+        label: "Talk",
+        kind: "element",
+        tagName: "video",
+        start: 0,
+        duration: 5,
+        track: 0,
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: doc.getElementById("talk"),
+    });
+    expect(element.link).toBe("lk-1");
+    expect(element.syncOrigin).toBe("lk-1");
+  });
 });
 
 describe("group info cache", () => {