fix(screenshot): hide overlays during capture so shots only contain page content (#64)

apps/extension/src/lib/__tests__/capture-suppress-bridge.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  CAPTURE_SUPPRESS,
+  type CaptureSuppressMessage,
+  withOverlaysHiddenForCapture,
+} from "../capture-suppress-bridge";
+
+function recordingSendToTab(events: string[]) {
+  return vi.fn(async (_tabId: number, message: CaptureSuppressMessage) => {
+    events.push(message.phase);
+    return { type: CAPTURE_SUPPRESS, ok: true };
+  });
+}
+
+describe("withOverlaysHiddenForCapture", () => {
+  it("sends begin → fn → end and returns fn's result", async () => {
+    const events: string[] = [];
+    const sendToTab = recordingSendToTab(events);
+
+    const result = await withOverlaysHiddenForCapture(
+      7,
+      async () => {
+        events.push("capture");
+        return "shot";
+      },
+      sendToTab,
+    );
+
+    expect(result).toBe("shot");
+    expect(events).toEqual(["begin", "capture", "end"]);
+    expect(sendToTab).toHaveBeenCalledWith(7, { type: CAPTURE_SUPPRESS, phase: "begin" });
+    expect(sendToTab).toHaveBeenCalledWith(7, { type: CAPTURE_SUPPRESS, phase: "end" });
+  });
+
+  it("still sends end when fn throws, then rethrows", async () => {
+    const events: string[] = [];
+    const sendToTab = recordingSendToTab(events);
+
+    await expect(
+      withOverlaysHiddenForCapture(
+        7,
+        async () => {
+          events.push("capture");
+          throw new Error("capture exploded");
+        },
+        sendToTab,
+      ),
+    ).rejects.toThrow("capture exploded");
+    expect(events).toEqual(["begin", "capture", "end"]);
+  });
+
+  it("captures directly when the tab has no content script", async () => {
+    const sendToTab = vi.fn(async () => {
+      throw new Error("Could not establish connection. Receiving end does not exist.");
+    });
+    const fn = vi.fn(async () => "shot");
+
+    const result = await withOverlaysHiddenForCapture(7, fn, sendToTab);
+
+    expect(result).toBe("shot");
+    expect(fn).toHaveBeenCalledTimes(1);
+    // begin failed → no matching end may be sent.
+    expect(sendToTab).toHaveBeenCalledTimes(1);
+  });
+
+  it("swallows end failures so the capture result stands", async () => {
+    const sendToTab = vi.fn(async (_tabId: number, message: CaptureSuppressMessage) => {
+      if (message.phase === "end") throw new Error("tab navigated away");
+      return { type: CAPTURE_SUPPRESS, ok: true };
+    });
+
+    const result = await withOverlaysHiddenForCapture(7, async () => "shot", sendToTab);
+
+    expect(result).toBe("shot");
+    expect(sendToTab).toHaveBeenCalledTimes(2);
+  });
+});

apps/extension/src/lib/capture-suppress-bridge.ts

@@ -0,0 +1,71 @@
+/**
+ * Wire protocol and background-side helper for hiding the extension's
+ * in-page overlay while a screenshot is captured, so captured frames only
+ * contain the page itself.
+ *
+ * The background wraps every capture in `withOverlaysHiddenForCapture`,
+ * which sends `begin` (the content script hides the overlay host and only
+ * acks once the compositor has produced an overlay-free frame) and always
+ * follows up with `end`, even when the capture throws. Tabs without the
+ * content script (chrome://, the Web Store, ...) host no overlay, so a
+ * failed `begin` falls through to capturing directly.
+ */
+
+export const CAPTURE_SUPPRESS = "bsk/capture-suppress";
+
+export type CaptureSuppressPhase = "begin" | "end";
+
+export interface CaptureSuppressMessage {
+  type: typeof CAPTURE_SUPPRESS;
+  phase: CaptureSuppressPhase;
+}
+
+export interface CaptureSuppressAck {
+  type: typeof CAPTURE_SUPPRESS;
+  ok: true;
+}
+
+export function isCaptureSuppressMessage(msg: unknown): msg is CaptureSuppressMessage {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  return m.type === CAPTURE_SUPPRESS && (m.phase === "begin" || m.phase === "end");
+}
+
+/** Minimal `chrome.tabs.sendMessage` surface so tests can inject a fake. */
+export type CaptureSuppressSendToTab = (
+  tabId: number,
+  message: CaptureSuppressMessage,
+) => Promise<unknown>;
+
+const defaultSendToTab: CaptureSuppressSendToTab = (tabId, message) =>
+  chrome.tabs.sendMessage(tabId, message);
+
+/**
+ * Run `fn` with the target tab's overlay hidden. `end` is sent from a
+ * `finally` so the overlay always reappears, and a missing content script
+ * (or any other `begin` failure) simply skips suppression — there is no
+ * overlay to hide in that tab.
+ */
+export async function withOverlaysHiddenForCapture<T>(
+  tabId: number,
+  fn: () => Promise<T>,
+  sendToTab: CaptureSuppressSendToTab = defaultSendToTab,
+): Promise<T> {
+  let began = false;
+  try {
+    await sendToTab(tabId, { type: CAPTURE_SUPPRESS, phase: "begin" });
+    began = true;
+  } catch {
+    // No content script in the target tab → no overlay can leak into the
+    // capture; proceed without suppression.
+  }
+  try {
+    return await fn();
+  } finally {
+    if (began) {
+      await sendToTab(tabId, { type: CAPTURE_SUPPRESS, phase: "end" }).catch((err) => {
+        console.debug("[bsk capture] overlay restore failed", err);
+      });
+    }
+  }
+}