@hyperframes/studio 0.8.125 → 0.8.127

package/src/hooks/useThumbnailStripSize.ts

@@ -1,31 +1,220 @@
-import { useCallback, useRef, useState } from "react";
-import { useMountEffect } from "./useMountEffect";
+import { useCallback, useState } from "react";
+import { flushSync } from "react-dom";
 
-interface StripSize {
+export interface StripSize {
   width: number;
   height: number;
+  inViewStart: number;
+  inViewEnd: number;
 }
 
-const resize = (width: number, height: number) => (prev: StripSize) =>
-  prev.width === width && prev.height === height ? prev : { width, height };
+const IN_VIEW_CHUNK_PX = 512;
 
-/** Size of the thumbnail's parent, kept current by a ResizeObserver; 0x0 until measured. */
+const chunk = (px: number, round: (n: number) => number) =>
+  Math.max(0, round(px / IN_VIEW_CHUNK_PX) * IN_VIEW_CHUNK_PX);
+
+const spanAt = (left: number) => ({
+  inViewStart: chunk(-left - IN_VIEW_CHUNK_PX, Math.floor),
+  inViewEnd: chunk(window.innerWidth - left + IN_VIEW_CHUNK_PX, Math.ceil),
+});
+
+// scrollMargin widens the band inside the timeline's own scroller too; TypeScript's DOM types lack it.
+const GAP_WARNING: IntersectionObserverInit & { scrollMargin: string } = {
+  rootMargin: `0px ${IN_VIEW_CHUNK_PX / 2}px`,
+  scrollMargin: `0px ${IN_VIEW_CHUNK_PX / 2}px`,
+};
+
+// A short strip keeps every tile, as before, so only long clips do work on a scroll.
+const SHORT_STRIP_MAX_PX = 8 * IN_VIEW_CHUNK_PX;
+const isShort = (width: number) => width <= SHORT_STRIP_MAX_PX;
+
+const EMPTY_STRIP: StripSize = { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 };
+
+// Clamped to a measured strip, so a strip changes only when it crosses the screen's edge.
+const merge = (prev: StripSize, patch: Partial<StripSize>): StripSize => {
+  const next = { ...prev, ...patch };
+  const width = next.width > 0 ? Math.ceil(next.width) : Infinity;
+  next.inViewStart = isShort(width) ? 0 : Math.min(next.inViewStart, width);
+  next.inViewEnd = isShort(width) ? width : Math.min(next.inViewEnd, width);
+  return (Object.keys(next) as (keyof StripSize)[]).every((key) => next[key] === prev[key])
+    ? prev
+    : next;
+};
+
+type Apply = (patch: Partial<StripSize>) => void;
+
+interface Strip {
+  apply: Apply;
+  scroller: Element | null;
+  box: { left: number; top: number; width: number; height: number };
+  readAt: { x: number; y: number };
+  showing: boolean;
+}
+
+const NEAR_PX = IN_VIEW_CHUNK_PX / 2;
+
+// Each frame reads the strips showing tiles, which a move without a scroll may have carried, and the
+// strips whose last box, moved by the scroll since, lands near the screen; reads precede one commit.
+const strips = new Map<Element, Strip>();
+let users = 0;
+let frame = 0;
+let shared: {
+  resize: ResizeObserver;
+  presence: IntersectionObserver | null;
+  gaps: IntersectionObserver | null;
+} | null = null;
+
+const offsetOf = (scroller: Element | null) =>
+  scroller ? { x: scroller.scrollLeft, y: scroller.scrollTop } : { x: scrollX, y: scrollY };
+
+const isNear = ({
+  left,
+  top,
+  width,
+  height,
+}: {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}) =>
+  left < innerWidth + NEAR_PX &&
+  left + width > -NEAR_PX &&
+  top < innerHeight + NEAR_PX &&
+  top + height > -NEAR_PX;
+
+const NOTHING_IN_VIEW = { inViewStart: 0, inViewEnd: 0 };
+
+const spanOf = (box: Strip["box"]) => (isNear(box) ? spanAt(box.left) : NOTHING_IN_VIEW);
+
+const read = (target: Element, strip: Strip) => {
+  const { left, top, width, height } = target.getBoundingClientRect();
+  strip.box = { left, top, width, height };
+  strip.readAt = offsetOf(strip.scroller);
+  return spanOf(strip.box);
+};
+
+const commit = (updates: (readonly [Apply, Partial<StripSize>])[]) =>
+  flushSync(() => updates.forEach(([apply, patch]) => apply(patch)));
+
+const refresh = () => {
+  frame = 0;
+  const offsetsNow = new Map<Element | null, { x: number; y: number }>();
+  const updates: (readonly [Apply, Partial<StripSize>])[] = [];
+  for (const [target, strip] of strips) {
+    if (isShort(strip.box.width)) continue;
+    let now = offsetsNow.get(strip.scroller);
+    if (!now) offsetsNow.set(strip.scroller, (now = offsetOf(strip.scroller)));
+    const { box, readAt } = strip;
+    const moved = {
+      left: box.left - (now.x - readAt.x),
+      top: box.top - (now.y - readAt.y),
+      width: box.width,
+      height: box.height,
+    };
+    if (strip.showing || isNear(moved)) updates.push([strip.apply, read(target, strip)]);
+  }
+  commit(updates);
+};
+
+const scheduleRefresh = () => {
+  if (!frame) frame = requestAnimationFrame(refresh);
+};
+
+const measure = (entries: { target: Element; size?: { width: number; height: number } }[]) =>
+  commit(
+    entries.flatMap(({ target, size }) => {
+      const strip = strips.get(target);
+      return strip ? [[strip.apply, { ...size, ...read(target, strip) }] as const] : [];
+    }),
+  );
+
+const onPresence = (entries: IntersectionObserverEntry[]) =>
+  measure(entries.filter((entry) => entry.isIntersecting));
+
+const onResize = (entries: ResizeObserverEntry[]) =>
+  measure(
+    entries.map(({ target, contentRect: { width, height } }) => ({
+      target,
+      size: { width, height },
+    })),
+  );
+
+const observeIntersections = (callback: IntersectionObserverCallback) =>
+  typeof IntersectionObserver === "undefined"
+    ? null
+    : new IntersectionObserver(callback, GAP_WARNING);
+
+function acquire() {
+  if (users++ === 0) {
+    shared = {
+      resize: new ResizeObserver(onResize),
+      presence: observeIntersections(onPresence),
+      gaps: observeIntersections(
+        (entries) => entries.some((entry) => entry.isIntersecting) && scheduleRefresh(),
+      ),
+    };
+    window.addEventListener("scroll", scheduleRefresh, { capture: true, passive: true });
+  }
+  return shared!;
+}
+
+function release() {
+  if (--users > 0) return;
+  shared?.resize.disconnect();
+  shared?.presence?.disconnect();
+  shared?.gaps?.disconnect();
+  shared = null;
+  window.removeEventListener("scroll", scheduleRefresh, { capture: true });
+  cancelAnimationFrame(frame);
+  frame = 0;
+}
+
+const watchGap = (gap: HTMLDivElement | null) => {
+  if (!gap) return;
+  const { gaps } = acquire();
+  gaps?.observe(gap);
+  return () => {
+    gaps?.unobserve(gap);
+    release();
+  };
+};
+
+/** Size of the thumbnail's parent and its span in the window, kept current on resize, scroll and moves. */
 export function useThumbnailStripSize() {
-  const [size, setSize] = useState<StripSize>({ width: 0, height: 0 });
-  const observerRef = useRef<ResizeObserver | null>(null);
+  const [size, setSize] = useState(EMPTY_STRIP);
 
   const ref = useCallback((element: HTMLDivElement | null) => {
-    observerRef.current?.disconnect();
     if (!element) return;
     const target = element.parentElement ?? element;
-    setSize(resize(target.clientWidth, target.clientHeight));
-    observerRef.current = new ResizeObserver(([entry]) =>
-      setSize(resize(entry.contentRect.width, entry.contentRect.height)),
-    );
-    observerRef.current.observe(target);
+    const { resize, presence } = acquire();
+    let current = EMPTY_STRIP;
+    const apply: Apply = (patch) => {
+      const next = merge(current, patch);
+      if (next === current) return;
+      current = next;
+      strip.showing = next.inViewEnd > 0;
+      setSize(next);
+    };
+    const scroller = target.closest("[data-timeline-scroll-viewport]");
+    const strip: Strip = {
+      apply,
+      scroller,
+      box: { left: 0, top: 0, width: 0, height: 0 },
+      readAt: { x: 0, y: 0 },
+      showing: false,
+    };
+    strips.set(target, strip);
+    apply({ width: target.clientWidth, height: target.clientHeight, ...read(target, strip) });
+    resize.observe(target);
+    presence?.observe(target);
+    return () => {
+      resize.unobserve(target);
+      presence?.unobserve(target);
+      strips.delete(target);
+      release();
+    };
   }, []);
 
-  useMountEffect(() => () => observerRef.current?.disconnect());
-
-  return [size, ref] as const;
+  return [size, ref, watchGap] as const;
 }

package/src/noWindowBoundDomChecks.test.ts

@@ -0,0 +1,31 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, it } from "vitest";
+
+const SRC = dirname(fileURLToPath(import.meta.url));
+const DOM_CTOR = String.raw`(?:HTML\w*Element|SVG\w*Element|Element|Node|Text|ShadowRoot|DocumentFragment)\b`;
+// A DOM constructor read off any object, a window most of all, asks which window built a node.
+const WINDOW_BOUND = [
+  new RegExp(String.raw`[\w$)\]!?]\??\.\s*${DOM_CTOR}`),
+  new RegExp(String.raw`^\s*\??\.\s*${DOM_CTOR}`),
+  new RegExp(String.raw`\[\s*["'](?:HTML|SVG)\w*Element["']`),
+];
+
+function sources(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true, recursive: true })
+    .filter((e) => e.isFile() && /\.tsx?$/.test(e.name) && !/\.test(-helpers)?\.tsx?$/.test(e.name))
+    .map((e) => join(e.parentPath, e.name));
+}
+
+it("no studio source checks a DOM node against a window's own constructor", () => {
+  const hits = sources(SRC).flatMap((file) =>
+    readFileSync(file, "utf8")
+      .split("\n")
+      .map((line, i) => ({ line, at: `${relative(SRC, file)}:${i + 1}` }))
+      .filter(({ line }) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+      .filter(({ line }) => WINDOW_BOUND.some((re) => re.test(line)))
+      .map(({ at, line }) => `${at}  ${line.trim()}`),
+  );
+  expect(hits, "use @hyperframes/core/runtime/dom-realm instead").toEqual([]);
+});

package/src/player/components/CompositionThumbnail.tsx

@@ -7,6 +7,7 @@ import {
   type ThumbnailRequest,
 } from "../lib/thumbnailScheduler";
 import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
+import { ThumbnailTiles } from "./ThumbnailTiles";
 import { computeThumbnailStrip, probeImageAspect } from "./thumbnailUtils";
 import { studioApiFetch } from "../../utils/studioApiFetch";
 
@@ -142,7 +143,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   contentRevision = 0,
   priority = "visible",
 }: CompositionThumbnailProps) {
-  const [container, setContainerRef] = useThumbnailStripSize();
+  const [container, setContainerRef, watchGap] = useThumbnailStripSize();
   const url = buildCompositionThumbnailUrl({
     previewUrl,
     seekTime,
@@ -169,15 +170,18 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
       {value && (
-        <div
-          className="absolute inset-0 flex"
+        <ThumbnailTiles
+          strip={container}
+          frameW={frameW}
+          frameCount={frameCount}
+          watchGap={watchGap}
           style={{
             animation: "hf-thumb-fade 200ms ease-out",
             mixBlendMode:
               "var(--timeline-composition-thumbnail-blend)" as CSSProperties["mixBlendMode"],
           }}
         >
-          {Array.from({ length: frameCount }, (_, index) => (
+          {(index) => (
             <div
               key={index}
               className="relative h-full shrink-0 overflow-hidden"
@@ -191,8 +195,8 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
                 style={{ opacity: "var(--timeline-composition-thumbnail-opacity)" }}
               />
             </div>
-          ))}
-        </div>
+          )}
+        </ThumbnailTiles>
       )}
       {snapshot.status === "loading" && (
         <div className="absolute inset-0 animate-pulse bg-text-0/[0.035]" />

package/src/player/components/ImageThumbnail.tsx

@@ -3,6 +3,7 @@ import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { useThumbnailStripSize } from "../../hooks/useThumbnailStripSize";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decodeImageThumbnail } from "../lib/thumbnailImageDecoder";
+import { ThumbnailTiles } from "./ThumbnailTiles";
 import { computeThumbnailStrip } from "./thumbnailUtils";
 
 export interface ImageThumbnailProps {
@@ -25,7 +26,7 @@ export const ImageThumbnail = memo(function ImageThumbnail({
   priority = "visible",
   rich = false,
 }: ImageThumbnailProps) {
-  const [container, setContainerRef] = useThumbnailStripSize();
+  const [container, setContainerRef, watchGap] = useThumbnailStripSize();
   const request = useMemo(
     () => ({
       key: createThumbnailKey({ kind: "image", source: imageSrc, rich: Number(rich) }),
@@ -46,8 +47,13 @@ export const ImageThumbnail = memo(function ImageThumbnail({
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
       {value?.kind === "image" && (
-        <div className="absolute inset-0 flex">
-          {Array.from({ length: frameCount }, (_, index) => (
+        <ThumbnailTiles
+          strip={container}
+          frameW={frameW}
+          frameCount={frameCount}
+          watchGap={watchGap}
+        >
+          {(index) => (
             <div
               key={index}
               className="relative h-full shrink-0 overflow-hidden bg-neutral-900"
@@ -61,8 +67,8 @@ export const ImageThumbnail = memo(function ImageThumbnail({
                 className="absolute inset-0 h-full w-full object-cover"
               />
             </div>
-          ))}
-        </div>
+          )}
+        </ThumbnailTiles>
       )}
       {snapshot.status === "loading" && (
         <div

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

@@ -0,0 +1,30 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { expect, it } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { ThumbnailTiles } from "./ThumbnailTiles";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const harness = createHappyDomRootHarness();
+
+it("places the first mounted tile where the full strip would have it", () => {
+  const host = document.body.appendChild(document.createElement("div"));
+  act(() =>
+    harness.mount(host).render(
+      <ThumbnailTiles
+        strip={{ width: 10_000, height: 40, inViewStart: 1_024, inViewEnd: 2_048 }}
+        frameW={100}
+        frameCount={100}
+        watchGap={() => {}}
+      >
+        {(index) => <i key={index} data-index={index} />}
+      </ThumbnailTiles>,
+    ),
+  );
+
+  const row = host.firstElementChild as HTMLElement;
+  const first = Number(row.querySelector("i")!.dataset.index);
+  expect(first).toBe(10);
+  expect(row.style.paddingLeft).toBe(`${first * 100}px`);
+});

package/src/player/components/ThumbnailTiles.tsx

@@ -0,0 +1,41 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { StripSize } from "../../hooks/useThumbnailStripSize";
+
+interface ThumbnailTilesProps {
+  strip: StripSize;
+  frameW: number;
+  frameCount: number;
+  watchGap: (gap: HTMLDivElement | null) => void | (() => void);
+  style?: CSSProperties;
+  children: (index: number) => ReactNode;
+}
+
+/** A clip's tile row, mounting only the tiles in the strip's on-screen span, each at its own place. */
+export function ThumbnailTiles({
+  strip,
+  frameW,
+  frameCount,
+  watchGap,
+  style,
+  children,
+}: ThumbnailTilesProps) {
+  const end = Math.min(frameCount, Math.ceil(strip.inViewEnd / frameW));
+  const first = Math.min(end, Math.floor(strip.inViewStart / frameW));
+  return (
+    <div className="absolute inset-0 flex" style={{ ...style, paddingLeft: first * frameW }}>
+      <div
+        ref={watchGap}
+        data-thumbnail-gap="start"
+        className="pointer-events-none absolute inset-y-0 left-0"
+        style={{ width: first * frameW }}
+      />
+      {Array.from({ length: end - first }, (_, offset) => children(first + offset))}
+      <div
+        ref={watchGap}
+        data-thumbnail-gap="end"
+        className="pointer-events-none absolute inset-y-0 right-0"
+        style={{ left: end * frameW }}
+      />
+    </div>
+  );
+}

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

@@ -1,10 +1,10 @@
 // @vitest-environment happy-dom
 import React, { act } from "react";
-import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { MockResizeObserver, reportResize } from "../../hooks/resizeObserverTestUtils";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
+import { createHappyDomRootHarness } from "./testRootHarness";
 import { VideoThumbnail } from "./VideoThumbnail";
 
 vi.mock("../lib/thumbnailVideoDecoder", () => ({ decodeVideoThumbnail: vi.fn() }));
@@ -15,28 +15,26 @@ Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
 });
 
 let host: HTMLDivElement;
-let root: Root | null = null;
 
 beforeEach(() => {
   globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
-  host = document.createElement("div");
-  document.body.append(host);
+  host = document.body.appendChild(document.createElement("div"));
 });
 
 afterEach(() => {
-  act(() => root?.unmount());
-  root = null;
   thumbnailScheduler.invalidateProject("p");
   vi.clearAllMocks();
-  document.body.innerHTML = "";
 });
 
+// Registered after the reset above, so each test's strip unmounts before the cache is cleared.
+const harness = createHappyDomRootHarness();
+
 async function render(width = 0, height = 40) {
   Object.defineProperty(host, "clientWidth", { configurable: true, value: width });
   Object.defineProperty(host, "clientHeight", { configurable: true, value: height });
-  root = createRoot(host);
+  const root = harness.mount(host);
   await act(async () => {
-    root!.render(
+    root.render(
       <VideoThumbnail
         videoSrc="/api/projects/p/preview/assets/clip.mp4"
         label=""
@@ -95,6 +93,115 @@ describe("VideoThumbnail", () => {
     expect(tiles).toEqual(["blob:0", "blob:2", "blob:4", "blob:5", "blob:7"]);
   });
 
+  describe("on a 10-minute clip at full zoom", () => {
+    const frames: FrameRequestCallback[] = [];
+    const originalIntersectionObserver = globalThis.IntersectionObserver;
+    let left = -432_000;
+    let scrolled = 0;
+    let reportGapNearScreen: () => void = () => {};
+
+    beforeEach(() => {
+      vi.mocked(decodeVideoThumbnail).mockResolvedValue({
+        value: { kind: "filmstrip", urls: ["blob:a", "blob:b"], aspect: 16 / 9 },
+        weight: 256,
+      });
+      vi.spyOn(window, "requestAnimationFrame").mockImplementation((frame) => frames.push(frame));
+      globalThis.IntersectionObserver = class {
+        observed = new Set<Element>();
+        constructor(private readonly callback: IntersectionObserverCallback) {
+          reportGapNearScreen = () =>
+            callback(
+              [...this.observed].map(
+                (target) => ({ isIntersecting: true, target }) as IntersectionObserverEntry,
+              ),
+              this as unknown as IntersectionObserver,
+            );
+        }
+        observe(target: Element) {
+          this.observed.add(target);
+          queueMicrotask(() =>
+            this.callback(
+              [{ isIntersecting: true, target } as IntersectionObserverEntry],
+              this as unknown as IntersectionObserver,
+            ),
+          );
+        }
+        unobserve(target: Element) {
+          this.observed.delete(target);
+        }
+        disconnect() {
+          this.observed.clear();
+        }
+      } as unknown as typeof IntersectionObserver;
+      left = -432_000;
+      scrolled = 0;
+      host.getBoundingClientRect = () =>
+        ({ left, top: 0, width: 600 * 1440, height: 40 }) as DOMRect;
+      const scroller = document.body.appendChild(document.createElement("div"));
+      scroller.setAttribute("data-timeline-scroll-viewport", "");
+      Object.defineProperty(scroller, "scrollLeft", { configurable: true, get: () => scrolled });
+      scroller.append(host);
+    });
+
+    const scrollTo = (nextLeft: number) => {
+      scrolled += left - nextLeft;
+      left = nextLeft;
+      host.dispatchEvent(new Event("scroll"));
+    };
+
+    afterEach(() => {
+      frames.length = 0;
+      vi.restoreAllMocks();
+      globalThis.IntersectionObserver = originalIntersectionObserver;
+    });
+
+    const settle = () =>
+      act(async () => {
+        await Promise.resolve();
+        for (const frame of frames.splice(0)) frame(0);
+      });
+
+    const expectTilesCoverTheWindow = () => {
+      const tiles = host.querySelectorAll("img").length;
+      const skipped = parseFloat(
+        (host.querySelector("img")!.closest(".flex") as HTMLElement).style.paddingLeft,
+      );
+      expect(tiles).toBeLessThan(60);
+      expect(skipped).toBeLessThanOrEqual(-left);
+      expect(skipped + tiles * 71).toBeGreaterThanOrEqual(-left + window.innerWidth);
+    };
+
+    it("mounts only the tiles in view, and follows each scroll", async () => {
+      await render(600 * 1440, 40);
+      expectTilesCoverTheWindow();
+
+      for (const scrolledTo of [100_000, 300_000]) {
+        scrollTo(-scrolledTo);
+        await settle();
+        expectTilesCoverTheWindow();
+      }
+    });
+
+    it("mounts no tiles once the clip is wholly off screen", async () => {
+      await render(600 * 1440, 40);
+
+      scrollTo(-(600 * 1440 + 5_000));
+      await settle();
+
+      expect(host.querySelectorAll("img")).toHaveLength(0);
+    });
+
+    it("follows the strip when something else moves it, as a drag moves its ghost", async () => {
+      await render(600 * 1440, 40);
+
+      left = -430_500;
+      reportGapNearScreen();
+      await settle();
+
+      expectTilesCoverTheWindow();
+    });
+  });
+
   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

@@ -7,6 +7,7 @@ import {
   type ThumbnailSnapshot,
 } from "../lib/thumbnailScheduler";
 import { decodeVideoThumbnail } from "../lib/thumbnailVideoDecoder";
+import { ThumbnailTiles } from "./ThumbnailTiles";
 import { computeThumbnailStrip, quantizeThumbnailFrameCount } from "./thumbnailUtils";
 
 interface VideoThumbnailProps {
@@ -85,7 +86,7 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   sessionEpoch = 0,
   priority = "visible",
 }: VideoThumbnailProps) {
-  const [container, setContainerRef] = useThumbnailStripSize();
+  const [container, setContainerRef, watchGap] = useThumbnailStripSize();
   const requestFrameCount = quantizeThumbnailFrameCount(
     computeThumbnailStrip(container.width, 16 / 9, container.height).frameCount,
   );
@@ -122,8 +123,13 @@ export const VideoThumbnail = memo(function VideoThumbnail({
   return (
     <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
       {urls.length > 0 && (
-        <div className="absolute inset-0 flex">
-          {Array.from({ length: frameCount }, (_, index) => {
+        <ThumbnailTiles
+          strip={container}
+          frameW={frameW}
+          frameCount={frameCount}
+          watchGap={watchGap}
+        >
+          {(index) => {
             const src = urls[Math.round((index * (urls.length - 1)) / Math.max(1, frameCount - 1))];
             return (
               <div
@@ -139,8 +145,8 @@ export const VideoThumbnail = memo(function VideoThumbnail({
                 />
               </div>
             );
-          })}
-        </div>
+          }}
+        </ThumbnailTiles>
       )}
       {snapshot.status === "loading" && urls.length === 0 && (
         <div

package/src/player/lib/timelineGroupInfo.realm.test.ts

@@ -0,0 +1,20 @@
+// @vitest-environment jsdom
+import { expect, it } from "vitest";
+import { groupInfoFor } from "./timelineGroupInfo";
+
+it("sees a group the preview adds, whichever window built its node", () => {
+  const frame = document.body.appendChild(document.createElement("iframe"));
+  const doc = frame.contentDocument!;
+  const member = doc.createElement("audio");
+  member.id = "a1";
+  member.setAttribute("data-audio-group", "g1");
+  doc.body.append(member);
+  expect(groupInfoFor(doc, "g1").label).toBe("g1");
+  const group = doc.createElement("hf-audio-group");
+  group.id = "g1";
+  group.setAttribute("data-label", "Drums");
+  doc.body.append(group);
+
+  expect(groupInfoFor(doc, "g1").label).toBe("Drums");
+  frame.remove();
+});

package/src/player/lib/timelineGroupInfo.ts

@@ -6,6 +6,7 @@
  * cache, its revision counter, the observer that bumps it, and the one reader.
  */
 
+import { isElementNode } from "@hyperframes/core/runtime/dom-realm";
 import {
   HF_AUDIO_GROUP_ATTR,
   HF_AUDIO_GROUP_TAG,
@@ -52,7 +53,7 @@ function countGroupChanges(doc: Document, records: readonly MutationRecord[]): v
       record.type !== "childList" ||
       [...record.addedNodes, ...record.removedNodes].some(
         (node) =>
-          node instanceof Element &&
+          isElementNode(node) &&
           (node.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG ||
             node.hasAttribute(HF_AUDIO_GROUP_ATTR) ||
             node.querySelector?.(`${HF_AUDIO_GROUP_TAG},[${HF_AUDIO_GROUP_ATTR}]`) != null),