@hyperframes/studio 0.8.78 → 0.8.79

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

@@ -127,6 +127,11 @@ describe("preview errors", () => {
     root = null;
   });
 
+  it("puts the preview on the player's once-a-second paused heartbeat", async () => {
+    const { player } = await mountPlayer();
+    expect(player.hasAttribute("low-power-idle")).toBe(true);
+  });
+
   it("attaches lifecycle listeners before navigating the player", async () => {
     await mountPlayer();
     const srcIndex = lifecycleLog.indexOf("src");

package/src/player/components/Player.tsx

@@ -317,6 +317,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
 
         player.setAttribute("shader-capture-scale", "1");
         player.setAttribute("shader-loading", "player");
+        player.setAttribute("low-power-idle", "");
         player.setAttribute("width", String(portrait ? 1080 : 1920));
         player.setAttribute("height", String(portrait ? 1920 : 1080));
         player.style.width = "100%";

package/src/player/components/VideoThumbnail.test.tsx

@@ -86,6 +86,19 @@ describe("VideoThumbnail", () => {
     expect(host.querySelectorAll("img").length).toBeGreaterThan(0);
   });
 
+  it("spreads the frames across every tile so the strip reaches the clip's end", async () => {
+    const urls = Array.from({ length: 8 }, (_, index) => `blob:${index}`);
+    vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+      value: { kind: "filmstrip", urls, aspect: 16 / 9 },
+      weight: 256,
+    });
+
+    await render(500);
+
+    const tiles = [...host.querySelectorAll("img")].map((img) => img.getAttribute("src"));
+    expect(tiles).toEqual(["blob:0", "blob:2", "blob:4", "blob:5", "blob:7"]);
+  });
+
   it("issues a single decode job for a narrow clip", async () => {
     vi.mocked(decodeVideoThumbnail).mockResolvedValue({
       value: { kind: "image", url: "blob:poster", aspect: 16 / 9 },

package/src/player/components/VideoThumbnail.tsx

@@ -146,7 +146,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
       {urls.length > 0 && (
         <div className="absolute inset-0 flex">
           {Array.from({ length: frameCount }, (_, index) => {
-            const src = urls[index % urls.length];
+            const src = urls[Math.round((index * (urls.length - 1)) / Math.max(1, frameCount - 1))];
             return (
               <div
                 key={index}

package/src/player/components/timelineCallbacks.ts

@@ -1,5 +1,6 @@
 // fallow-ignore-file code-duplication
 // fallow-ignore-file dead-code
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineMoveOperation } from "../../hooks/timelineMoveAdapter";
 import type { BlockedTimelineEditIntent } from "./timelineEditing";
@@ -89,7 +90,7 @@ export interface TimelineEditCallbacks {
     attr: string,
     value: string | null,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome | void>;
   /** C1's ungrouped-track FX pointer: "Group these clips" — write
    *  `data-audio-group` on every one of them, atomically. Same shape B6's
    *  carve auto-grouping uses. */
@@ -110,7 +111,7 @@ export interface TimelineEditCallbacks {
     attr: string,
     value: string | null,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome | void>;
   onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   onSplitElement?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;

package/src/player/hooks/useTimelinePlayer.hiddenPause.test.ts

@@ -0,0 +1,75 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import {
+  attachIframeWindow,
+  makeAdapterWindow,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+describe("useTimelinePlayer tab hidden while playing", () => {
+  it("pauses on the adapter's time, like any other pause", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { adapter, win } = makeAdapterWindow();
+    attachIframeWindow(api, win);
+    act(() => api.play());
+    adapter.seek(6);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(usePlayerStore.getState().currentTime).toBe(6);
+    act(() => root.unmount());
+  });
+
+  it("stops a reverse shuttle for good", async () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    const { adapter, win } = makeAdapterWindow();
+    attachIframeWindow(api, win);
+    adapter.seek(20);
+    act(() => void window.dispatchEvent(new KeyboardEvent("keydown", { code: "KeyJ", key: "j" })));
+    await act(() => new Promise((r) => setTimeout(r, 100)));
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+    const stoppedAt = adapter.getTime();
+    await act(() => new Promise((r) => setTimeout(r, 200)));
+
+    expect(usePlayerStore.getState().isPlaying).toBe(false);
+    expect(adapter.getTime()).toBe(stoppedAt);
+    expect(usePlayerStore.getState().currentTime).toBe(stoppedAt);
+    act(() => root.unmount());
+  });
+
+  it("does not carry the shuttle speed past the pause", () => {
+    const { api, root } = renderTimelinePlayerHarness();
+    attachIframeWindow(api, makeAdapterWindow().win);
+    const pressL = () =>
+      act(
+        () => void window.dispatchEvent(new KeyboardEvent("keydown", { code: "KeyL", key: "l" })),
+      );
+    pressL();
+    pressL();
+    expect(usePlayerStore.getState().playbackRate).toBe(2);
+
+    vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    act(() => void document.dispatchEvent(new Event("visibilitychange")));
+    pressL();
+
+    expect(usePlayerStore.getState().playbackRate).toBe(1);
+    act(() => root.unmount());
+  });
+});

package/src/player/hooks/useTimelinePlayer.play.test.ts

@@ -95,6 +95,42 @@ it.each([30, 0])(
   },
 );
 
+it("settles a load whose runtime learns its duration after its only readiness post", async () => {
+  const { api, root } = renderTimelinePlayerHarness();
+  let duration = 0;
+  const { adapter, win } = makeAdapterWindow();
+  adapter.getDuration = () => duration;
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+  });
+  postFromRuntime(win, { type: "state" });
+  expect(adapter.pause).not.toHaveBeenCalled();
+
+  // No further post comes: a paused low-power preview checks in only once a second.
+  duration = 30;
+  await act(() => new Promise((resolve) => requestAnimationFrame(() => resolve(undefined))));
+  expect(adapter.pause).toHaveBeenCalled();
+  act(() => root.unmount());
+});
+
+it.each(["unmounts", "resets"])("stops retrying a pending load once the player %s", async (how) => {
+  const { api, root } = renderTimelinePlayerHarness();
+  const { adapter, win } = makeAdapterWindow();
+  let lookups = 0;
+  adapter.getDuration = () => (lookups++, 0);
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+  });
+  postFromRuntime(win, { type: "state" });
+  act(() => (how === "resets" ? api.resetPlayer() : root.unmount()));
+  const atStop = lookups;
+  await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  expect(lookups).toBe(atStop);
+  if (how === "resets") act(() => root.unmount());
+});
+
 it("does not let the blank page's load step enable Play for the preview that replaces it", async () => {
   const { api, root } = renderTimelinePlayerHarness();
   // The iframe's first load is about:blank, before the runtime exists; its load step waits for runtime messages.

package/src/player/hooks/useTimelinePlayer.ts

@@ -362,21 +362,25 @@ export function useTimelinePlayer({
       seek,
     });
 
-  const { processTimelineMessageRef, enrichMissingCompositionsRef, onIframeLoad } =
-    useTimelineSyncCallbacks({
-      iframeRef,
-      probeIntervalRef,
-      pendingSeekRef,
-      isRefreshingRef,
-      getAdapter,
-      syncTimelineElements,
-      setDuration,
-      setCurrentTime,
-      requestTimelineReady,
-      setIsPlaying,
-      attachIframeShortcutListeners,
-      applyPreviewAudioState,
-    });
+  const {
+    processTimelineMessageRef,
+    enrichMissingCompositionsRef,
+    onIframeLoad,
+    cancelPendingLoad,
+  } = useTimelineSyncCallbacks({
+    iframeRef,
+    probeIntervalRef,
+    pendingSeekRef,
+    isRefreshingRef,
+    getAdapter,
+    syncTimelineElements,
+    setDuration,
+    setCurrentTime,
+    requestTimelineReady,
+    setIsPlaying,
+    attachIframeShortcutListeners,
+    applyPreviewAudioState,
+  });
 
   // Full-reload edits load behind a hidden shadow iframe (useShadowPreviewReload.ts).
   const {
@@ -452,8 +456,8 @@ export function useTimelinePlayer({
     applyPreviewVariablesToUrl(url);
     beginShadowReload(url.toString());
   }, [saveSeekPosition, getAdapter, beginShadowReload]);
-  const getAdapterRef = useRef(getAdapter);
-  getAdapterRef.current = getAdapter;
+  const pauseRef = useRef(pause);
+  pauseRef.current = pause;
 
   useMountEffect(() => {
     const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
@@ -469,14 +473,7 @@ export function useTimelinePlayer({
     });
 
     const handleVisibilityChange = () => {
-      if (document.hidden && usePlayerStore.getState().isPlaying) {
-        const adapter = getAdapterRef.current?.();
-        if (adapter) {
-          adapter.pause();
-          setIsPlaying(false);
-          stopRAFLoop();
-        }
-      }
+      if (document.hidden && usePlayerStore.getState().isPlaying) pauseRef.current();
     };
 
     window.addEventListener("keydown", handleWindowKeyDown, true);
@@ -494,16 +491,16 @@ export function useTimelinePlayer({
       stopReverseLoop();
       stopScrubPreviewAudio();
       releaseStaticSeekCache(staticSeekAdapterRef, staticSeekWarnedRef);
-      if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+      cancelPendingLoad();
     };
   });
 
   const resetPlayer = useCallback(() => {
     stopRAFLoop();
     stopReverseLoop();
-    if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+    cancelPendingLoad();
     usePlayerStore.getState().reset();
-  }, [stopRAFLoop, stopReverseLoop]);
+  }, [stopRAFLoop, stopReverseLoop, cancelPendingLoad]);
 
   useEffect(() => {
     return usePlayerStore.subscribe((state, prev) => {

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -244,7 +244,7 @@ export function useTimelineSyncCallbacks({
       adapter.pause();
       const startTime = seekAdapterToRestorePoint(adapter, pendingSeekRef);
       const commit = () => {
-        // Keep non-React listeners such as the capture link and time display in sync
+        // Keep non-React listeners such as the time display in sync
         // with the initial adapter seek on iframe load.
         liveTime.notify(startTime);
         syncAdapterDuration(adapter, setDuration);
@@ -309,28 +309,36 @@ export function useTimelineSyncCallbacks({
       // Listen for those instead of polling.
       const iframe = iframeRef.current;
       let settled = false;
+      let retryFrame = 0;
+      const stopWaiting = () => {
+        window.removeEventListener("message", onMessage);
+        cancelAnimationFrame(retryFrame);
+      };
 
       const trySettle = () => {
         if (settled) return;
         if (initializeAdapter(context)) {
           settled = true;
-          window.removeEventListener("message", onMessage);
+          stopWaiting();
           if (probeIntervalRef.current) clearInterval(probeIntervalRef.current);
+          return;
         }
+        cancelAnimationFrame(retryFrame);
+        retryFrame = requestAnimationFrame(trySettle);
       };
 
       const onMessage = (e: MessageEvent) => {
         if (isPreviewReadinessMessage(e, iframe)) trySettle();
       };
       window.addEventListener("message", onMessage);
-      stopWaitingRef.current = () => window.removeEventListener("message", onMessage);
+      stopWaitingRef.current = stopWaiting;
 
       // Safety net: if no message arrives within 5s, try one last time then give up.
       probeIntervalRef.current = setTimeout(() => {
         if (!settled) {
           trySettle();
         }
-        window.removeEventListener("message", onMessage);
+        stopWaiting();
         if (!settled) onLoadGiveUp?.(context);
         revealIframe(iframeRef.current);
       }, 5000) as unknown as ReturnType<typeof setInterval>;

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

@@ -5,6 +5,7 @@ import { decodeVideoThumbnail, videoThumbnailTimestamps } from "./thumbnailVideo
 
 const dispose = vi.fn();
 const canvasesAtTimestamps = vi.fn();
+const getKeyPacket = vi.fn(async (_time: number) => null as { timestamp: number } | null);
 const input = {
   getPrimaryVideoTrack: vi.fn(),
   dispose,
@@ -22,10 +23,25 @@ vi.mock("mediabunny", () => ({
   CanvasSink: class {
     canvasesAtTimestamps = canvasesAtTimestamps;
   },
+  EncodedPacketSink: class {
+    getKeyPacket = getKeyPacket;
+  },
 }));
 
+function recordDecodes(decoded: number[][]): void {
+  canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+    const run: number[] = [];
+    decoded.push(run);
+    for await (const time of timestamps) {
+      run.push(time);
+      yield { canvas: document.createElement("canvas") };
+    }
+  });
+}
+
 beforeEach(() => {
   vi.clearAllMocks();
+  getKeyPacket.mockImplementation(async () => null);
   vi.spyOn(URL, "createObjectURL").mockReturnValueOnce("blob:one").mockReturnValueOnce("blob:two");
   vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
   HTMLCanvasElement.prototype.toBlob = function toBlob(callback) {
@@ -52,17 +68,14 @@ describe("videoThumbnailTimestamps", () => {
 
 describe("decodeVideoThumbnail", () => {
   it("extracts sparse frames, returns object URLs, and disposes once", async () => {
-    const canvas = document.createElement("canvas");
-    canvasesAtTimestamps.mockImplementation(async function* (timestamps: number[]) {
-      expect(timestamps).toEqual([2, 8]);
-      yield { canvas, timestamp: 2, duration: 1 };
-      yield { canvas, timestamp: 8, duration: 1 };
-    });
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
     const result = await decodeVideoThumbnail(
       { source: "/clip.mp4", sourceStart: 2, sourceRangeDuration: 6, frameCount: 2 },
       new AbortController().signal,
     );
 
+    expect(decoded).toEqual([[2, 8]]);
     expect(result.value).toEqual({
       kind: "filmstrip",
       urls: ["blob:one", "blob:two"],
@@ -74,6 +87,89 @@ describe("decodeVideoThumbnail", () => {
     expect(dispose).toHaveBeenCalledTimes(1);
   });
 
+  it("decodes each strip frame at its keyframe unless that keyframe is before the clip's range", async () => {
+    getKeyPacket.mockImplementation(async (time) => ({ timestamp: Math.floor(time / 4) * 4 }));
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 2, sourceRangeDuration: 8, frameCount: 3 },
+      new AbortController().signal,
+    );
+    expect(decoded).toEqual([[2, 4, 8]]);
+  });
+
+  it("keeps a slot's own time when its keyframe is more than half a slot earlier", async () => {
+    getKeyPacket.mockImplementation(async () => ({ timestamp: 0 }));
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+      new AbortController().signal,
+    );
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 1 },
+      new AbortController().signal,
+    );
+    expect(decoded).toEqual([[0, 5, 10], [5]]);
+  });
+
+  it("looks up each keyframe just before decoding it", async () => {
+    const events: string[] = [];
+    getKeyPacket.mockImplementation(async (time) => {
+      events.push(`key ${time}`);
+      return { timestamp: time };
+    });
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      for await (const time of timestamps) {
+        events.push(`frame ${time}`);
+        yield { canvas: document.createElement("canvas") };
+      }
+    });
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+      new AbortController().signal,
+    );
+    expect(events).toEqual(["key 0", "frame 0", "key 5", "frame 5", "key 10", "frame 10"]);
+  });
+
+  it("ends the decode times without throwing when cancelled during a keyframe lookup", async () => {
+    const controller = new AbortController();
+    getKeyPacket.mockImplementation(async () => (controller.abort(), null));
+    const decoded: number[] = [];
+    let timesEnded = false;
+    canvasesAtTimestamps.mockImplementation(async function* (timestamps: AsyncIterable<number>) {
+      for await (const time of timestamps) {
+        decoded.push(time);
+        yield { canvas: document.createElement("canvas") };
+      }
+      timesEnded = true;
+    });
+    await expect(
+      decodeVideoThumbnail(
+        { source: "/clip.mp4", sourceStart: 0, sourceRangeDuration: 10, frameCount: 3 },
+        controller.signal,
+      ),
+    ).rejects.toThrow("Aborted");
+    expect(getKeyPacket).toHaveBeenCalledTimes(1);
+    expect(decoded).toEqual([]);
+    expect(timesEnded).toBe(true);
+  });
+
+  it("spreads a trimmed strip across its range when the file reports no duration", async () => {
+    input.getPrimaryVideoTrack.mockResolvedValue({
+      getDisplayWidth: vi.fn(async () => 1080),
+      getDisplayHeight: vi.fn(async () => 1920),
+      getDurationFromMetadata: vi.fn(async () => null),
+    });
+    const decoded: number[][] = [];
+    recordDecodes(decoded);
+    await decodeVideoThumbnail(
+      { source: "/clip.mp4", sourceStart: 5, sourceRangeDuration: 5, frameCount: 3 },
+      new AbortController().signal,
+    );
+    expect(decoded).toEqual([[5, 7.5, 10]]);
+  });
+
   it("releases input and degrades when the source has no video track", async () => {
     input.getPrimaryVideoTrack.mockResolvedValue(null);
     await expect(

package/src/player/lib/thumbnailVideoDecoder.ts

@@ -44,7 +44,7 @@ interface DecodedResources {
 
 interface ThumbnailCanvasSink {
   canvasesAtTimestamps(
-    timestamps: number[],
+    timestamps: AsyncIterable<number>,
   ): AsyncIterable<{ canvas: HTMLCanvasElement | OffscreenCanvas } | null>;
 }
 
@@ -77,7 +77,7 @@ function targetDimensions(
 
 async function decodeFrames(
   sink: ThumbnailCanvasSink,
-  timestamps: number[],
+  timestamps: AsyncIterable<number>,
   signal: AbortSignal,
   resources: DecodedResources,
 ): Promise<void> {
@@ -89,6 +89,7 @@ async function decodeFrames(
     throwIfAborted(signal);
     resources.urls.push(URL.createObjectURL(blob));
   }
+  throwIfAborted(signal);
 }
 
 function loadedResult(
@@ -138,8 +139,12 @@ export async function decodeVideoThumbnail(
     }
     const metadataDuration = await track.getDurationFromMetadata({ skipLiveWait: true });
     throwIfAborted(signal);
-    const sourceDuration = Math.max(0, metadataDuration ?? request.sourceRangeDuration ?? 0);
-    const sourceStart = Math.min(Math.max(0, request.sourceStart ?? 0), sourceDuration);
+    const requestedStart = Math.max(0, request.sourceStart ?? 0);
+    const sourceDuration = Math.max(
+      0,
+      metadataDuration ?? requestedStart + (request.sourceRangeDuration ?? 0),
+    );
+    const sourceStart = Math.min(requestedStart, sourceDuration);
     const requestedDuration =
       request.sourceRangeDuration ?? Math.max(0, sourceDuration - sourceStart);
     const duration = Math.min(
@@ -151,6 +156,16 @@ export async function decodeVideoThumbnail(
       duration,
       Math.min(request.frameCount, budgets.richPreviewFrameCount),
     );
+    const keys = new mediabunny.EncodedPacketSink(track);
+    const maxKeyframeLead = duration / Math.max(2, timestamps.length - 1) / 2;
+    async function* decodeTimesAtNearbyKeyframes() {
+      for (const time of timestamps) {
+        const key = await keys.getKeyPacket(time, { metadataOnly: true });
+        if (signal.aborted) return;
+        const near = key && key.timestamp >= sourceStart && time - key.timestamp <= maxKeyframeLead;
+        yield near ? key.timestamp : time;
+      }
+    }
     const aspect = displayWidth / displayHeight;
     const target = targetDimensions(aspect, budgets);
     const sink = new mediabunny.CanvasSink(track, {
@@ -159,7 +174,7 @@ export async function decodeVideoThumbnail(
       fit: request.fit ?? "cover",
       poolSize: 1,
     });
-    await decodeFrames(sink, timestamps, signal, resources);
+    await decodeFrames(sink, decodeTimesAtNearbyKeyframes(), signal, resources);
     return loadedResult(resources, aspect, target.width, target.height);
   } catch (error) {
     releaseDecodedResources(resources);

package/src/utils/authoredSource.ts

@@ -0,0 +1,92 @@
+import { ensureHfIds, isCompositionTemplate } from "@hyperframes/parsers/hf-ids";
+
+// Stamped as the preview stamps the files it serves, so a live element's hf-id finds its source.
+export function parseSavedSource(html: string): Document {
+  return new DOMParser().parseFromString(ensureHfIds(html), "text/html");
+}
+
+const rootsByDoc = new WeakMap<Document, ParentNode[]>();
+
+// A plain template is a runtime clone source, so ids inside it repeat across clones.
+function searchRoots(root: ParentNode): ParentNode[] {
+  const templates = Array.from(root.querySelectorAll("template")).filter(isCompositionTemplate);
+  return [root, ...templates.flatMap((template) => searchRoots(template.content))];
+}
+
+function findByAttribute(doc: Document, name: string, value: string): Element | null {
+  let roots = rootsByDoc.get(doc);
+  if (!roots) rootsByDoc.set(doc, (roots = searchRoots(doc)));
+  const selector = `[${name}="${value.replace(/["\\]/g, "\\$&")}"]`;
+  for (const root of roots) {
+    const match = root.querySelector(selector);
+    if (match) return match;
+  }
+  return null;
+}
+
+export function findAuthoredElement(doc: Document, live: Element): Element | null {
+  const hfId = live.getAttribute("data-hf-id");
+  if (hfId) return findByAttribute(doc, "data-hf-id", hfId);
+  return live.id ? findByAttribute(doc, "id", live.id) : null;
+}
+
+export function findAuthoredElementById(doc: Document, live: Element): Element | null {
+  return live.id ? findByAttribute(doc, "id", live.id) : null;
+}
+
+const PATH_ATTRS = ["src", "href"];
+const CSS_URL = /\burl\(\s*(["']?)([^)"'\s](?:[^)"']*[^)"'\s])?)\1\s*\)/g;
+
+function isRelative(path: string): boolean {
+  return !!path && !/^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(path);
+}
+
+function toProjectPath(sourceFile: string, path: string): string {
+  const parts = sourceFile.split("/").slice(0, -1);
+  for (const part of path.split("/")) {
+    if (part === "..") parts.pop();
+    else if (part !== "." && part !== "") parts.push(part);
+  }
+  return parts.join("/");
+}
+
+function livePathsOf(live: Element): Set<string> {
+  const paths = new Set<string>();
+  for (const el of [live, ...Array.from(live.querySelectorAll("*"))]) {
+    for (const attr of PATH_ATTRS) paths.add(el.getAttribute(attr) ?? "");
+    for (const match of (el.getAttribute("style") ?? "").matchAll(CSS_URL)) paths.add(match[2]);
+  }
+  return paths;
+}
+
+// The preview inlines a sub-composition with its relative asset paths rebased to the project
+// root (rewriteAssetPath in @hyperframes/parsers, which is not browser-safe); copy does the same.
+export function authoredMarkup(authored: Element, live: Element, sourceFile: string): string {
+  if (!sourceFile.includes("/")) return authored.outerHTML;
+  const livePaths = livePathsOf(live);
+  const rebase = (path: string): string => {
+    if (!isRelative(path)) return path;
+    const cut = path.search(/[?#]/);
+    const suffix = cut < 0 ? "" : path.slice(cut);
+    const rebased = toProjectPath(sourceFile, cut < 0 ? path : path.slice(0, cut)) + suffix;
+    return path.startsWith("../") || livePaths.has(rebased) ? rebased : path;
+  };
+  const copy = authored.cloneNode(true) as Element;
+  for (const el of [copy, ...Array.from(copy.querySelectorAll("*"))]) {
+    for (const attr of PATH_ATTRS) {
+      const value = el.getAttribute(attr);
+      if (value) el.setAttribute(attr, rebase(value.trim()));
+    }
+    const style = el.getAttribute("style");
+    if (style) {
+      el.setAttribute(
+        "style",
+        style.replace(
+          CSS_URL,
+          (_, quote: string, url: string) => `url(${quote}${rebase(url)}${quote})`,
+        ),
+      );
+    }
+  }
+  return copy.outerHTML;
+}

package/src/utils/gsapSoftReload.test.ts

@@ -488,6 +488,35 @@ describe("applySoftReload authored-opacity restore", () => {
     expect(el.style.getPropertyPriority("opacity")).toBe("");
   });
 
+  it("keeps the stamp for an element whose hf-id the written file lacks, even if it shares an id", () => {
+    const el = document.createElement("img");
+    el.id = "title-card";
+    el.setAttribute("data-hf-id", "hf-from-another-file");
+    el.setAttribute("data-hf-authored-opacity", "0.5");
+    el.style.opacity = "0";
+
+    const opacity = restoreOpacity(
+      el,
+      '<html><body><img id="title-card" style="opacity: 0.9"></body></html>',
+    );
+
+    expect(opacity).toBe("0.5");
+  });
+
+  it("does not take a runtime clone's opacity from its plain template", () => {
+    const el = document.createElement("li");
+    el.id = "item";
+    el.setAttribute("data-hf-authored-opacity", "0.5");
+    el.style.opacity = "0";
+
+    const opacity = restoreOpacity(
+      el,
+      '<html><body><template><li id="item" style="opacity: 0.3"></li></template></body></html>',
+    );
+
+    expect(opacity).toBe("0.5");
+  });
+
   it("falls back to the parse-time stamp when no after-write HTML is given", () => {
     const el = document.createElement("img");
     el.setAttribute("data-hf-authored-opacity", "0.75");