middlewright 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iterate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# middlewright
+
+A plugin/middleware system for Playwright locator actions — the one Playwright doesn't have.
+
+Wrap `click`, `fill`, `waitFor` and friends with composable middleware, so your tests can be smart about *why* an action is slow or failing, without sprinkling `waitForSomething()` helpers through every test.
+
+## Quick start
+
+Install with `pnpm add -D middlewright` then wire it once in a fixture:
+
+```ts
+// test-helpers.ts
+import { test as base } from "@playwright/test";
+import { addPlugins, spinnerWaiter } from "middlewright";
+
+export const test = base.extend({
+  page: async ({ page: basePage }, use, testInfo) => {
+    await using page = await addPlugins({
+      page: basePage,
+      testInfo,
+      plugins: [spinnerWaiter()],
+    });
+    await use(page);
+  },
+});
+```
+
+Then write completely ordinary tests — no special helpers, no wrapper calls:
+
+```ts
+import { test } from "./test-helpers";
+
+test("kick off a slow report", async ({ page }) => {
+  await page.goto("/reports");
+  await page.getByRole("button", { name: "Generate report" }).click();
+  // The report takes ~20s. The app shows "generating..." while it runs, so
+  // spinnerWaiter waits patiently here — but if there were NO spinner, this
+  // would fail after the normal 1s actionTimeout, with a hint suggesting
+  // the product add a loading state.
+  await page.getByText("Report ready").click();
+});
+```
+
+Pair it with an aggressive `actionTimeout` in `playwright.config.ts` (e.g. `1_000`) — the plugins are what make that viable.
+
+For a fixture with all five plugins wired together, see the [kitchen sink](#kitchen-sink) below.
+
+Ships with five plugins:
+
+| Plugin | What it does | |
+| --- | --- | --- |
+| [`spinnerWaiter`](#spinnerwaiter) | If the app is visibly loading, wait longer for elements. If it isn't, fail fast. | [source](./src/plugins/spinner-waiter.ts) |
+| [`hydrationWaiter`](#hydrationwaiter) | Don't interact with the app until it's hydrated. | [source](./src/plugins/hydration-waiter.ts) |
+| [`uiErrorReporter`](#uierrorreporter) | When an action fails, append any visible error toasts to the error message. | [source](./src/plugins/ui-error-reporter.ts) |
+| [`videoMode`](#videomode) | Highlight elements and pause before actions, so recorded videos are watchable. | [source](./src/plugins/video-mode.ts) |
+| [`llmRecover`](#llmrecover) | When an action fails, ask an LLM to write and run recovery code. Marks the test as soft-failed so nothing silently passes. | [source](./src/plugins/llm-recover.ts) |
+
+`spinnerWaiter` is the best one. It makes your test pass fast, fail fast, and it incentivises agents to *improve* the product when tests fail, instead of bumping timeouts which makes tests worse and lets your product get away with bad UX.
+
+## ⚠️ This is a hack
+
+You should know what you're buying:
+
+- **It patches `Locator.prototype` at runtime.** Once any page has plugins added, every locator in the process goes through the middleware dispatcher (pages without plugins fall through to the original behavior, but the patch itself is global).
+- **It reaches into Playwright internals.** Clean stack traces in reports depend on `setBoxedStackPrefixes`, which is undocumented and untyped — see [microsoft/playwright#38818](https://github.com/microsoft/playwright/issues/38818) asking for it to be made official. It has *already moved once* (playwright-core ≤ 1.59: `lib/utils`; 1.60+: `lib/coreBundle`). middlewright knows both locations and degrades gracefully (with a console warning, and plugin frames in your stack traces) if a future version moves it again. Set `PLAYWRIGHT_PLUGIN_DEBUG=1` to skip stack-boxing entirely.
+- **Pin your Playwright version** and treat Playwright upgrades as potentially breaking for this package. It's tested against the version in this repo's lockfile (currently 1.60.x); the declared `@playwright/test` peer range is >= 1.49.
+
+If Playwright ever ships official action middleware, use that instead and let this package die happy.
+
+## Why does this exist?
+
+It started with action timeouts. A good test suite fails *fast* — a 1-second `actionTimeout` catches real bugs immediately instead of burning 30 seconds per failed assertion. But real apps have operations that legitimately take 20 seconds, and the user-facing contract for those is "show a spinner". So the timeout you actually want is conditional: **1 second normally, 30 seconds while a spinner is visible**. That also creates a nice incentive loop: if a slow operation makes a test flaky, the fix is to add a loading state to the product — which is what your users wanted anyway.
+
+We [asked Playwright for this in 2022](https://github.com/microsoft/playwright/issues/16007). The maintainers' verdict:
+
+> This would be tricky since it might be that spinner shows up after the action has started. \[…\] I don't think it is technically feasible.
+
+Fair enough — *inside* Playwright's watchdog architecture it may not be. But in userland, wrapping the action with a retry-while-spinning loop is straightforward. Once you have one wrapper, you notice the pattern generalizes: waiting for hydration, surfacing error toasts, highlighting for videos, even LLM-assisted recovery are all "do something around a locator action". That's a middleware chain. This package is that middleware chain, extracted from the test infrastructure of a production app at [iterate](https://github.com/iterate).
+
+## Plugins
+
+### spinnerWaiter
+
+The flagship. Before each action, if the target element isn't visible but a spinner is, waits (up to `spinnerTimeout`) for the element — bailing out early if the spinner disappears without producing it. If there's no spinner and the action fails, the error message suggests adding one:
+
+```
+Timeout 1000ms exceeded.
+  If this is a slow operation, update the product code to add a spinner while it's running.
+  This will improve the user experience and buy you more time for this assertion.
+  To add a spinner, show any UI element matching this locator:
+    locator('[aria-label="Loading"],[data-spinner=\'true\'],...')
+```
+
+```ts
+spinnerWaiter({
+  spinnerSelectors: ['[data-spinner="true"]'], // default also matches aria-label="Loading" and trailing "...ing..." text
+  spinnerTimeout: 30_000,
+});
+```
+
+Runtime overrides go through `AsyncLocalStorage` — `enterWith` for the rest of the test, `run` for a single call:
+
+```ts
+test("a test where spinners are expected to hang", async ({ page }) => {
+  spinnerWaiter.settings.enterWith({ spinnerTimeout: 60_000 });
+  // ...
+
+  // or scope an override to one action:
+  await spinnerWaiter.settings.run({ disabled: true }, () =>
+    page.getByText("flash message").click(),
+  );
+});
+```
+
+### hydrationWaiter
+
+Before each action, waits for `[data-hydrated="false"]` to disappear. Your app cooperates by rendering that attribute server-side and flipping it once the framework hydrates. Stops the classic "test clicked a button before React attached the handler" flake at the source.
+
+```ts
+hydrationWaiter({ selector: '[data-hydrated="false"]', timeout: 10_000 });
+```
+
+### uiErrorReporter
+
+When an action fails, grabs the text of any visible error UI (default selector `[data-type="error"]`, which matches [sonner](https://sonner.emilkowal.ski/) error toasts) and appends it to the error message in red. Turns "Timeout 1000ms exceeded" into "Timeout 1000ms exceeded — Error UI visible: 'Could not save: quota exceeded'".
+
+```ts
+uiErrorReporter({ selector: '[data-type="error"]' });
+```
+
+### videoMode
+
+For producing demo/debugging videos people can actually follow: outlines the element in gold, pauses before each action, and pauses after the test so the video doesn't cut off abruptly. Enable it conditionally (e.g. `!!process.env.VIDEO_MODE && videoMode()`) together with Playwright's `video: "on"` and a generous `actionTimeout`.
+
+```ts
+videoMode({
+  pauseBefore: 1000,
+  pauseAfterTest: 3000,
+  highlightStyle: "3px solid gold",
+  skipMethods: ["waitFor"],
+  skipStackFrames: ["test-helpers.ts"], // don't slow down internal login/setup helpers
+});
+```
+
+### llmRecover
+
+The most fun one, and the most dangerous one. When an action fails, it captures a screenshot, the accessibility snapshot, the page HTML and the error, asks Claude to respond with a JavaScript recovery function, and `eval`s it with `{ page, locator, error }` in scope. Up to `maxAttempts` tries, with attempt history fed back to the model.
+
+Two design decisions worth knowing about:
+
+- **Recovered tests still fail.** On successful recovery it records a *soft* assertion failure, so the test keeps running (surfacing any further failures) but the run is marked failed, with the recovery code in the report. The point is to tell you *what the fix probably is* — e.g. "the button copy changed" — not to let the suite go green on vibes.
+- **The LLM can decline.** If it deems the failure unrecoverable (real bug, not a locator/timing issue), the original error is rethrown with the model's explanation attached.
+
+```ts
+// gate it behind an env var — this runs LLM-generated code via eval, in
+// your test process. Only enable it deliberately.
+!!process.env.LLM_RECOVER && llmRecover({
+  model: "claude-opus-4-8",   // default
+  maxAttempts: 3,             // default
+  apiKey: "...",              // default: process.env.ANTHROPIC_API_KEY
+});
+```
+
+For testing (or to swap in your own agent/provider), inject `requestRecoveryCode` — see [spec/llm-recover.spec.ts](spec/llm-recover.spec.ts).
+
+Artifacts (every attempt, code, errors, timings) are written to `<test-output-dir>/llm-recover/*.json`.
+
+### Kitchen sink
+
+All five plugins wired into one fixture — this mirrors how they ran in the app they were extracted from:
+
+```ts
+// test-helpers.ts
+import { test as base } from "@playwright/test";
+import {
+  addPlugins,
+  hydrationWaiter,
+  llmRecover,
+  spinnerWaiter,
+  uiErrorReporter,
+  videoMode,
+} from "middlewright";
+
+export const test = base.extend({
+  page: async ({ page: basePage }, use, testInfo) => {
+    await using page = await addPlugins({
+      page: basePage,
+      testInfo,
+      plugins: [
+        // order matters: the first plugin is outermost. llmRecover goes first
+        // so it sees errors after the other plugins have enriched them.
+        !!process.env.LLM_RECOVER && llmRecover(),
+        hydrationWaiter({ timeout: 60_000 }),
+        uiErrorReporter(),
+        spinnerWaiter(),
+        // opt-in: slows everything down to make recordings watchable
+        !!process.env.VIDEO_MODE && videoMode({ skipStackFrames: ["test-helpers.ts"] }),
+      ],
+      // also hide this helper file from stack traces in reports
+      boxedStackPrefixes: (defaults) => [...defaults, import.meta.filename],
+    });
+    await use(page);
+  },
+});
+```
+
+```ts
+// playwright.config.ts (the relevant bits)
+export default defineConfig({
+  use: {
+    actionTimeout: process.env.VIDEO_MODE ? 10_000 : 1_000, // fail fast; spinnerWaiter buys time when deserved
+    video: { mode: process.env.VIDEO_MODE ? "on" : "retain-on-failure" },
+  },
+});
+```
+
+## 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) (page mutation around actions + 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`.
+
+A plugin is a name plus optional `middleware` and `testLifecycle` hooks:
+
+```ts
+import type { Plugin } from "middlewright";
+import { adjustError } from "middlewright";
+
+export const slowActionLogger = (thresholdMs = 2000): Plugin => ({
+  name: "slow-action-logger",
+
+  // Wraps every locator action. ctx has { locator, method, args, page, testInfo }.
+  middleware: async (ctx, next) => {
+    const start = Date.now();
+    try {
+      return await next(); // call the next middleware, or the real action
+    } catch (error) {
+      adjustError(error as Error, [`action took ${Date.now() - start}ms before failing`]);
+      throw error;
+    } finally {
+      if (Date.now() - start > thresholdMs) {
+        console.warn(`${ctx.locator}.${ctx.method}() took ${Date.now() - start}ms`);
+      }
+    }
+  },
+
+  // Subscribe to beforeTest/afterTest events. Return a cleanup function if needed.
+  testLifecycle: (emitter) => {
+    emitter.on("afterTest", ({ testInfo }) => console.log(`finished: ${testInfo.title}`));
+  },
+});
+```
+
+Notes for plugin authors:
+
+- Middleware runs in registration order; the first plugin in the array is outermost. Error-enriching plugins (like `uiErrorReporter`) should generally be registered *before* the plugins whose errors they enrich, and recovery plugins (like `llmRecover`) first of all, so they see fully-enriched errors.
+- Inside middleware, use the `_original` methods (`locator.waitFor_original(...)` etc. — see the `LocatorWithOriginal` type) when you need to perform locator actions *without* re-entering the middleware chain.
+- `adjustError(error, infoLines, filterFile?)` appends colored info lines to an error message and optionally scrubs your plugin's frames from the stack trace.
+
+## How it works
+
+`addPlugins` patches `Locator.prototype` (once per process), replacing `click`, `dblclick`, `fill`, `type`, `press`, `clear`, `blur`, `focus`, `hover` and `waitFor` with a dispatcher. The dispatcher looks up the plugin state stored on the action's page; if the page has plugins, it runs the middleware chain (each middleware calling `next()` until the original method runs); if not, it calls the original method directly.
+
+To keep Playwright's HTML report pointing at *your test code* rather than plugin internals, it registers the plugin files with playwright-core's internal `setBoxedStackPrefixes` — the same mechanism Playwright uses to hide its own frames. This is the unofficial-API part of the hack; set `PLAYWRIGHT_PLUGIN_DEBUG=1` to disable it when debugging the plugins themselves.
+
+## Development
+
+```bash
+pnpm install
+pnpm exec playwright install chromium
+pnpm test         # playwright tests (no app needed — pages are built with setContent)
+pnpm typecheck
+pnpm build
+```
+
+The llm-recover live-API tests are skipped unless you set `LLM_RECOVER=1` (and `ANTHROPIC_API_KEY`); provider-injected tests for the same plugin always run.
+
+## Credits
+
+Extracted from the internal test infrastructure of the [iterate](https://github.com/iterate) monorepo, where these plugins ran against a production app. Prior art / motivation: [microsoft/playwright#16007](https://github.com/microsoft/playwright/issues/16007), [microsoft/playwright#38818](https://github.com/microsoft/playwright/issues/38818).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { addPlugins, adjustError, oneArgMethods, overrideableMethods, type Plugin, type ActionContext, type ActionMiddleware, type NextFn, type TestLifecycleEvents, type LocatorWithOriginal, type OverrideableMethod, type OneArgMethod, } from "./plugin-system.ts";
+export * from "./plugins/index.ts";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { addPlugins, adjustError, oneArgMethods, overrideableMethods, } from "./plugin-system.js";
+export * from "./plugins/index.js";

package/dist/plugin-system.d.ts

@@ -0,0 +1,82 @@
+import Emittery from "emittery";
+import type { Locator, Page, TestInfo } from "@playwright/test";
+declare const oneArgMethods: readonly ["fill", "type", "press"];
+type OneArgMethod = (typeof oneArgMethods)[number];
+declare const overrideableMethods: ("fill" | "type" | "press" | "blur" | "clear" | "click" | "dblclick" | "focus" | "hover" | "waitFor")[];
+type OverrideableMethod = (typeof overrideableMethods)[number];
+export type LocatorWithOriginal = Locator & {
+    [K in OverrideableMethod as `${K}_original`]: Locator[K];
+};
+/**
+ * Append info to an error message and clean up stack trace.
+ * @param error - The error to modify
+ * @param info - Lines to append to the error message
+ * @param filterFile - Filename to remove from stack trace (e.g., "my-plugin.ts")
+ * @param color - ANSI color code (default: 33 = yellow). Use 31 for red.
+ */
+export declare const adjustError: (error: Error, info: string[], filterFile?: string, { color }?: {
+    color?: number | undefined;
+}) => void;
+export type ActionContext = {
+    locator: LocatorWithOriginal;
+    method: OverrideableMethod;
+    args: unknown[];
+    page: Page;
+    testInfo: TestInfo;
+};
+/** Function that calls the next middleware or the original action */
+export type NextFn = () => Promise<unknown>;
+/** Middleware function - wraps an action, must call next() */
+export type ActionMiddleware = (ctx: ActionContext, next: NextFn) => Promise<unknown>;
+export type TestLifecycleEvents = {
+    beforeTest: {
+        page: Page;
+        testInfo: TestInfo;
+    };
+    afterTest: {
+        page: Page;
+        testInfo: TestInfo;
+    };
+};
+export type Plugin = {
+    name: string;
+    /** Middleware to wrap locator actions. Called in registration order. */
+    middleware?: ActionMiddleware;
+    /** Subscribe to test lifecycle events */
+    testLifecycle?: (emitter: Emittery<TestLifecycleEvents>) => void | (() => void);
+};
+declare const PLUGIN_STATE: unique symbol;
+type PluginState = {
+    actionMiddlewares: ActionMiddleware[];
+    lifecycleEmitter: Emittery<TestLifecycleEvents>;
+    lifecycleCleanups: (() => void)[];
+    testInfo: TestInfo;
+};
+type PageWithPlugins = Page & {
+    [PLUGIN_STATE]: PluginState;
+    [Symbol.asyncDispose]: () => Promise<void>;
+};
+/**
+ * Add plugins to a page. Returns a disposable page that cleans up on dispose.
+ *
+ * @example
+ * ```ts
+ * await using page = await addPlugins({
+ *   page: basePage,
+ *   testInfo,
+ *   plugins: [
+ *     hydrationWaiter(),
+ *     spinnerWaiter(),
+ *     videoMode(),
+ *   ]
+ * });
+ * ```
+ */
+export declare const addPlugins: (params: {
+    page: Page;
+    testInfo: TestInfo;
+    plugins: (Plugin | false | null | undefined)[];
+    boxedStackPrefixes?: (defaults: string[]) => string[];
+}) => Promise<PageWithPlugins>;
+export type { OverrideableMethod, OneArgMethod };
+export { oneArgMethods, overrideableMethods };

package/dist/plugin-system.js

@@ -0,0 +1,201 @@
+/**
+ * middlewright plugin system.
+ *
+ * Extracted from the iterate monorepo's internal Playwright test
+ * infrastructure (github.com/iterate/iterate, private). Modifications from the
+ * original: playwright-core internals are resolved relative to
+ * `@playwright/test` so this works under pnpm's strict node_modules layout,
+ * and locator actions on pages that never had plugins added fall through to
+ * the original implementation instead of throwing.
+ */
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import Emittery from "emittery";
+const require = createRequire(import.meta.url);
+// Methods that take an extra argument before options (e.g., fill(value, options))
+const oneArgMethods = ["fill", "type", "press"];
+const overrideableMethods = [
+    "click",
+    "waitFor",
+    "clear",
+    "dblclick",
+    "blur",
+    "focus",
+    "hover",
+    ...oneArgMethods,
+];
+/**
+ * Append info to an error message and clean up stack trace.
+ * @param error - The error to modify
+ * @param info - Lines to append to the error message
+ * @param filterFile - Filename to remove from stack trace (e.g., "my-plugin.ts")
+ * @param color - ANSI color code (default: 33 = yellow). Use 31 for red.
+ */
+export const adjustError = (error, info, filterFile, { color = 33 } = {}) => {
+    if (!error?.message)
+        return;
+    Object.assign(error, { originalMessage: error.message, originalStack: error.stack });
+    if (info.length > 0) {
+        const infoBlock = info.map((line) => `  ${line}`).join("\n");
+        error.message = `${error.message}\n\x1b[${color}m${infoBlock}\x1b[0m\n`;
+    }
+    if (filterFile && error.stack) {
+        error.stack = error.stack
+            .split("\n")
+            .filter((line) => !line.includes(filterFile))
+            .join("\n");
+    }
+};
+const PLUGIN_STATE = Symbol("playwrightPluginState");
+// Track if Locator prototype has been patched
+let prototypePatched = false;
+/** Get plugin state from a page */
+const getPluginState = (page) => {
+    return page[PLUGIN_STATE];
+};
+/**
+ * Add plugins to a page. Returns a disposable page that cleans up on dispose.
+ *
+ * @example
+ * ```ts
+ * await using page = await addPlugins({
+ *   page: basePage,
+ *   testInfo,
+ *   plugins: [
+ *     hydrationWaiter(),
+ *     spinnerWaiter(),
+ *     videoMode(),
+ *   ]
+ * });
+ * ```
+ */
+export const addPlugins = async (params) => {
+    const { page, testInfo, plugins, boxedStackPrefixes } = params;
+    // Patch Locator prototype once globally
+    patchLocatorPrototype(page, boxedStackPrefixes);
+    // Initialize state on page
+    const state = {
+        actionMiddlewares: [],
+        lifecycleEmitter: new Emittery(),
+        lifecycleCleanups: [],
+        testInfo,
+    };
+    // Register plugins
+    for (const plugin of plugins) {
+        if (!plugin)
+            continue;
+        if (plugin.middleware) {
+            state.actionMiddlewares.push(plugin.middleware);
+        }
+        if (plugin.testLifecycle) {
+            const cleanup = plugin.testLifecycle(state.lifecycleEmitter);
+            if (cleanup)
+                state.lifecycleCleanups.push(cleanup);
+        }
+    }
+    const pageWithPlugins = page;
+    pageWithPlugins[PLUGIN_STATE] = state;
+    // Emit beforeTest
+    await state.lifecycleEmitter.emitSerial("beforeTest", { page, testInfo });
+    // Add async dispose
+    pageWithPlugins[Symbol.asyncDispose] = async () => {
+        await state.lifecycleEmitter.emitSerial("afterTest", { page, testInfo });
+        state.lifecycleCleanups.forEach((cleanup) => cleanup());
+    };
+    return pageWithPlugins;
+};
+/**
+ * Resolve playwright-core starting from @playwright/test. Under pnpm's strict
+ * layout, playwright-core isn't reachable from this package - only via the
+ * host project's @playwright/test.
+ */
+const resolvePlaywrightInternals = () => {
+    const testPkg = require.resolve("@playwright/test/package.json");
+    const requireFromTest = createRequire(testPkg);
+    const playwrightPkg = requireFromTest.resolve("playwright/package.json");
+    const corePkg = createRequire(playwrightPkg).resolve("playwright-core/package.json");
+    return { testPkg, playwrightPkg, corePkg };
+};
+/**
+ * setBoxedStackPrefixes is an internal playwright-core API
+ * (https://github.com/microsoft/playwright/issues/38818 asks for it to be made
+ * official) and has already moved once: playwright-core <= 1.59 exposed it
+ * from lib/utils, 1.60+ from the utils namespace of lib/coreBundle. Returns
+ * null when it can't be found - everything works without it, you just see
+ * plugin frames in stack traces.
+ */
+const loadSetBoxedStackPrefixes = (corePkg) => {
+    const coreRequire = createRequire(corePkg);
+    for (const load of [
+        () => coreRequire("./lib/utils").setBoxedStackPrefixes,
+        () => coreRequire("./lib/coreBundle").utils.setBoxedStackPrefixes,
+    ]) {
+        try {
+            const fn = load();
+            if (typeof fn === "function")
+                return fn;
+        }
+        catch {
+            // try the next layout
+        }
+    }
+    return null;
+};
+/** Patch Locator prototype to run middleware. Safe to call multiple times. */
+const patchLocatorPrototype = (page, boxedStackPrefixes) => {
+    if (prototypePatched)
+        return;
+    prototypePatched = true;
+    const internals = resolvePlaywrightInternals();
+    // Exclude this file from stack traces in Playwright reports
+    if (!process.env.PLAYWRIGHT_PLUGIN_DEBUG) {
+        const setBoxedStackPrefixes = loadSetBoxedStackPrefixes(internals.corePkg);
+        if (setBoxedStackPrefixes) {
+            const getPrefixes = boxedStackPrefixes || ((defaults) => defaults);
+            const prefixes = getPrefixes([
+                path.dirname(internals.testPkg),
+                path.dirname(internals.playwrightPkg),
+                path.dirname(internals.corePkg),
+                import.meta.filename,
+            ]);
+            setBoxedStackPrefixes(prefixes);
+        }
+        else {
+            console.warn("[middlewright] could not find setBoxedStackPrefixes in this playwright-core version - " +
+                "stack traces in reports will include plugin frames");
+        }
+    }
+    const dummyLocator = page.locator("body");
+    const locatorPrototype = dummyLocator.constructor.prototype;
+    for (const method of overrideableMethods) {
+        locatorPrototype[`${method}_original`] = locatorPrototype[method];
+        const value = async function patchedMethod(...args) {
+            const callOriginal = () => this[`${method}_original`](...args);
+            // Pages that never had plugins added (e.g. a second page in the same
+            // worker) fall through to the original implementation.
+            const state = getPluginState(this.page());
+            if (!state)
+                return callOriginal();
+            const actionMiddlewares = state.actionMiddlewares;
+            const ctx = {
+                locator: this,
+                method,
+                args,
+                page: this.page(),
+                testInfo: state.testInfo,
+            };
+            // Build middleware chain - each middleware calls next() to continue
+            let index = 0;
+            const next = async () => {
+                if (index < actionMiddlewares.length) {
+                    const middleware = actionMiddlewares[index++];
+                    return middleware(ctx, next);
+                }
+                return callOriginal();
+            };
+            return next();
+        };
+        Object.defineProperty(locatorPrototype, method, { value });
+    }
+};
+export { oneArgMethods, overrideableMethods };

package/dist/plugins/hydration-waiter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * hydration-waiter: don't interact with the app before it's interactive.
+ *
+ * Extracted from the iterate monorepo's internal Playwright test
+ * infrastructure (github.com/iterate/iterate, private).
+ */
+import type { Plugin } from "../plugin-system.ts";
+export type HydrationWaiterOptions = {
+    /** Selector for unhydrated state. Default: '[data-hydrated="false"]' */
+    selector?: string;
+    /** Timeout for hydration. Default: 10_000 */
+    timeout?: number;
+    /** Whether to skip this plugin. Default: false */
+    disabled?: boolean;
+};
+/**
+ * Waits for the app to be hydrated before any locator action.
+ * Looks for `[data-hydrated="false"]` and waits for it to disappear.
+ *
+ * Your app needs to cooperate: render `data-hydrated="false"` on some element
+ * server-side and flip it to "true" (or remove it) once the framework has
+ * hydrated. With React, for example, flip it in a top-level component that
+ * only runs client-side.
+ */
+export declare const hydrationWaiter: (options?: HydrationWaiterOptions) => Plugin;

package/dist/plugins/hydration-waiter.js

@@ -0,0 +1,26 @@
+/**
+ * Waits for the app to be hydrated before any locator action.
+ * Looks for `[data-hydrated="false"]` and waits for it to disappear.
+ *
+ * Your app needs to cooperate: render `data-hydrated="false"` on some element
+ * server-side and flip it to "true" (or remove it) once the framework has
+ * hydrated. With React, for example, flip it in a top-level component that
+ * only runs client-side.
+ */
+export const hydrationWaiter = (options = {}) => {
+    const selector = options.selector || '[data-hydrated="false"]';
+    const timeout = options.timeout || 10_000;
+    return {
+        name: "hydration-waiter",
+        middleware: async ({ page }, next) => {
+            if (options.disabled)
+                return next();
+            const unhydratedLocator = page.locator(selector);
+            const isUnhydrated = await unhydratedLocator.isVisible();
+            if (isUnhydrated) {
+                await unhydratedLocator.waitFor_original({ state: "hidden", timeout });
+            }
+            return next();
+        },
+    };
+};

package/dist/plugins/index.d.ts

@@ -0,0 +1,5 @@
+export { hydrationWaiter, type HydrationWaiterOptions } from "./hydration-waiter.ts";
+export { videoMode, type VideoModeOptions } from "./video-mode.ts";
+export { spinnerWaiter, type SpinnerWaiterOptions, defaultSelectors } from "./spinner-waiter.ts";
+export { uiErrorReporter, type UIErrorReporterOptions } from "./ui-error-reporter.ts";
+export { llmRecover, type LlmRecoverOptions, type AttemptRecord, type RecoveryContext, type RequestRecoveryCodeFn, } from "./llm-recover.ts";

package/dist/plugins/index.js

@@ -0,0 +1,5 @@
+export { hydrationWaiter } from "./hydration-waiter.js";
+export { videoMode } from "./video-mode.js";
+export { spinnerWaiter, defaultSelectors } from "./spinner-waiter.js";
+export { uiErrorReporter } from "./ui-error-reporter.js";
+export { llmRecover, } from "./llm-recover.js";