From 8c22ddba0fda22c3ec6faa83f4686249804d299d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sun, 1 Nov 2026 06:16:39 +0000
Subject: [PATCH] fix(cli): snapshot warns when self-closed audio or video
 clips have swallowed the page (#6915)

---
 .../commands/snapshot.selfClosedMedia.test.ts | 29 +++++++++++++++++++
 packages/cli/src/commands/snapshot.ts         | 22 ++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 packages/cli/src/commands/snapshot.selfClosedMedia.test.ts

diff --git a/packages/cli/src/commands/snapshot.selfClosedMedia.test.ts b/packages/cli/src/commands/snapshot.selfClosedMedia.test.ts
new file mode 100644
index 0000000000..9e2077c6d8
--- /dev/null
+++ b/packages/cli/src/commands/snapshot.selfClosedMedia.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { selfClosedMediaWarning } from "./snapshot.js";
+
+const page = (media: string) => `<!doctype html><html><body>
+<div id="root" data-composition-id="main" data-start="0" data-duration="10" data-width="1280" data-height="720">
+${media}
+<h1 id="title">Hello</h1></div></body></html>`;
+
+describe("selfClosedMediaWarning", () => {
+  it("names the self-closed clips and what they do to the still", async () => {
+    const clips = Array.from(
+      { length: 3 },
+      (_, i) => `<audio id="sfx${i}" src="s${i}.wav" data-start="${i}" data-duration="1" />`,
+    ).join("\n");
+
+    const warning = await selfClosedMediaWarning(page(clips));
+
+    expect(warning).toContain("3 self-closed <audio>/<video> tags");
+    expect(warning).toContain("#sfx0");
+    expect(warning).toContain("stills come out blank");
+  });
+
+  it("stays quiet when every clip has a closing tag, even with fallback content", async () => {
+    const closed = `<audio id="a" src="a.wav" data-start="0" data-duration="1"></audio>
+<video id="v" src="v.mp4" data-start="0" data-duration="2"><p>Your browser cannot play this.</p></video>`;
+
+    expect(await selfClosedMediaWarning(page(closed))).toBeNull();
+  });
+});
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index dc82ffb777..be5f52fc9a 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -938,6 +938,14 @@ export async function captureSnapshots(
   // Localize fonts (embed remote @font-face as data URIs, matching the render
   // path) so snapshots render the real font instead of a fallback sans.
   const html = await bundleWithLocalizedFonts(projectDir);
+  const entry = join(projectDir, "index.html");
+  const swallowed = existsSync(entry)
+    ? await selfClosedMediaWarning(readFileSync(entry, "utf8"))
+    : null;
+  if (swallowed) {
+    warnings.push(swallowed);
+    console.warn(`   ${c.warn("⚠")} ${swallowed}`);
+  }
   const server = await serveCapturePage(projectDir, html, opts.autoProxy);
 
   const savedPaths: string[] = [];
@@ -1506,6 +1514,20 @@ function warnUnsettledImages(images: UnsettledImages, time: number, warnings: st
   }
 }
 
+/** What the project's own lint says about self-closed clips, which hide the rest of the page and blank every still. */
+export async function selfClosedMediaWarning(source: string): Promise<string | null> {
+  const { lintHyperframeHtml } = await import("@hyperframes/lint");
+  const found = (await lintHyperframeHtml(source)).findings.filter(
+    (finding) => finding.code === "self_closing_media_tag",
+  );
+  if (found.length === 0) return null;
+  const ids = found.flatMap((finding) => (finding.elementId ? [`#${finding.elementId}`] : []));
+  return (
+    `index.html has ${found.length} self-closed <audio>/<video> tags${ids.length ? ` (${ids.slice(0, 3).join(", ")})` : ""}: ` +
+    "HTML leaves them open, so everything after the first one is hidden and stills come out blank. Write <audio ...></audio>."
+  );
+}
+
 function warnSnapshotsNotRecorded(error: unknown): undefined {
   console.warn(`   ${c.warn("⚠")} Snapshots were not recorded: ${normalizeErrorMessage(error)}`);
   return undefined;