From e3706392155f76fc4125333ae709cd49e4234841 Mon Sep 17 00:00:00 2001
From: Kamran Ahmed <kamranahmed.se@gmail.com>
Date: Thu, 29 Oct 2026 01:19:30 +0000
Subject: [PATCH] Keep hint layer unstyled by page popover rules

---
 apps/docs/src/content/guides/changelog.mdx |  6 +++++
 packages/driver/src/popover.css            | 29 ++++++++++++----------
 packages/driver/tests/hints.test.ts        | 22 ++++++++++++++++
 3 files changed, 44 insertions(+), 13 deletions(-)

diff --git a/apps/docs/src/content/guides/changelog.mdx b/apps/docs/src/content/guides/changelog.mdx
index 7079932..af50b21 100644
--- a/apps/docs/src/content/guides/changelog.mdx
+++ b/apps/docs/src/content/guides/changelog.mdx
@@ -10,6 +10,12 @@ ships, these entries move under a versioned heading.
 
 ## Unreleased
 
+### Fixed
+
+- Hints in an open `<dialog>` no longer get covered when the page styles
+  every `[popover]`, for example with a dark background.
+  ([#628](https://github.com/nilbuild/driver.js/issues/628))
+
 ## 1.10.2
 
 ### Fixed
diff --git a/packages/driver/src/popover.css b/packages/driver/src/popover.css
index 9bfcdf4..6710993 100644
--- a/packages/driver/src/popover.css
+++ b/packages/driver/src/popover.css
@@ -4,19 +4,22 @@
    classes) out of here. */
 
 .driver-layer {
-  position: fixed;
-  inset: 0;
-  width: auto;
-  height: auto;
-  max-width: none;
-  max-height: none;
-  margin: 0;
-  padding: 0;
-  border: 0;
-  background: transparent;
-  color: inherit;
-  overflow: visible;
-  pointer-events: none;
+  position: fixed !important;
+  top: 0 !important;
+  right: 0 !important;
+  bottom: 0 !important;
+  left: 0 !important;
+  width: auto !important;
+  height: auto !important;
+  max-width: none !important;
+  max-height: none !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+  color: inherit !important;
+  overflow: visible !important;
+  pointer-events: none !important;
 }
 
 .driver-layer::backdrop {
diff --git a/packages/driver/tests/hints.test.ts b/packages/driver/tests/hints.test.ts
index afb30ff..401da40 100644
--- a/packages/driver/tests/hints.test.ts
+++ b/packages/driver/tests/hints.test.ts
@@ -1,3 +1,5 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { driver, type Driver } from "../src/driver";
 import { hints, type DriverHint, type Hints } from "../src/hints";
@@ -1018,6 +1020,26 @@ describe("modal dialogs", () => {
       expect(dialog.querySelectorAll(".driver-layer")).toHaveLength(1);
     });
 
+    it("keeps the host unstyled when the page styles every popover", () => {
+      const style = document.createElement("style");
+      style.textContent = `${readFileSync(resolve(process.cwd(), "src/popover.css"), "utf8")}
+        html [popover] { background-color: rgb(1, 2, 3); padding: 12px; top: 40px; }`;
+      document.head.appendChild(style);
+      document.body.insertAdjacentHTML("beforeend", DIALOG_HTML);
+
+      const h = createHints({ hints: [DIALOG_HINT] });
+      h.show();
+
+      const layer = document.querySelector(".driver-layer")!;
+      const computed = getComputedStyle(layer);
+      expect(computed.backgroundColor).toBe("rgba(0, 0, 0, 0)");
+      expect(computed.paddingTop).toBe("0px");
+      expect(computed.top).toBe("0px");
+
+      h.hide();
+      style.remove();
+    });
+
     it("removes the host once its UI is gone", () => {
       document.body.insertAdjacentHTML("beforeend", DIALOG_HTML);
       const dialog = document.querySelector("dialog")!;