@hyperframes/studio 0.7.54 → 0.7.56

package/src/utils/gsapSoftReload.ts

@@ -183,6 +183,159 @@ export interface SoftReloadOptions {
   authoredHtml?: string;
 }
 
+/** One file's restore from the edit-history store: before (live) / after (target) bytes. */
+export interface UndoRestoreFile {
+  previous: string;
+  restored: string;
+}
+function idElementMap(doc: Document): Map<string, Element> {
+  const map = new Map<string, Element>();
+  for (const el of doc.querySelectorAll("[id]")) {
+    const id = el.getAttribute("id");
+    if (id) map.set(id, el);
+  }
+  return map;
+}
+
+// Strip id'd elements to bare `id` and blank GSAP scripts, in place: docs that
+// differ only in id'd attributes/inline-style/script text normalize equal; any
+// residual difference is beyond soft-reload's reach → caller full-reloads.
+function normalizeSoftResidual(doc: Document): void {
+  for (const el of doc.querySelectorAll("[id]")) {
+    const id = el.getAttribute("id");
+    for (const name of [...el.getAttributeNames()]) {
+      if (name !== "id") el.removeAttribute(name);
+    }
+    if (id) el.setAttribute("id", id);
+  }
+  for (const script of findGsapScriptElements(doc)) script.textContent = "";
+}
+
+// Soft-reloadable iff the docs differ SOLELY in id'd-element attributes/inline
+// style and/or the GSAP script; returns the changed ids to sync onto the live
+// DOM. Structural/text diffs → null → the caller full-reloads. Pure.
+export function diffSoftReloadableRestore(
+  previous: string,
+  restored: string,
+): { changedElementIds: string[] } | null {
+  let prevDoc: Document;
+  let nextDoc: Document;
+  try {
+    prevDoc = new DOMParser().parseFromString(previous, "text/html");
+    nextDoc = new DOMParser().parseFromString(restored, "text/html");
+  } catch {
+    return null;
+  }
+  const prevById = idElementMap(prevDoc);
+  const nextById = idElementMap(nextDoc);
+  // A different id set means an element was added or removed (e.g. a split, a
+  // delete) — structural, so soft-reload can't express it.
+  if (prevById.size !== nextById.size) return null;
+  const changedElementIds: string[] = [];
+  for (const [id, nextEl] of nextById) {
+    const prevEl = prevById.get(id);
+    if (!prevEl || prevEl.tagName !== nextEl.tagName) return null;
+    // A change inside the element (text / children) is out of soft scope; only
+    // its own attributes may differ. (GSAP scripts are handled via re-run.)
+    if (prevEl.innerHTML !== nextEl.innerHTML) return null;
+    if (prevEl.outerHTML !== nextEl.outerHTML) changedElementIds.push(id);
+  }
+  // Confirm nothing OUTSIDE id'd-element attributes and GSAP scripts changed.
+  normalizeSoftResidual(prevDoc);
+  normalizeSoftResidual(nextDoc);
+  if (prevDoc.documentElement.outerHTML !== nextDoc.documentElement.outerHTML) return null;
+  return { changedElementIds };
+}
+
+/** Copy every attribute from `source` onto the live `target`, dropping extras. */
+function syncElementAttributes(target: Element, source: Element): void {
+  for (const name of [...target.getAttributeNames()]) {
+    if (!source.hasAttribute(name)) target.removeAttribute(name);
+  }
+  for (const name of source.getAttributeNames()) {
+    target.setAttribute(name, source.getAttribute(name) ?? "");
+  }
+}
+
+/**
+ * Soft-apply an undo/redo restore to the live preview WITHOUT a full iframe
+ * remount (which blanks the frame black and re-flashes the WebGL context). Only
+ * the active composition — the document living in the root iframe — is eligible;
+ * a sub-comp or multi-file restore falls back to `reloadPreview`.
+ *
+ * The restore is soft-applied when its only differences are id'd-element
+ * attributes / inline-style and/or the GSAP script (see diffSoftReloadableRestore):
+ *   1. Each changed element's attribute surface (inline style, data-start /
+ *      -duration, the studio manual-offset props + flags) is synced onto the live
+ *      element — so a canvas-position revert lands on the live DOM the runtime's
+ *      seek-reapply reads from, not just on disk.
+ *   2. The restored GSAP script is re-run in place via applySoftReload, which
+ *      re-seeks to `currentTime` (playhead-invariant) and re-folds manual edits.
+ *      With no single script, the manual-edit reapply is invoked directly.
+ *
+ * Returns "soft" when applied in place, "full" when it escalated to reloadPreview
+ * (ineligible restore, missing target, or a permanent soft-reload failure).
+ */
+export function applyUndoRestoreToPreview(
+  iframe: HTMLIFrameElement | null,
+  activeCompPath: string | null,
+  files: Record<string, UndoRestoreFile> | undefined,
+  currentTime: number,
+  reloadPreview: () => void,
+): "soft" | "full" {
+  const paths = files ? Object.keys(files) : [];
+  // Soft path only covers the single active-comp document in the root iframe.
+  if (!iframe || !activeCompPath || !files || paths.length !== 1 || paths[0] !== activeCompPath) {
+    reloadPreview();
+    return "full";
+  }
+  const doc = iframe.contentDocument;
+  const win = iframe.contentWindow as IframeWindow | null;
+  if (!doc || !win) {
+    reloadPreview();
+    return "full";
+  }
+  const { previous, restored } = files[activeCompPath]!;
+  const diff = diffSoftReloadableRestore(previous, restored);
+  if (!diff) {
+    reloadPreview();
+    return "full";
+  }
+
+  // Sync each changed element's attributes onto the live DOM from the restored
+  // markup, so the runtime's seek-reapply (which reads inline offset props off
+  // the live element) folds the REVERTED values, not the stale current ones.
+  const restoredById = idElementMap(new DOMParser().parseFromString(restored, "text/html"));
+  for (const id of diff.changedElementIds) {
+    const liveEl = doc.getElementById(id);
+    const restoredEl = restoredById.get(id);
+    if (liveEl && restoredEl) syncElementAttributes(liveEl, restoredEl);
+  }
+
+  const script = extractGsapScriptText(restored);
+  if (script) {
+    const result = applySoftReload(iframe, script, {
+      onAsyncFailure: reloadPreview,
+      currentTimeOverride: currentTime,
+    });
+    if (result === "cannot-soft-reload") {
+      reloadPreview();
+      return "full";
+    }
+    return "soft";
+  }
+  // No single GSAP script to re-run — the change was pure attribute/style. Re-fold
+  // manual edits and hold the playhead so the synced attributes take visible effect.
+  try {
+    win.__player?.seek?.(currentTime);
+    win.__hfStudioManualEditsApply?.();
+  } catch {
+    reloadPreview();
+    return "full";
+  }
+  return "soft";
+}
+
 export function applySoftReload(
   iframe: HTMLIFrameElement | null,
   scriptText: string,

package/src/utils/mediaTypes.ts

@@ -1,9 +1,10 @@
-export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i;
+export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|avif|svg|ico)$/i;
 export const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
 export const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
 export const FONT_EXT = /\.(woff|woff2|ttf|ttc|otf|eot)$/i;
 export const LUT_EXT = /\.cube$/i;
-export const MEDIA_EXT = /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|svg|ico)$/i;
+export const MEDIA_EXT =
+  /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|avif|svg|ico)$/i;
 
 export function isMediaFile(path: string): boolean {
   return MEDIA_EXT.test(path);

package/src/utils/resizeDebug.ts

@@ -0,0 +1,55 @@
+// Resize/gesture diagnostics — grep [hf-resize]. Off by default; opt in per
+// session with `localStorage.setItem("hf-resize-debug", "1")` (then reload).
+// Granular per-move/per-gesture tracing that complements the always-on
+// [hf-commit] transaction telemetry in gestureTransaction.ts.
+let moveN = 0;
+let enabled: boolean | null = null;
+
+function isEnabled(): boolean {
+  if (enabled === null) {
+    try {
+      enabled = localStorage.getItem("hf-resize-debug") === "1";
+    } catch {
+      enabled = false;
+    }
+  }
+  return enabled;
+}
+
+export function logResize(stage: string, data: Record<string, unknown>): void {
+  if (!isEnabled()) return;
+  console.log(
+    `[hf-resize] ${JSON.stringify({ stage, t: Math.round(performance.now()), ...data })}`,
+  );
+}
+
+/** Per-pointermove logging, throttled: first move then every 8th. */
+export function logResizeMove(data: Record<string, unknown>): void {
+  if (!isEnabled()) return;
+  moveN += 1;
+  if (moveN % 8 === 1) logResize("move", { n: moveN, ...data });
+}
+
+export function resetResizeMoveLog(): void {
+  moveN = 0;
+}
+
+/** Snapshot the element's live geometry now and again after 200ms (jump detector). */
+export function logResizeSettle(el: HTMLElement, tag: string): void {
+  if (!isEnabled()) return;
+  const snap = (phase: string) => {
+    const r = el.getBoundingClientRect();
+    const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
+    logResize("settle", {
+      tag,
+      phase,
+      rect: { x: r.x, y: r.y, w: r.width, h: r.height },
+      cssW: cs?.width,
+      cssH: cs?.height,
+      transform: cs?.transform,
+      inlineStyle: el.getAttribute("style"),
+    });
+  };
+  snap("t0");
+  setTimeout(() => snap("t200"), 200);
+}

package/src/utils/rootDuration.test.ts

@@ -1,5 +1,10 @@
+// @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
-import { extendRootDurationInSource } from "./rootDuration";
+import {
+  extendRootDurationInSource,
+  patchRootCompositionDuration,
+  readRootCompositionDuration,
+} from "./rootDuration";
 
 describe("extendRootDurationInSource", () => {
   it("extends data-duration when the new end is bigger than the root duration", () => {
@@ -31,4 +36,88 @@ describe("extendRootDurationInSource", () => {
     expect(patched).toContain(`<div data-duration="3"></div>`);
     expect(patched).toContain(`<div data-composition-id="main" data-duration="7"></div>`);
   });
+
+  // Reviewer round-2 finding #3: the old regex was attribute-ORDER-dependent and
+  // double-quotes-only, so these hand-authored variants silently no-op'd.
+  it("extends when data-duration is declared BEFORE data-composition-id", () => {
+    const source = `<div data-duration="4" data-composition-id="main"></div>`;
+    expect(extendRootDurationInSource(source, 9)).toBe(
+      `<div data-duration="9" data-composition-id="main"></div>`,
+    );
+  });
+
+  it("extends when attributes use single quotes", () => {
+    const source = `<div data-composition-id='main' data-duration='4'></div>`;
+    expect(extendRootDurationInSource(source, 9)).toBe(
+      `<div data-composition-id='main' data-duration='9'></div>`,
+    );
+  });
+
+  it("extends with swapped order AND single quotes AND extra whitespace", () => {
+    const source = `<div  data-duration = '4'  data-composition-id = 'main' >x</div>`;
+    expect(extendRootDurationInSource(source, 9)).toBe(
+      `<div  data-duration = '9'  data-composition-id = 'main' >x</div>`,
+    );
+  });
+});
+
+describe("readRootCompositionDuration", () => {
+  it("reads the root duration regardless of attribute order or quote style", () => {
+    expect(
+      readRootCompositionDuration(`<div data-composition-id="main" data-duration="4"></div>`),
+    ).toBe(4);
+    expect(
+      readRootCompositionDuration(`<div data-duration="4" data-composition-id="main"></div>`),
+    ).toBe(4);
+    expect(
+      readRootCompositionDuration(`<div data-composition-id='main' data-duration='4.5'></div>`),
+    ).toBe(4.5);
+  });
+
+  it("reads the FIRST composition when several are present", () => {
+    const source = [
+      `<div data-composition-id="root" data-duration="10"></div>`,
+      `<div data-composition-id="nested" data-duration="2"></div>`,
+    ].join("\n");
+    expect(readRootCompositionDuration(source)).toBe(10);
+  });
+
+  it("returns null when there is no composition root", () => {
+    expect(readRootCompositionDuration(`<div data-duration="4"></div>`)).toBeNull();
+  });
+
+  it("returns null when the root has no data-duration attribute", () => {
+    expect(readRootCompositionDuration(`<div data-composition-id="main"></div>`)).toBeNull();
+  });
+});
+
+describe("patchRootCompositionDuration", () => {
+  it("rewrites only the root's data-duration value, preserving surrounding bytes", () => {
+    const source = [
+      `<!doctype html>`,
+      `<div data-composition-id="main" data-duration="4" data-width="640">`,
+      `  <img src="a.png" data-duration="3" />`,
+      `</div>`,
+    ].join("\n");
+    const patched = patchRootCompositionDuration(source, "8");
+    expect(patched).toBe(
+      [
+        `<!doctype html>`,
+        `<div data-composition-id="main" data-duration="8" data-width="640">`,
+        `  <img src="a.png" data-duration="3" />`,
+        `</div>`,
+      ].join("\n"),
+    );
+  });
+
+  it("keeps single-quote style when rewriting", () => {
+    expect(
+      patchRootCompositionDuration(`<div data-composition-id='main' data-duration='4'></div>`, "8"),
+    ).toBe(`<div data-composition-id='main' data-duration='8'></div>`);
+  });
+
+  it("is a no-op when the root has no data-duration attribute", () => {
+    const source = `<div data-composition-id="main"></div>`;
+    expect(patchRootCompositionDuration(source, "8")).toBe(source);
+  });
 });

package/src/utils/rootDuration.ts

@@ -1,17 +1,80 @@
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 
-export function extendRootDurationInSource(source: string, newEnd: number): string {
-  const rootDurMatch = source.match(
-    /(<[^>]*data-composition-id="[^"]*"[^>]*data-duration=")([^"]*)(")/,
+/**
+ * Matches the opening tag of the ROOT composition element — the first tag that
+ * carries a `data-composition-id` attribute, regardless of where the attribute
+ * sits in the tag or how its value is quoted. `[^>]*` keeps the match inside a
+ * single tag, so the first hit is the first composition in document order (the
+ * same element `doc.querySelector("[data-composition-id]")` resolves to).
+ */
+const ROOT_COMPOSITION_OPEN_TAG_RE = /<[^>]*\bdata-composition-id(?=[\s=/>])[^>]*>/i;
+
+/**
+ * Matches a `data-duration="..."` attribute inside a single opening tag. Quote
+ * style is captured (backreferenced), so both `"` and `'` round-trip, and the
+ * `\s*` around `=` tolerates author whitespace.
+ */
+const DATA_DURATION_ATTR_RE = /(\bdata-duration\s*=\s*)(["'])[^"']*\2/i;
+
+/**
+ * Read the ROOT composition's raw `data-duration`.
+ *
+ * Parses the source with DOMParser and locates the root the same way the rest of
+ * the timeline code does — the first `[data-composition-id]` element in document
+ * order — then reads its `data-duration`. Because it works on the parsed tree,
+ * attribute order and quote style are irrelevant, unlike the previous
+ * order-dependent, double-quotes-only regex.
+ *
+ * Returns `null` when there is no root composition or the root has no
+ * `data-duration` attribute at all. When the attribute is present but not a
+ * number the parsed `NaN` is returned as-is, so callers reproduce the old
+ * regex's "attribute matched but value unusable" behavior.
+ *
+ * Deterministic and render-safe: DOMParser is the only DOM global used.
+ */
+export function readRootCompositionDuration(source: string): number | null {
+  const root = new DOMParser()
+    .parseFromString(source, "text/html")
+    .querySelector("[data-composition-id]");
+  const raw = root?.getAttribute("data-duration");
+  if (raw == null) return null;
+  return Number.parseFloat(raw);
+}
+
+/**
+ * Rewrite the ROOT composition's `data-duration` value, preserving the rest of
+ * the document byte-for-byte.
+ *
+ * We deliberately do NOT re-serialize the parsed Document: a DOMParser round-trip
+ * injects `<html>/<head>/<body>`, forces double quotes, self-closes void
+ * elements, and drops the original indentation — it reformats unrelated markup.
+ * Instead we locate the root opening tag and rewrite only its `data-duration`
+ * value in place, keeping the author's quote style. The targeted splice is
+ * attribute-order-, quote-, and whitespace-agnostic.
+ *
+ * No-op (returns `source` unchanged) when there is no root composition tag or the
+ * root tag has no `data-duration` attribute to replace.
+ */
+export function patchRootCompositionDuration(source: string, newValue: string): string {
+  const rootTag = ROOT_COMPOSITION_OPEN_TAG_RE.exec(source);
+  if (!rootTag) return source;
+  const patchedTag = rootTag[0].replace(
+    DATA_DURATION_ATTR_RE,
+    (_full, prefix: string, quote: string) => `${prefix}${quote}${newValue}${quote}`,
   );
-  if (rootDurMatch) {
-    const rootDur = parseFloat(rootDurMatch[2]!);
-    if (newEnd > rootDur) {
-      return source.replace(
-        rootDurMatch[0],
-        `${rootDurMatch[1]}${formatTimelineAttributeNumber(newEnd)}${rootDurMatch[3]}`,
-      );
-    }
-  }
-  return source;
+  if (patchedTag === rootTag[0]) return source;
+  return (
+    source.slice(0, rootTag.index) + patchedTag + source.slice(rootTag.index + rootTag[0].length)
+  );
+}
+
+/**
+ * Grow-only ratchet: extend the root composition's `data-duration` to `newEnd`
+ * when `newEnd` is larger than the current root duration. No-op otherwise (and
+ * when there is no root duration to compare against).
+ */
+export function extendRootDurationInSource(source: string, newEnd: number): string {
+  const current = readRootCompositionDuration(source);
+  if (current == null || !(newEnd > current)) return source;
+  return patchRootCompositionDuration(source, formatTimelineAttributeNumber(newEnd));
 }

package/src/utils/sdkCutover.ts

@@ -18,6 +18,7 @@ export interface CutoverDeps {
       label: string;
       kind: EditHistoryKind;
       coalesceKey?: string;
+      coalesceMs?: number;
       files: Record<string, { before: string; after: string }>;
     }) => Promise<void>;
   };
@@ -84,6 +85,8 @@ function wrongCompositionFile(deps: CutoverDeps, targetPath: string): boolean {
 interface CutoverOptions {
   label?: string;
   coalesceKey?: string;
+  /** Coalesce window (ms); Infinity folds across a slow round-trip. */
+  coalesceMs?: number;
   /** Skip the preview reload (mirrors the server path's skipRefresh). */
   skipRefresh?: boolean;
 }
@@ -110,6 +113,7 @@ export async function persistSdkSerialize(
     label: options?.label ?? "Edit layer",
     kind: "manual",
     ...(options?.coalesceKey ? { coalesceKey: options.coalesceKey } : {}),
+    ...(options?.coalesceMs != null ? { coalesceMs: options.coalesceMs } : {}),
     files: { [targetPath]: { before: originalContent, after } },
   });
   if (deps.refresh) deps.refresh(after);

package/src/utils/studioFileHistory.ts

@@ -1,25 +1,55 @@
+import type { MutableRefObject } from "react";
 import type { EditHistoryKind } from "./editHistory";
+import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
+
+export interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  coalesceMs?: number;
+  files: Record<string, { before: string; after: string }>;
+}
+
+export interface DomEditCommitBaseParams {
+  activeCompPath: string | null;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
+  projectIdRef: MutableRefObject<string | null>;
+  reloadPreview: () => void;
+  clearDomSelection: () => void;
+}
 
 interface SaveProjectFilesWithHistoryInput {
   projectId: string;
   label: string;
   kind: EditHistoryKind;
   coalesceKey?: string;
+  coalesceMs?: number;
   files: Record<string, string>;
   readFile: (path: string) => Promise<string>;
   writeFile: (path: string, content: string) => Promise<void>;
-  recordEdit: (entry: {
-    label: string;
-    kind: EditHistoryKind;
-    coalesceKey?: string;
-    files: Record<string, { before: string; after: string }>;
-  }) => Promise<void>;
+  recordEdit: (entry: RecordEditInput) => Promise<void>;
+}
+
+export async function readProjectFileContent(pid: string, path: string): Promise<string> {
+  const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(path)}`);
+  if (!response.ok) {
+    throw await createStudioSaveHttpError(response, `Failed to read ${path}`);
+  }
+  const data = (await response.json()) as { content?: string };
+  if (typeof data.content !== "string") {
+    throw new Error(`Missing file contents for ${path}`);
+  }
+  return data.content;
 }
 
 export async function saveProjectFilesWithHistory({
   label,
   kind,
   coalesceKey,
+  coalesceMs,
   files,
   readFile,
   writeFile,
@@ -43,7 +73,7 @@ export async function saveProjectFilesWithHistory({
       writtenPaths.push(path);
     }
 
-    await recordEdit({ label, kind, coalesceKey, files: snapshots });
+    await recordEdit({ label, kind, coalesceKey, coalesceMs, files: snapshots });
   } catch (error) {
     try {
       for (const path of writtenPaths.reverse()) {

package/src/utils/studioHelpers.ts

@@ -308,3 +308,65 @@ export async function resolveDroppedAssetDuration(
   media.load();
   return duration;
 }
+
+export async function resolveDroppedAssetDimensions(
+  projectId: string,
+  assetPath: string,
+  kind: TimelineAssetKind,
+): Promise<{ width: number; height: number } | null> {
+  if (kind === "audio") return null;
+  const src = `/api/projects/${projectId}/preview/${assetPath}`;
+
+  if (kind === "image") {
+    return new Promise((resolve) => {
+      const img = new Image();
+      const timeout = window.setTimeout(() => resolve(null), 3000);
+      img.addEventListener(
+        "load",
+        () => {
+          window.clearTimeout(timeout);
+          resolve(
+            img.naturalWidth > 0 && img.naturalHeight > 0
+              ? { width: img.naturalWidth, height: img.naturalHeight }
+              : null,
+          );
+        },
+        { once: true },
+      );
+      img.addEventListener(
+        "error",
+        () => {
+          window.clearTimeout(timeout);
+          resolve(null);
+        },
+        { once: true },
+      );
+      img.src = src;
+    });
+  }
+
+  return new Promise((resolve) => {
+    const video = document.createElement("video");
+    video.preload = "metadata";
+    const timeout = window.setTimeout(() => resolve(null), 3000);
+    const finalize = (value: { width: number; height: number } | null) => {
+      window.clearTimeout(timeout);
+      video.src = "";
+      video.load();
+      resolve(value);
+    };
+    video.addEventListener(
+      "loadedmetadata",
+      () => {
+        finalize(
+          video.videoWidth > 0 && video.videoHeight > 0
+            ? { width: video.videoWidth, height: video.videoHeight }
+            : null,
+        );
+      },
+      { once: true },
+    );
+    video.addEventListener("error", () => finalize(null), { once: true });
+    video.src = src;
+  });
+}

package/src/utils/studioPreviewHelpers.test.ts

@@ -25,6 +25,15 @@ function stubRect(el: Element, rect: DOMRect): void {
   el.getBoundingClientRect = () => rect;
 }
 
+/** Create and attach a preview iframe, returning it with its (asserted) document. */
+function createPreviewIframe(): { iframe: HTMLIFrameElement; doc: Document } {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("Expected iframe document");
+  return { iframe, doc };
+}
+
 describe("coversComposition (full-bleed canvas-pick exclusion)", () => {
   const viewport = { width: 1920, height: 1080 };
 
@@ -106,10 +115,7 @@ describe("pauseStudioPreviewPlayback", () => {
 
 describe("getPreviewTargetFromPointer", () => {
   it("skips candidates hidden from author hit-testing by inherited pointer-events:none", () => {
-    const iframe = document.createElement("iframe");
-    document.body.append(iframe);
-    const doc = iframe.contentDocument;
-    if (!doc) throw new Error("Expected iframe document");
+    const { iframe, doc } = createPreviewIframe();
 
     doc.body.innerHTML = `
       <main id="scene" data-composition-id="scene">
@@ -141,10 +147,7 @@ describe("getPreviewTargetFromPointer", () => {
   });
 
   it("honors a CSS-class pointer-events:auto opt-in under a pointer-events:none ancestor", () => {
-    const iframe = document.createElement("iframe");
-    document.body.append(iframe);
-    const doc = iframe.contentDocument;
-    if (!doc) throw new Error("Expected iframe document");
+    const { iframe, doc } = createPreviewIframe();
 
     doc.head.innerHTML = `<style>.clickable { pointer-events: auto; }</style>`;
     doc.body.innerHTML = `
@@ -172,4 +175,58 @@ describe("getPreviewTargetFromPointer", () => {
 
     iframe.remove();
   });
+
+  it("selects a full-bleed <video> instead of skipping to the element behind it", () => {
+    const { iframe, doc } = createPreviewIframe();
+
+    doc.body.innerHTML = `
+      <main id="scene" data-composition-id="scene">
+        <div id="backdrop"></div>
+        <video id="hero"></video>
+      </main>
+    `;
+
+    const scene = doc.getElementById("scene");
+    const backdrop = doc.getElementById("backdrop");
+    const hero = doc.getElementById("hero");
+    if (!scene || !backdrop || !hero) throw new Error("Expected preview fixture elements");
+
+    stubRect(iframe, domRect(0, 0, 400, 300));
+    stubRect(scene, domRect(0, 0, 400, 300));
+    stubRect(backdrop, domRect(0, 0, 400, 300));
+    // Full-bleed hero video painted on top of a full-bleed backdrop.
+    stubRect(hero, domRect(0, 0, 400, 300));
+    doc.elementsFromPoint = () => [hero, backdrop, scene];
+
+    // Before the fix the video was full-bleed-excluded and the picker fell through
+    // to the backdrop (or null). It must now return the video itself.
+    expect(getPreviewTargetFromPointer(iframe, 200, 150, "index.html")).toBe(hero);
+
+    iframe.remove();
+  });
+
+  it("still excludes a full-bleed non-media container so clicks reach inner content", () => {
+    const { iframe, doc } = createPreviewIframe();
+
+    doc.body.innerHTML = `
+      <main id="scene" data-composition-id="scene">
+        <div id="wrapper"><h1 id="headline">Title</h1></div>
+      </main>
+    `;
+
+    const scene = doc.getElementById("scene");
+    const wrapper = doc.getElementById("wrapper");
+    const headline = doc.getElementById("headline");
+    if (!scene || !wrapper || !headline) throw new Error("Expected preview fixture elements");
+
+    stubRect(iframe, domRect(0, 0, 400, 300));
+    stubRect(scene, domRect(0, 0, 400, 300));
+    stubRect(wrapper, domRect(0, 0, 400, 300));
+    stubRect(headline, domRect(40, 40, 160, 48));
+    doc.elementsFromPoint = () => [headline, wrapper, scene];
+
+    expect(getPreviewTargetFromPointer(iframe, 80, 64, "index.html")).toBe(headline);
+
+    iframe.remove();
+  });
 });