diff --git a/README.md b/README.md
index 909f4f2..fb18a14 100644
--- a/README.md
+++ b/README.md
@@ -351,6 +351,23 @@ export default defineConfig({
 });
 ```
 
+### Popups
+
+Pages you never wrap (popups, `context.newPage()`) fall through to plain Playwright. To get plugin behavior in a popup — an OAuth window, say — wrap it with a second `addPlugins` call, using **fresh plugin instances**:
+
+```ts
+const popupPromise = page.waitForEvent("popup");
+await page.getByRole("button", { name: "Sign in" }).click();
+await using popup = await addPlugins({
+  page: await popupPromise,
+  testInfo,
+  plugins: [spinnerWaiter(), videoMode()],
+});
+await popup.getByRole("button", { name: "Approve" }).click();
+```
+
+Playwright screencasts each page separately, so the popup's `videoMode` produces its own video; its artifacts get a `-2` suffix (`video-rendered-2.webm`, `video-mode-2.json`, …) so they sit next to the main page's in the same output dir. Reusing the main page's `videoMode` instance on the popup would wipe the main timeline, so it throws instead — one instance per page. See [spec/popup.spec.ts](spec/popup.spec.ts).
+
 ## Writing your own plugin
 
 **Writing your own plugins is the intended way to use this package.** The bundled five exist because they were useful for one particular app; your app has its own loading conventions, error surfaces, and flake patterns. Each bundled plugin is one small self-contained file — use them as inspiration: [spinner-waiter](./src/plugins/spinner-waiter.ts) (conditional waiting + error enrichment + runtime settings via `AsyncLocalStorage`), [hydration-waiter](./src/plugins/hydration-waiter.ts) (the simplest one — start here), [ui-error-reporter](./src/plugins/ui-error-reporter.ts) (catch/enrich/rethrow), [video-mode](./src/plugins/video-mode.ts) (video annotations/artifacts + lifecycle hooks), [llm-recover](./src/plugins/llm-recover.ts) (recovery loops, artifacts, soft assertions). The source also ships inside the npm package, so it's right there in `node_modules/middlewright/src`.
diff --git a/spec/auth-demo-app.ts b/spec/auth-demo-app.ts
new file mode 100644
index 0000000..2ee91e8
--- /dev/null
+++ b/spec/auth-demo-app.ts
@@ -0,0 +1,60 @@
+import type { BrowserContext } from "@playwright/test";
+
+/**
+ * app.middlewright.test shows a Sign in button that opens an auth popup on
+ * auth.middlewright.test; approving there posts a message back to the opener,
+ * which then shows who signed in. Routed on the context so the popup page is
+ * covered too.
+ */
+const demoStyle = `
+  <style>
+    body { font-family: system-ui, sans-serif; display: grid; place-items: center; min-height: 90vh; background: #f4f4f5; }
+    main { background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px 48px; text-align: center; }
+    h1 { font-size: 22px; margin: 0 0 16px; }
+    button { font-size: 16px; padding: 10px 24px; border-radius: 8px; border: none; background: #4f46e5; color: white; cursor: pointer; }
+    output { display: block; margin-top: 16px; font-size: 16px; color: #16a34a; }
+  </style>
+`;
+
+export const routeAuthDemoApp = async (context: BrowserContext) => {
+  await context.route("https://app.middlewright.test/**", async (route) => {
+    await route.fulfill({
+      body: `
+        ${demoStyle}
+        <main>
+          <h1>middlewright dashboard</h1>
+          <button id="signin">Sign in</button>
+          <output></output>
+          <script>
+            document.querySelector("#signin").addEventListener("click", () => {
+              window.open("https://auth.middlewright.test/authorize");
+            });
+            window.addEventListener("message", (event) => {
+              if (event.data === "approved") {
+                document.querySelector("output").textContent = "Signed in as mmkal";
+              }
+            });
+          </script>
+        </main>
+      `,
+      contentType: "text/html",
+    });
+  });
+  await context.route("https://auth.middlewright.test/**", async (route) => {
+    await route.fulfill({
+      body: `
+        ${demoStyle}
+        <main>
+          <h1>Authorize middlewright?</h1>
+          <button id="approve">Approve</button>
+          <script>
+            document.querySelector("#approve").addEventListener("click", () => {
+              window.opener.postMessage("approved", "*");
+            });
+          </script>
+        </main>
+      `,
+      contentType: "text/html",
+    });
+  });
+};
diff --git a/spec/popup-video.spec.ts b/spec/popup-video.spec.ts
new file mode 100644
index 0000000..6f81c06
--- /dev/null
+++ b/spec/popup-video.spec.ts
@@ -0,0 +1,48 @@
+import { stat } from "node:fs/promises";
+import { test, expect } from "@playwright/test";
+import { addPlugins, videoMode } from "../src/index.ts";
+import { routeAuthDemoApp } from "./auth-demo-app.ts";
+
+test.use({ video: "on" });
+
+test("records separate videos for the main page and an auth popup", async ({
+  page: basePage,
+  context,
+}, testInfo) => {
+  await routeAuthDemoApp(context);
+  const video = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+  let popupVideo!: ReturnType<typeof videoMode>;
+  {
+    await using page = await addPlugins({ page: basePage, testInfo, plugins: [video] });
+    await page.goto("https://app.middlewright.test/");
+
+    const popupPromise = basePage.waitForEvent("popup");
+    await page.getByRole("button", { name: "Sign in" }).click();
+    popupVideo = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+    await using popup = await addPlugins({
+      page: await popupPromise,
+      testInfo,
+      plugins: [popupVideo],
+    });
+
+    await popup.getByRole("button", { name: "Approve" }).click();
+    await page.getByText("Signed in as mmkal").waitFor();
+  }
+
+  // Playwright screencasts each page separately, so each instance ends the
+  // test with its own raw recording and its own annotated render.
+  await expect(video.metadata()).resolves.toMatchObject({
+    outputs: { raw: "video-raw.webm", rendered: "video-rendered.webm" },
+  });
+  await expect(popupVideo.metadata()).resolves.toMatchObject({
+    outputs: { raw: "video-raw-2.webm", rendered: "video-rendered-2.webm" },
+  });
+  for (const path of [
+    video.outputPaths().raw,
+    video.outputPaths().rendered,
+    popupVideo.outputPaths().raw,
+    popupVideo.outputPaths().rendered,
+  ]) {
+    expect((await stat(path)).size).toBeGreaterThan(0);
+  }
+});
diff --git a/spec/popup.spec.ts b/spec/popup.spec.ts
new file mode 100644
index 0000000..8f2fae3
--- /dev/null
+++ b/spec/popup.spec.ts
@@ -0,0 +1,88 @@
+import { test, expect } from "@playwright/test";
+import { addPlugins, videoMode } from "../src/index.ts";
+import { routeAuthDemoApp } from "./auth-demo-app.ts";
+
+test("a popup wrapped with addPlugins runs actions through its own plugins", async ({
+  page: basePage,
+  context,
+}, testInfo) => {
+  await routeAuthDemoApp(context);
+  const video = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+  await using page = await addPlugins({ page: basePage, testInfo, plugins: [video] });
+  await page.goto("https://app.middlewright.test/");
+
+  const popupPromise = basePage.waitForEvent("popup");
+  await page.getByRole("button", { name: "Sign in" }).click();
+  const popupVideo = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+  await using popup = await addPlugins({
+    page: await popupPromise,
+    testInfo,
+    plugins: [popupVideo],
+  });
+
+  await popup.getByRole("button", { name: "Approve" }).click();
+  await page.getByText("Signed in as mmkal").waitFor();
+
+  // The popup's click went through the popup's own video-mode middleware...
+  await expect(popupVideo.metadata()).resolves.toMatchObject({
+    highlights: [{ method: "click" }],
+  });
+  // ...and the main page's timeline has only the main page's actions.
+  await expect(video.metadata()).resolves.toMatchObject({
+    highlights: [{ method: "click" }, { method: "waitFor" }],
+  });
+});
+
+test("each videoMode instance still owns its artifacts after the test", async ({
+  page: basePage,
+  context,
+}, testInfo) => {
+  await routeAuthDemoApp(context);
+  const video = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+  let popupVideo!: ReturnType<typeof videoMode>;
+  {
+    await using page = await addPlugins({ page: basePage, testInfo, plugins: [video] });
+    await page.goto("https://app.middlewright.test/");
+
+    const popupPromise = basePage.waitForEvent("popup");
+    await page.getByRole("button", { name: "Sign in" }).click();
+    popupVideo = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+    await using popup = await addPlugins({
+      page: await popupPromise,
+      testInfo,
+      plugins: [popupVideo],
+    });
+
+    await popup.getByRole("button", { name: "Approve" }).click();
+    await page.getByText("Signed in as mmkal").waitFor();
+  }
+
+  // Both pages have finalized. Each instance must write its own artifacts and
+  // read back its own timeline — not whichever page finalized last.
+  expect(popupVideo.outputPaths().metadata).not.toBe(video.outputPaths().metadata);
+  await expect(video.metadata()).resolves.toMatchObject({
+    highlights: [{ method: "click" }, { method: "waitFor" }],
+  });
+  await expect(popupVideo.metadata()).resolves.toMatchObject({
+    highlights: [{ method: "click" }],
+  });
+});
+
+test("reusing one videoMode instance on a popup fails with a clear error", async ({
+  page: basePage,
+  context,
+}, testInfo) => {
+  await routeAuthDemoApp(context);
+  const video = videoMode({ finalHold: 0, highlight: { mode: "outline", duration: 300 }, trimStart: "never" });
+  await using page = await addPlugins({ page: basePage, testInfo, plugins: [video] });
+  await page.goto("https://app.middlewright.test/");
+
+  const popupPromise = basePage.waitForEvent("popup");
+  await page.getByRole("button", { name: "Sign in" }).click();
+
+  // Wiring the same instance to a second page would wipe the main page's
+  // timeline, so it must fail loudly instead.
+  await expect(
+    addPlugins({ page: await popupPromise, testInfo, plugins: [video] }),
+  ).rejects.toThrow("create a fresh videoMode() instance for each page");
+});
diff --git a/src/plugins/video-mode.ts b/src/plugins/video-mode.ts
index bc0e566..3f44357 100644
--- a/src/plugins/video-mode.ts
+++ b/src/plugins/video-mode.ts
@@ -265,6 +265,8 @@ export type VideoModeTrimStart = "auto" | "detect-blank" | "never" | ["selector"
 
 type VideoModeState = {
   addressBars: VideoModeAddressBar[];
+  /** Distinguishes artifact filenames when a test has several instances. */
+  artifactSuffix: string;
   captions: VideoModeCaption[];
   deadAirDepth: number;
   deadAirSpans: VideoModeSpan[];
@@ -862,13 +864,35 @@ const recordCaption = async <T>(
   }
 };
 
-const videoModeOutputPaths = (testInfo: TestInfo): VideoModeOutputPaths => {
+/**
+ * Insert a per-instance suffix before the extension: `video-mode.json` →
+ * `video-mode-2.json`. The first instance in a test keeps the unsuffixed
+ * names, so single-page tests are unaffected.
+ */
+const suffixArtifactFileName = (fileName: string, artifactSuffix: string) => {
+  if (!artifactSuffix) return fileName;
+  const extension = extname(fileName);
+  return `${fileName.slice(0, fileName.length - extension.length)}${artifactSuffix}${extension}`;
+};
+
+/**
+ * Registrations per testInfo.outputDir. Each videoMode instance added within
+ * one test (e.g. a fresh instance for a popup) gets its own artifact
+ * namespace so it can't clobber the main page's files.
+ */
+const videoModeRegistrationCounts = new Map<string, number>();
+
+const videoModeOutputPaths = (
+  testInfo: TestInfo,
+  artifactSuffix: string,
+): VideoModeOutputPaths => {
+  const name = (fileName: string) => suffixArtifactFileName(fileName, artifactSuffix);
   return {
-    metadata: join(testInfo.outputDir, VIDEO_MODE_METADATA_FILE),
-    player: join(testInfo.outputDir, VIDEO_MODE_PLAYER_FILE),
-    raw: join(testInfo.outputDir, VIDEO_MODE_RAW_FILE),
-    rendered: join(testInfo.outputDir, VIDEO_MODE_RENDERED_FILE),
-    reportPlayer: join(testInfo.outputDir, VIDEO_MODE_REPORT_PLAYER_FILE),
+    metadata: join(testInfo.outputDir, name(VIDEO_MODE_METADATA_FILE)),
+    player: join(testInfo.outputDir, name(VIDEO_MODE_PLAYER_FILE)),
+    raw: join(testInfo.outputDir, name(VIDEO_MODE_RAW_FILE)),
+    rendered: join(testInfo.outputDir, name(VIDEO_MODE_RENDERED_FILE)),
+    reportPlayer: join(testInfo.outputDir, name(VIDEO_MODE_REPORT_PLAYER_FILE)),
   };
 };
 
@@ -1258,8 +1282,8 @@ const recordHighlight = async (options: {
         : undefined;
 
     const image = pan
-      ? `video-mode-pan-${options.state.highlightImageIndex}.png`
-      : `video-mode-highlight-${options.state.highlightImageIndex}.png`;
+      ? `video-mode-pan${options.state.artifactSuffix}-${options.state.highlightImageIndex}.png`
+      : `video-mode-highlight${options.state.artifactSuffix}-${options.state.highlightImageIndex}.png`;
     options.state.highlightImageIndex += 1;
     const imagePath = join(options.testInfo.outputDir, image);
     await mkdir(options.testInfo.outputDir, { recursive: true });
@@ -1546,7 +1570,7 @@ const recordFillReveal = async (options: {
       return;
     }
 
-    const image = `video-mode-fill-${options.state.highlightImageIndex}.png`;
+    const image = `video-mode-fill${options.state.artifactSuffix}-${options.state.highlightImageIndex}.png`;
     options.state.highlightImageIndex += 1;
     await mkdir(options.testInfo.outputDir, { recursive: true });
     await options.locator.page().screenshot({
@@ -3580,7 +3604,7 @@ const playwrightReportAttachmentName = async (path: string) => {
   return `${createHash("sha1").update(data).digest("hex")}${extname(path)}`;
 };
 
-const videoModePlayerHtml = (options: { raw: string; rendered?: string }) => {
+const videoModePlayerHtml = (options: { metadata: string; raw: string; rendered?: string }) => {
   const primary = options.rendered || options.raw;
   const primaryLabel = options.rendered ? "Rendered video" : "Raw video";
   const primaryActiveKey = options.rendered ? "rendered" : "raw";
@@ -3724,7 +3748,7 @@ const videoModePlayerHtml = (options: { raw: string; rendered?: string }) => {
       <div>frame: <span id="frame">0</span></div>
       <div>duration: <span id="duration">?</span>s</div>
       <div class="hint">Left/right steps one frame. Shift+left/right steps ten. Space toggles play.</div>
-      <div class="hint"><a href="${VIDEO_MODE_METADATA_FILE}">${VIDEO_MODE_METADATA_FILE}</a></div>
+      <div class="hint"><a href="${options.metadata}">${options.metadata}</a></div>
     </aside>
   </main>
   <script>
@@ -3840,6 +3864,7 @@ const videoModePlayerHtml = (options: { raw: string; rendered?: string }) => {
 
 const renderVideo = async (options: {
   addressBars: VideoModeAddressBar[];
+  artifactSuffix: string;
   captions: VideoModeCaption[];
   dialogPostFrame: { path: string; viewport: VideoModeViewport } | undefined;
   dialogPostHoldMs: number;
@@ -3968,7 +3993,7 @@ const renderVideo = async (options: {
   );
   const captionFile =
     renderedAddressBars.length > 0 || renderedCaptions.length > 0
-      ? join(options.outputDir, VIDEO_MODE_CAPTIONS_FILE)
+      ? join(options.outputDir, suffixArtifactFileName(VIDEO_MODE_CAPTIONS_FILE, options.artifactSuffix))
       : undefined;
 
   if (captionFile) {
@@ -3982,7 +4007,9 @@ const renderVideo = async (options: {
     );
   }
   const dialogFile =
-    renderedDialogs.length > 0 ? join(options.outputDir, VIDEO_MODE_DIALOGS_FILE) : undefined;
+    renderedDialogs.length > 0
+      ? join(options.outputDir, suffixArtifactFileName(VIDEO_MODE_DIALOGS_FILE, options.artifactSuffix))
+      : undefined;
 
   if (dialogFile) {
     await writeFile(
@@ -4076,7 +4103,8 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
           throw new Error("videoMode.outputPaths() is only available after addPlugins registers videoMode");
         }
 
-        return videoModeOutputPaths(testInfoForOutputPaths);
+        // Debug mode writes no artifacts, so instances don't need namespacing.
+        return videoModeOutputPaths(testInfoForOutputPaths, "");
       },
       setEndTime: () => {},
       setStartTime: () => {},
@@ -4106,6 +4134,7 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
   const trimStart = resolveTrimStart(options.trimStart);
   const state: VideoModeState = {
     addressBars: [],
+    artifactSuffix: "",
     captions: [],
     deadAirDepth: 0,
     deadAirSpans: [],
@@ -4128,6 +4157,9 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
     return recording;
   };
   let testInfoForOutputPaths: TestInfo | undefined;
+  // Guards against wiring one instance to two pages at once (e.g. a popup):
+  // beforeTest resets state, so that would wipe the first page's timeline.
+  let activePage: Page | undefined;
   const getVideoTimestamp = () => {
     const now = performance.now();
     return Math.round(now - (state.startedAt || now));
@@ -4146,7 +4178,7 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
         return metadataFor(state);
       }
 
-      return await readVideoModeMetadata(videoModeOutputPaths(testInfoForOutputPaths).metadata, () =>
+      return await readVideoModeMetadata(videoModeOutputPaths(testInfoForOutputPaths, state.artifactSuffix).metadata, () =>
         metadataFor(state),
       );
     },
@@ -4155,7 +4187,7 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
         throw new Error("videoMode.outputPaths() is only available after addPlugins registers videoMode");
       }
 
-      return videoModeOutputPaths(testInfoForOutputPaths);
+      return videoModeOutputPaths(testInfoForOutputPaths, state.artifactSuffix);
     },
     setEndTime: (ms = getVideoTimestamp()) => {
       state.sourceRange.end = resolveVideoTimestamp("setEndTime", ms);
@@ -4169,7 +4201,16 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
     ...controls,
     name: "video-mode",
     pageExtension: ({ testInfo }) => {
+      if (activePage) {
+        throw new Error(
+          "this videoMode() instance is already recording another page - " +
+            "create a fresh videoMode() instance for each page (e.g. for a popup)",
+        );
+      }
       testInfoForOutputPaths = testInfo;
+      const registrations = (videoModeRegistrationCounts.get(testInfo.outputDir) || 0) + 1;
+      videoModeRegistrationCounts.set(testInfo.outputDir, registrations);
+      state.artifactSuffix = registrations === 1 ? "" : `-${registrations}`;
       return { videoMode: controls };
     },
 
@@ -4301,6 +4342,7 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
       let onDialog: ((dialog: Dialog) => void) | undefined;
       let stopObservingPlaywrightSteps = () => {};
       const offBeforeTest = emitter.on("beforeTest", async ({ page, testInfo }) => {
+        activePage = page;
         dialogHighlightQueue = Promise.resolve();
         state.addressBars = [];
         state.captions = [];
@@ -4476,7 +4518,7 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
         const video = page.video();
 
         if (video) {
-          const paths = videoModeOutputPaths(testInfo);
+          const paths = videoModeOutputPaths(testInfo, state.artifactSuffix);
           await mkdir(testInfo.outputDir, { recursive: true });
           let dialogPostFrame: { path: string; viewport: VideoModeViewport } | undefined;
           let finalFrame: { path: string; viewport: VideoModeViewport } | undefined;
@@ -4486,7 +4528,10 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
             if (!viewport) {
               throw new Error("videoMode cannot capture a post-dialog frame without a viewport");
             }
-            const path = join(testInfo.outputDir, VIDEO_MODE_DIALOG_POST_FRAME_FILE);
+            const path = join(
+              testInfo.outputDir,
+              suffixArtifactFileName(VIDEO_MODE_DIALOG_POST_FRAME_FILE, state.artifactSuffix),
+            );
             await page.screenshot({ path, scale: "css" });
             dialogPostFrame = { path, viewport };
           }
@@ -4496,7 +4541,10 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
             if (!viewport) {
               throw new Error("videoMode cannot capture a final frame without a viewport");
             }
-            const path = join(testInfo.outputDir, VIDEO_MODE_FINAL_FRAME_FILE);
+            const path = join(
+              testInfo.outputDir,
+              suffixArtifactFileName(VIDEO_MODE_FINAL_FRAME_FILE, state.artifactSuffix),
+            );
             await page.screenshot({ path, scale: "css" });
             finalFrame = { path, viewport };
           }
@@ -4527,8 +4575,8 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
           const recordedVideoPath = await video.path();
           await waitForNonEmptyFile(recordedVideoPath);
           await copyFile(recordedVideoPath, paths.raw);
-          state.outputs.raw = VIDEO_MODE_RAW_FILE;
-          await testInfo.attach("video-raw", {
+          state.outputs.raw = suffixArtifactFileName(VIDEO_MODE_RAW_FILE, state.artifactSuffix);
+          await testInfo.attach(`video-raw${state.artifactSuffix}`, {
             contentType: "video/webm",
             path: paths.raw,
           });
@@ -4621,6 +4669,7 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
           ) {
             const wroteRenderedVideo = await renderVideo({
               addressBars: renderTimeline.addressBars,
+              artifactSuffix: state.artifactSuffix,
               captions: renderTimeline.captions,
               deadAir: renderTimeline.deadAir,
               dialogPostFrame,
@@ -4638,31 +4687,40 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
             });
 
             if (wroteRenderedVideo) {
-              state.outputs.rendered = VIDEO_MODE_RENDERED_FILE;
-              await testInfo.attach("video-rendered", {
+              state.outputs.rendered = suffixArtifactFileName(
+                VIDEO_MODE_RENDERED_FILE,
+                state.artifactSuffix,
+              );
+              await testInfo.attach(`video-rendered${state.artifactSuffix}`, {
                 contentType: "video/webm",
                 path: paths.rendered,
               });
             }
           }
 
-          state.outputs.player = VIDEO_MODE_PLAYER_FILE;
+          state.outputs.player = suffixArtifactFileName(VIDEO_MODE_PLAYER_FILE, state.artifactSuffix);
+          const metadataFileName = suffixArtifactFileName(
+            VIDEO_MODE_METADATA_FILE,
+            state.artifactSuffix,
+          );
           await writeFile(
             paths.player,
             videoModePlayerHtml({
+              metadata: metadataFileName,
               raw: state.outputs.raw,
               rendered: state.outputs.rendered,
             }),
           );
 
           const reportPlayerHtml = videoModePlayerHtml({
+            metadata: metadataFileName,
             raw: await playwrightReportAttachmentName(paths.raw),
             rendered: state.outputs.rendered
               ? await playwrightReportAttachmentName(paths.rendered)
               : undefined,
           });
           await writeFile(paths.reportPlayer, reportPlayerHtml);
-          await testInfo.attach("video-mode-player", {
+          await testInfo.attach(`video-mode-player${state.artifactSuffix}`, {
             contentType: "text/html",
             path: paths.reportPlayer,
           });
@@ -4679,20 +4737,23 @@ export const videoMode = (options: VideoModeOptions = {}): VideoModePlugin => {
           metadata.outputs.rendered ||
           sourceRangeIsSet(metadata.sourceRange)
         ) {
-          const path = videoModeOutputPaths(testInfo).metadata;
+          const path = videoModeOutputPaths(testInfo, state.artifactSuffix).metadata;
           await mkdir(testInfo.outputDir, { recursive: true });
           await writeFile(path, `${JSON.stringify(metadata, null, 2)}\n`);
-          await testInfo.attach("video-mode", {
+          await testInfo.attach(`video-mode${state.artifactSuffix}`, {
             contentType: "application/json",
             path,
           });
         }
 
         state.startedAt = undefined;
-        console.log(`video-mode metadata written to ${videoModeOutputPaths(testInfo).metadata}`);
+        console.log(
+          `video-mode metadata written to ${videoModeOutputPaths(testInfo, state.artifactSuffix).metadata}`,
+        );
       });
 
       return () => {
+        activePage = undefined;
         stopObservingPlaywrightSteps();
         offBeforeTest();
         offAfterTestFinalize();
diff --git a/tasks/complete/2026-08-13-popup-plugins.md b/tasks/complete/2026-08-13-popup-plugins.md
new file mode 100644
index 0000000..f395856
--- /dev/null
+++ b/tasks/complete/2026-08-13-popup-plugins.md
@@ -0,0 +1,44 @@
+---
+status: done
+size: medium
+branch: popup-plugins
+pr: https://github.com/iterate/middlewright/pull/32
+---
+
+# Popup support (auth popout windows)
+
+**Status summary**: done. Middleware plugins supported popups all along via a second `addPlugins` call; video mode now supports them too — each `videoMode()` instance gets its own artifact namespace (auto `-2` suffix for the second instance in a test), and reusing one instance across pages throws a clear error. Specs cover metadata isolation, the guard, and real `video: "on"` recording. README has a Popups section.
+
+The pattern this supports:
+
+```ts
+const popupPromise = page.waitForEvent("popup");
+await page.getByRole("button", { name: "Sign in" }).click();
+await using popup = await addPlugins({
+  page: await popupPromise,
+  testInfo,
+  plugins: [spinnerWaiter(), videoMode()], // fresh instances for the popup
+});
+```
+
+## Findings: do we need a code change?
+
+- **Middleware plugins (spinnerWaiter, hydrationWaiter, uiErrorReporter, screenshot): no.** The `Locator.prototype` patch is global, but dispatch is per-page via `getPluginState(this.page())` (`src/plugin-system.ts`). An unwrapped popup falls through to original Playwright behavior; a second `addPlugins` call on the popup gives it its own plugin state. This is the designed seam.
+- **videoMode: yes.** Two hazards, one per way you might wire it:
+  1. **Reusing the same `videoMode()` instance** on page + popup was broken: the plugin holds one per-test `state` closure, and its `beforeTest` handler resets it — wrapping the popup mid-test wiped the main page's timeline. Now guarded: registering an active instance on a second page throws "create a fresh videoMode() instance for each page".
+  2. **A fresh `videoMode()` instance per popup** is the right model (Playwright screencasts each page separately; the instance's timebase is its creation time ≈ popup screencast start). Artifact filenames used to be fixed per `testInfo.outputDir` so the two instances clobbered each other; now each registration in a test gets a suffix (first instance unsuffixed for back-compat, then `-2`, `-3`, …) applied to metadata, raw/rendered video, player HTML, highlight/pan/fill images, dialog/final frames, `.ass` files, and attachment names.
+- A single combined video (main page + popup interleaved) would require compositing two screencasts and stays out of scope. Separate videos per page is the natural model.
+
+## Checklist
+
+- [x] spec: popup wrapped with `addPlugins` runs actions through its own plugins, timelines isolated in-memory during the test _(`spec/popup.spec.ts` — passed before the fix too; no code change needed for this half)_
+- [x] spec: after the test, each `videoMode` instance still owns its artifacts _(`spec/popup.spec.ts` — was red on the collision, green after namespacing)_
+- [x] decide artifact namespacing for multiple `videoMode` instances per test _(auto-index by registration order per `testInfo.outputDir` — no explicit name required; first instance keeps legacy unsuffixed names)_
+- [x] implement the namespacing _(`suffixArtifactFileName` + `videoModeRegistrationCounts` in `src/plugins/video-mode.ts`, threaded through `state.artifactSuffix`)_
+- [x] guard against registering an already-active `videoMode` instance on a second page _(throws from `pageExtension` before any state is touched; spec in `spec/popup.spec.ts`)_
+- [x] ffmpeg-level spec with `video: "on"`: popup gets its own raw/rendered webm alongside the main page's _(`spec/popup-video.spec.ts`)_
+- [x] README section on popups _(after Kitchen sink)_
+
+## Implementation log
+
+- 2026-08-13: investigated plugin-system + video-mode internals. Wrote `spec/popup.spec.ts` with an auth-popup demo app (`app.middlewright.test` opens `auth.middlewright.test`, Approve posts a message back to the opener; shared in `spec/auth-demo-app.ts`). Assumption: intended behavior is *separate* artifacts per instance, not a composited single video. Confirmed the collision (both report attachments shared one content hash), then implemented auto-index namespacing per user direction ("shouldn't require an explicit name"). Note: slugified `testInfo.name` wouldn't have helped — `outputDir` is already per-test; the collision was between two instances *within* one test, hence registration-order indexing. Full suite green (134 passed).