@hyperframes/studio 0.8.108 → 0.8.109

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", () => {

package/src/player/lib/timelineDOM.ts

@@ -12,6 +12,7 @@ import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip, IframeWindow, TimelineLike } from "./playbackTypes";
 import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import { readClipTiming } from "@hyperframes/core/composition-contract";
+import { linkScopeOf } from "@hyperframes/core/media-link";
 import { createRuntimeStartTimeResolver } from "@hyperframes/core/runtime/start-resolver";
 import { groupInfoFor } from "./timelineGroupInfo";
 import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
@@ -150,6 +151,12 @@ export function createTimelineElementFromManifestClip(params: {
     if (hostEl.hasAttribute("data-hidden")) entry.hidden = true;
     const timelineRole = hostEl.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
+    const link = hostEl.getAttribute("data-link");
+    if (link) entry.link = link;
+    const compositionScope = linkScopeOf(hostEl)?.getAttribute("data-composition-id");
+    if (compositionScope) entry.compositionScope = compositionScope;
+    const syncOrigin = hostEl.getAttribute("data-sync-origin");
+    if (syncOrigin) entry.syncOrigin = syncOrigin;
     const audioGroup = hostEl.getAttribute("data-audio-group");
     if (audioGroup) {
       entry.audioGroup = audioGroup;
@@ -337,6 +344,12 @@ export function parseTimelineFromDOM(
 
     const timelineRole = el.getAttribute("data-timeline-role");
     if (timelineRole) entry.timelineRole = timelineRole;
+    const domLink = el.getAttribute("data-link");
+    if (domLink) entry.link = domLink;
+    const domCompositionScope = linkScopeOf(el)?.getAttribute("data-composition-id");
+    if (domCompositionScope) entry.compositionScope = domCompositionScope;
+    const domSyncOrigin = el.getAttribute("data-sync-origin");
+    if (domSyncOrigin) entry.syncOrigin = domSyncOrigin;
 
     const domAudioGroup = el.getAttribute("data-audio-group");
     if (domAudioGroup) {

package/src/player/store/timelineElement.ts

@@ -83,6 +83,9 @@ export interface TimelineElement {
   /** The owning group's serialized `data-fx-chain`, when set — resolved once per parse. */
   audioGroupFxChain?: string;
   audioGroupAutomation?: string;
+  link?: string;
+  compositionScope?: string;
+  syncOrigin?: string;
   /**
    * Master start of the composition this row runs in, which its tweens and its
    * `data-start` are local to; 0 at the root. Writes go through toAuthoredStart.
@@ -116,6 +119,15 @@ export function toCompositionTime(element: RowClock, masterTime: number): number
   return masterTime - (element.parentCompositionStart ?? 0);
 }
 
+type CompositionScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;
+
+export function sameCompositionScope(a: CompositionScoped, b: CompositionScoped): boolean {
+  return (
+    (a.sourceFile ?? "") === (b.sourceFile ?? "") &&
+    (a.compositionScope ?? "") === (b.compositionScope ?? "")
+  );
+}
+
 /**
  * The fields `updateElement` may write.
  *

package/src/styles/components.css

@@ -296,17 +296,6 @@
   transition: none;
 }
 
-.timeline-audio-link {
-  position: absolute;
-  z-index: 4;
-  top: -9px;
-  left: 50%;
-  width: 1px;
-  height: 10px;
-  background: var(--timeline-audio-link);
-  pointer-events: none;
-}
-
 .timeline-clip.is-hovered {
   background-color: var(--clip-bg-hover);
 }
@@ -362,6 +351,16 @@
   white-space: nowrap;
 }
 
+/* Link groups share a label colour on the border and the name chip. */
+.timeline-clip[data-link-color] {
+  border-color: var(--clip-link-color);
+}
+
+.timeline-clip[data-link-color] .timeline-clip__label {
+  box-shadow: inset 3px 0 0 var(--clip-link-color);
+  padding-left: 8px;
+}
+
 .timeline-clip.is-audio .timeline-clip__label {
   top: 11px;
   left: 9px;
@@ -517,6 +516,23 @@
   transition: transform 160ms ease;
 }
 
+/* The caret of a text edited in place (InlineTextCaret): lit half the time, like the system caret */
+.hf-inline-text-caret {
+  animation: hf-inline-text-caret-blink 1.06s step-end infinite;
+}
+
+@keyframes hf-inline-text-caret-blink {
+  50% {
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-inline-text-caret {
+    animation: none;
+  }
+}
+
 /* Toast enter/exit (StudioToast) */
 @keyframes hf-toast-in {
   from {

package/src/styles/theme.css

@@ -117,7 +117,6 @@
   --timeline-clip-audio-bg-hover: oklch(0.49 0.12 300);
   --timeline-clip-audio-bg-dragging: oklch(0.42 0.12 300 / 0.96);
   --timeline-clip-audio-muted-bg: rgb(72, 74, 78);
-  --timeline-audio-link: light-dark(#626d66, #a0aaa4);
   --timeline-clip-selection: light-dark(#0f766e, rgba(255, 255, 255, 0.85));
   --timeline-clip-selection-highlight: rgb(255 255 255 / 0.55);
   --timeline-clip-radius: 8px;

package/src/utils/gsapSoftReload.test.ts

@@ -1,7 +1,8 @@
 // @vitest-environment happy-dom
 
-import { describe, it, expect, vi } from "vitest";
+import { afterEach, describe, it, expect, vi } from "vitest";
 import {
+  readNestedFiles,
   applySoftReload,
   applySoftReloadFinalization,
   ensureMotionPathPluginLoaded,
@@ -131,10 +132,14 @@ describe("applySoftReload", () => {
     const container = document.createElement("div");
     container.appendChild(scriptEl);
 
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "root");
+    root.appendChild(orphan);
+
     const { iframe } = buildMockIframe({ gsap: { timeline: vi.fn(), set: vi.fn() } });
     (iframe as unknown as { contentDocument: unknown }).contentDocument = {
       querySelectorAll: (sel: string) =>
-        sel === "script:not([src])" ? [scriptEl] : sel === "[style*='transform']" ? [orphan] : [],
+        sel === "script:not([src])" ? [scriptEl] : sel.includes("composition-id") ? [root] : [],
       createElement: (tag: string) => document.createElement(tag),
       body: container,
       head: document.createElement("div"),
@@ -427,6 +432,8 @@ describe("ensureMotionPathPluginLoaded", () => {
 // from the parse-time stamp. Otherwise a runtime transient (the color-grading
 // hide's 0, a mid-flight tween value) becomes a permanent tween bound.
 describe("applySoftReload authored-style restore", () => {
+  afterEach(() => document.body.replaceChildren());
+
   function buildIframeWithTarget(el: Element, overrides: Record<string, unknown> = {}) {
     const scriptEl = document.createElement("script");
     scriptEl.textContent =
@@ -581,4 +588,233 @@ describe("applySoftReload authored-style restore", () => {
     applySoftReload(iframe, SCRIPT_TEXT);
     expect(transformAtRebind).toBe("");
   });
+
+  // The preview inlines a sub-composition into a host that names its file.
+  function inlinedIn(file: string, el: HTMLElement): HTMLElement {
+    const host = document.createElement("div");
+    host.setAttribute("data-composition-file", file);
+    host.appendChild(el);
+    document.body.appendChild(host);
+    return el;
+  }
+
+  function answerQueries(iframe: HTMLIFrameElement, styled: Element, root: Element): void {
+    const doc = iframe.contentDocument as unknown as { querySelectorAll: (s: string) => unknown };
+    const query = doc.querySelectorAll;
+    doc.querySelectorAll = (sel: string) =>
+      sel.includes("transform") ? [styled] : sel.includes("composition-id") ? [root] : query(sel);
+  }
+  const SUB_FILE = `<template id="sub-template"><div id="sub" data-composition-id="sub">
+    <div id="nroot" data-hf-id="hf-n" style="left: 560px; top: 300px"></div></div></template>`;
+
+  it("gives a root tween's nested target what its own file authors for what GSAP wrote", () => {
+    const el = document.createElement("div");
+    el.id = "nroot";
+    el.setAttribute("data-hf-id", "hf-n");
+    // GSAP folded the stylesheet translate into its transform, masked it, and wrote the tweened width.
+    el.style.cssText =
+      "left: 560px; top: 300px; width: 337px; translate: none; transform: translate(12.5px, 0px)";
+    inlinedIn("compositions/sub.html", el);
+    const tween = { targets: () => [el], vars: { x: 50, width: 400, duration: 4 } };
+    const { iframe } = buildIframeWithTarget(el, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [tween] } },
+    });
+    const authoredHtml = `<html><body><div id="root"></div></body></html>`;
+    const nestedFiles = new Map([["compositions/sub.html", SUB_FILE]]);
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT, { authoredHtml, nestedFiles })).toBe("applied");
+    expect(el.getAttribute("style")).toBe("left: 560px; top: 300px;");
+  });
+
+  it("puts back a root element's tweened width from the file instead of the live value", () => {
+    const el = document.createElement("div");
+    el.setAttribute("data-hf-id", "hf-1");
+    el.style.cssText = "left: 700px; width: 366px";
+    const tween = { targets: () => [el], vars: { width: 450, duration: 4 } };
+    const { iframe } = buildIframeWithTarget(el, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [tween] } },
+    });
+    const authoredHtml = `<html><body><div data-hf-id="hf-1" style="left: 700px"></div></body></html>`;
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT, { authoredHtml })).toBe("applied");
+    expect(el.getAttribute("style")).toBe("left: 700px;");
+  });
+
+  it("leaves what a nested composition's own timeline animates to that timeline", () => {
+    const el = inlinedIn("compositions/sub.html", document.createElement("div"));
+    el.id = "nroot";
+    el.style.cssText = "translate: none; transform: translate(40px, 10px)";
+    const sub = { getChildren: () => [{ targets: () => [el], vars: { x: 100 } }] };
+    const { iframe } = buildIframeWithTarget(el, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [sub] }, sub },
+    });
+    const readFile = vi.fn(async () => SUB_FILE);
+
+    expect(readNestedFiles(iframe, SCRIPT_TEXT, readFile)).toBeNull();
+    applySoftReload(iframe, SCRIPT_TEXT);
+
+    expect(readFile).not.toHaveBeenCalled();
+    expect(el.style.cssText).toBe("translate: none; transform: translate(40px, 10px);");
+  });
+
+  it("a nested composition's reload leaves a GSAP transform in the top-level file alone", () => {
+    const host = document.createElement("div");
+    host.setAttribute("data-composition-id", "root");
+    host.setAttribute("data-composition-file", "compositions/sub.html");
+    const outside = Object.assign(document.createElement("div"), { _gsap: {} });
+    outside.style.cssText = "rotate: none; transform: rotate(30deg)";
+    const { iframe } = buildIframeWithTarget(host, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [] } },
+    });
+    answerQueries(iframe, outside, host);
+
+    applySoftReload(iframe, SCRIPT_TEXT, { authoredHtml: SUB_FILE });
+
+    expect(outside.style.cssText).toBe("rotate: none; transform: rotate(30deg);");
+  });
+
+  it("a nested composition's reload leaves its element that the top-level timeline animates alone", () => {
+    const host = document.createElement("div");
+    host.setAttribute("data-composition-id", "root");
+    host.setAttribute("data-composition-file", "compositions/sub.html");
+    const el = Object.assign(document.createElement("div"), { _gsap: {} });
+    // The top-level tween folded the stylesheet translate into its transform.
+    el.style.cssText = "translate: none; transform: translate(23.75px, 5px)";
+    host.appendChild(el);
+    const main = { getChildren: () => [{ targets: () => [el], vars: { x: 50 } }] };
+    const { iframe } = buildIframeWithTarget(host, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [] }, main },
+    });
+    answerQueries(iframe, el, host);
+
+    applySoftReload(iframe, SCRIPT_TEXT, {
+      authoredHtml: SUB_FILE,
+    });
+
+    expect(el.style.cssText).toBe("translate: none; transform: translate(23.75px, 5px);");
+  });
+
+  it("a nested composition's own reload restores its element from the file just written", () => {
+    const host = document.createElement("div");
+    host.setAttribute("data-composition-id", "root");
+    host.setAttribute("data-composition-file", "compositions/sub.html");
+    const el = document.createElement("div");
+    el.id = "nroot";
+    el.setAttribute("data-hf-id", "hf-n");
+    el.style.cssText = "left: 560px; top: 300px; width: 337px";
+    host.appendChild(el);
+    const tween = { targets: () => [el], vars: { width: 400 } };
+    const { iframe } = buildIframeWithTarget(el, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [tween] } },
+    });
+    answerQueries(iframe, el, host);
+    const readFile = vi.fn(async () => SUB_FILE);
+
+    expect(readNestedFiles(iframe, SCRIPT_TEXT, readFile)).toBeNull();
+    applySoftReload(iframe, SCRIPT_TEXT, { authoredHtml: SUB_FILE });
+
+    expect(readFile).not.toHaveBeenCalled();
+    expect(el.getAttribute("style")).toBe("left: 560px; top: 300px;");
+  });
+
+  it("reads only the other composition files a top-level re-run resets elements of", async () => {
+    const el = inlinedIn("compositions/sub.html", document.createElement("div"));
+    const tween = { targets: () => [el], vars: { width: 400 } };
+    const { iframe } = buildIframeWithTarget(el, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [tween] } },
+    });
+    const readFile = vi.fn(async () => SUB_FILE);
+
+    const files = await readNestedFiles(iframe, SCRIPT_TEXT, readFile);
+
+    expect(readFile).toHaveBeenCalledTimes(1);
+    expect(files).toEqual(new Map([["compositions/sub.html", SUB_FILE]]));
+  });
+
+  it("escalates, touching nothing, when a nested file the reset needs could not be read", () => {
+    const el = inlinedIn("compositions/sub.html", document.createElement("div"));
+    el.style.cssText = "width: 337px; translate: none";
+    const tween = { targets: () => [el], vars: { width: 400 } };
+    const set = vi.fn();
+    const { iframe } = buildIframeWithTarget(el, {
+      gsap: { timeline: vi.fn(), set },
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [tween] } },
+    });
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT, { nestedFiles: null })).toBe("cannot-soft-reload");
+    expect(set).not.toHaveBeenCalled();
+    expect(el.style.cssText).toBe("width: 337px; translate: none;");
+  });
+
+  it("keeps the runtime's own inline writes: only what GSAP wrote comes back from the file", () => {
+    const el = document.createElement("div");
+    el.setAttribute("data-hf-id", "hf-1");
+    // The runtime's layout pass wrote position and a data-width size; GSAP wrote the mask and transform.
+    el.style.cssText =
+      "left: 10px; position: absolute; width: 300px; translate: none; transform: translate(50px, 0px)";
+    const tween = { targets: () => [el], vars: { x: 50 } };
+    const { iframe } = buildIframeWithTarget(el, {
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [tween] } },
+    });
+    const authoredHtml = `<html><body><div data-hf-id="hf-1" style="left: 10px"></div></body></html>`;
+
+    applySoftReload(iframe, SCRIPT_TEXT, { authoredHtml });
+
+    expect(el.getAttribute("style")).toBe("left: 10px; position: absolute; width: 300px;");
+  });
+});
+
+describe("applySoftReload over a composition's own markup", () => {
+  // A live preview whose top-level timeline has no children; `_gsap` marks what a script set.
+  function reloadRoot(markup: string, held: string[]) {
+    const doc = document.implementation.createHTMLDocument("");
+    doc.body.innerHTML = `${markup}<script>${SCRIPT_TEXT}</script>`;
+    for (const id of held) Object.assign(doc.getElementById(id)!, { _gsap: {} });
+    const set = vi.fn();
+    const contentWindow = {
+      gsap: { timeline: vi.fn(), set },
+      __hfForceTimelineRebind: vi.fn(),
+      __timelines: { root: { kill: vi.fn(), getChildren: () => [] } } as Record<string, unknown>,
+      __player: { getTime: () => 0, seek: vi.fn() },
+    };
+    const iframe = { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement;
+    const cleared = () => (set.mock.calls[0]?.[0] as Element[] | undefined)?.map((el) => el.id);
+    return { doc, iframe, cleared };
+  }
+
+  it("resets an element a standalone gsap.set holds even when no inline transform is left", () => {
+    const { iframe, cleared } = reloadRoot(
+      `<div data-composition-id="root"><div id="held" style="left: 5px"></div><div id="plain"></div></div>`,
+      ["held"],
+    );
+
+    applySoftReload(iframe, SCRIPT_TEXT);
+
+    expect(cleared()).toEqual(["held"]);
+  });
+
+  it("leaves what a nested composition's script holds alone, but resets that composition's host", () => {
+    const { doc, iframe, cleared } = reloadRoot(
+      `<div data-composition-id="root"><div id="host" data-composition-id="sub">` +
+        `<div id="nested" style="transform: translate(90px, 60px)"></div></div></div>`,
+      ["host", "nested"],
+    );
+
+    applySoftReload(iframe, SCRIPT_TEXT);
+
+    expect(cleared()).toEqual(["host"]);
+    expect(doc.getElementById("nested")!.style.transform).toBe("translate(90px, 60px)");
+  });
+
+  it("reloads in full when the re-run builds its DOM a second time", () => {
+    const { doc, iframe } = reloadRoot(`<div id="root" data-composition-id="root"></div>`, []);
+    const append = doc.body.appendChild.bind(doc.body);
+    // What a script's createElement or template clone does each time it runs.
+    doc.body.appendChild = <T extends Node>(node: T): T => {
+      doc.getElementById("root")!.appendChild(doc.createElement("div"));
+      return append(node);
+    };
+
+    expect(applySoftReload(iframe, SCRIPT_TEXT)).toBe("cannot-soft-reload");
+  });
 });