From 465128d00201dc931e2bee0396d07cdbe167ce4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sun, 1 Nov 2026 22:22:18 +0000
Subject: [PATCH] fix(cli): media-treatment says which media the file has when
 the selector matches none (#6958)

---
 .../cli/src/commands/media-treatment.test.ts   | 18 ++++++++++++++++++
 packages/cli/src/commands/media-treatment.ts   | 16 +++++++++++++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/cli/src/commands/media-treatment.test.ts b/packages/cli/src/commands/media-treatment.test.ts
index 761543a30c..c7eb8d2ed9 100644
--- a/packages/cli/src/commands/media-treatment.test.ts
+++ b/packages/cli/src/commands/media-treatment.test.ts
@@ -222,6 +222,24 @@ describe("applyMediaTreatmentToHtml", () => {
     expect(result.html).toContain("data-color-grading=");
   });
 
+  it("says what media the file has when the selector matches none", () => {
+    expect(() => applyMediaTreatmentToHtml(VIDEO, { selector: "#prepared", grading: {} })).toThrow(
+      "Selector did not match: #prepared. Media in the file: video#hero.",
+    );
+    expect(() =>
+      applyMediaTreatmentToHtml(SEGMENTS, { selector: "#prepared", grading: {} }),
+    ).toThrow('video[src="a.mp4"], video[src="b.mp4"].');
+  });
+
+  it("says the file has no media yet when preparation added none", () => {
+    expect(() =>
+      applyMediaTreatmentToHtml("<!doctype html><html><body></body></html>", {
+        selector: "#prepared",
+        grading: {},
+      }),
+    ).toThrow("Selector did not match: #prepared. The file has no <video>, <img> or <canvas> yet.");
+  });
+
   it("treats every video a selector matches alike", () => {
     const result = applyMediaTreatmentToHtml(SEGMENTS, {
       selector: "video",
diff --git a/packages/cli/src/commands/media-treatment.ts b/packages/cli/src/commands/media-treatment.ts
index 73afaa5179..ea7af011d9 100644
--- a/packages/cli/src/commands/media-treatment.ts
+++ b/packages/cli/src/commands/media-treatment.ts
@@ -460,6 +460,18 @@ function queryIncludingTemplates(root: Document | Element, selector: string): El
   return [];
 }
 
+function describeMediaInDocument(document: Document): string {
+  const media = queryIncludingTemplates(document, "video, img, canvas");
+  if (media.length === 0) return "The file has no <video>, <img> or <canvas> yet.";
+  const shown = media.slice(0, 5).map((element) => {
+    const tag = element.tagName.toLowerCase();
+    const id = element.getAttribute("id");
+    return id ? `${tag}#${id}` : `${tag}[src="${element.getAttribute("src") ?? ""}"]`;
+  });
+  const more = media.length > shown.length ? ` and ${media.length - shown.length} more` : "";
+  return `Media in the file: ${shown.join(", ")}${more}.`;
+}
+
 type MediaTarget = { element: Element; selectorIndex: number; tag: GradingSourceTag };
 
 function selectMediaElements(
@@ -473,7 +485,9 @@ function selectMediaElements(
   } catch {
     throw new Error(`Invalid selector: ${selector}`);
   }
-  if (matches.length === 0) throw new Error(`Selector did not match: ${selector}`);
+  if (matches.length === 0) {
+    throw new Error(`Selector did not match: ${selector}. ${describeMediaInDocument(document)}`);
+  }
   if (selectorIndex !== undefined && !matches[selectorIndex]) {
     throw new Error(`--selector-index ${selectorIndex} is outside ${matches.length} matches`);
   }