middlewright 0.1.0 → 0.1.2

package/README.md

@@ -52,9 +52,11 @@ Ships with five plugins:
 | [`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) |
+| [`videoMode`](#videomode) | Record action/dead-air facts and render watchable annotated videos after the run. | [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) |
 
+When Playwright is launched with `--debug`, it sets `PWDEBUG=1`; the bundled plugins treat that as a hard debug-mode no-op. They still return plugin objects so your fixture can stay unchanged, but they do not wrap locator actions, wait for app state, recover failures, or write video artifacts.
+
 `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
@@ -130,18 +132,76 @@ 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`.
+For producing demo/debugging videos people can actually follow: marks pre-action waiting as dead air, records action bounding boxes, and renders highlights/final holds into the video after the test run. Enable it conditionally (e.g. `!!process.env.VIDEO_MODE && videoMode()`) together with Playwright's `video: "on"` and a generous `actionTimeout`.
+
+```ts
+await using page = await addPlugins({
+  page: basePage,
+  testInfo,
+  plugins: [
+    videoMode({
+      highlight: { mode: "pointer", duration: 1000 },
+      finalHold: 3000,
+      deadAirThreshold: 300,
+      skipMethods: ["waitFor"],
+      skipStackFrames: ["test-helpers.ts"], // don't annotate internal login/setup helpers
+    }),
+  ],
+});
+
+// Use page.videoMode for invisible setup/bookkeeping that should be marked as
+// dead air instead of highlighted in video mode.
+await page.videoMode.deadAir(async () => {
+  await page.goto("/login");
+  await page.locator("#email").fill("demo@example.com");
+});
+
+const videoPaths = page.videoMode.outputPaths();
+const videoMetadata = await page.videoMode.metadata();
+console.log(videoPaths.rendered);
+console.log(videoMetadata.highlights.length);
+
+page.videoMode.setStartTime();
+await page.locator("#important-flow").click();
+page.videoMode.setEndTime();
+```
+
+When Playwright video recording is enabled, `videoMode` saves `video-raw.webm`, uses `ffmpeg` to write `video-rendered.webm`, writes a sibling `video-mode.html` frame-stepper for inspecting both videos, and attaches all of them with `video-mode.json` to the test report. The frame-stepper stores its active video and frame in the URL, so links like `video-mode.html?active=rendered&frame=28` reopen the same frame. If `ffmpeg` or `ffprobe` is missing, the render step fails plainly so you know to install ffmpeg.
+
+#### Trimming the blank startup lead-in (`trimStart`)
+
+Recording begins at browser-context creation, so a video usually opens with a few seconds of `about:blank` + loading shell before the app paints. `trimStart` finds where that lead-in ends and starts the video on real content — instead of calling `setStartTime()` by hand in every test.
+
+```ts
+videoMode({ /* trimStart: "auto" is the default */ });
+
+// start when a known "ready" element first becomes visible (falls back to
+// blank detection if it never appears):
+videoMode({ trimStart: ["selector", "[data-app-ready]"] });
+
+// pin the start for a video whose exact frames you assert on:
+videoMode({ trimStart: "never" });
+```
+
+`trimStart` is one of:
+
+- **`"auto"`** (default) — pick a sensible strategy; currently the blank detector. Chosen so consumers get lead-in trimming just by upgrading.
+- **`"detect-blank"`** — decode a coarse strip of the opening seconds and find the first frame that *differs* from the opening frame (the moment the static blank lead-in ends), starting there only when the lead-in is long enough to be worth trimming. Keys on change-from-the-opening-frame, not how "busy" a frame is, so it's robust to letterbox bars and dark loading shells.
+- **`["selector", css]`** — start the moment `css` first becomes visible (waited for once, live); falls back to blank detection if it never appears.
+- **`"never"`** — don't trim.
+
+An explicit `setStartTime()` always wins over `trimStart`.
+
+`video-mode.json` records raw dead-air spans and highlight rectangles. `deadAirThreshold` is applied only when writing the rendered video: dead-air spans longer than the threshold are sped up so they render within that duration. Spans at or below the threshold are left at normal speed. `highlight` duration and `finalHold` are also applied at render time, so they do not slow down the browser test. `highlight: true` is equivalent to the default pointer mode, `{ mode: "pointer", duration: 1000 }`. For outline boxes, use a simple solid CSS-style string:
 
 ```ts
 videoMode({
-  pauseBefore: 1000,
-  pauseAfterTest: 3000,
-  highlightStyle: "3px solid gold",
-  skipMethods: ["waitFor"],
-  skipStackFrames: ["test-helpers.ts"], // don't slow down internal login/setup helpers
+  highlight: { mode: "outline", style: "1px solid yellow" },
 });
 ```
 
+Put `spinnerWaiter` before `videoMode` when you use both. Spinner-waiter still owns spinner-specific waiting and errors, while video-mode records the preceding middleware wait as dead air and records the action target immediately before the action.
+
 ### 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.
@@ -216,9 +276,9 @@ export default defineConfig({
 
 ## 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`.
+**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`.
 
-A plugin is a name plus optional `middleware` and `testLifecycle` hooks:
+A plugin is a name plus optional `middleware`, `testLifecycle`, and `pageExtension` hooks:
 
 ```ts
 import type { Plugin } from "middlewright";
@@ -249,9 +309,35 @@ export const slowActionLogger = (thresholdMs = 2000): Plugin => ({
 });
 ```
 
+Use `pageExtension` for explicit controls tests can call through the page returned from `addPlugins`:
+
+```ts
+export const debugTools = (): Plugin<{
+  debugTools: {
+    title(): string;
+  };
+}> => ({
+  name: "debug-tools",
+  pageExtension: ({ testInfo }) => ({
+    debugTools: {
+      title: () => testInfo.title,
+    },
+  }),
+});
+
+await using page = await addPlugins({
+  page: basePage,
+  testInfo,
+  plugins: [debugTools()],
+});
+
+expect(page.debugTools.title()).toBe(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.
+- Keep page extensions namespaced (`page.videoMode`, `page.debugTools`) so plugin controls do not collide with Playwright's own `Page` methods or other plugins.
 - 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.
 

package/dist/index.d.ts

@@ -1,2 +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 { addPlugins, adjustError, oneArgMethods, overrideableMethods, type Plugin, type PageExtensionContext, type ActionContext, type ActionMiddleware, type ActionMiddlewareTiming, type ActionTiming, type NextFn, type TestLifecycleEvents, type LocatorWithOriginal, type OverrideableMethod, type OneArgMethod, } from "./plugin-system.ts";
 export * from "./plugins/index.ts";

package/dist/plugin-system.d.ts

@@ -23,9 +23,21 @@ export type ActionContext = {
     args: unknown[];
     page: Page;
     testInfo: TestInfo;
+    timing: ActionTiming;
+};
+export type ActionMiddlewareTiming = {
+    name: string;
+    startedAt: number;
+    endedAt?: number;
+};
+export type ActionTiming = {
+    actionStartedAt: number;
+    attachedAt?: number;
+    attachedAtStart: boolean;
+    middlewares: ActionMiddlewareTiming[];
 };
 /** Function that calls the next middleware or the original action */
-export type NextFn = () => Promise<unknown>;
+export type NextFn = (args?: unknown[]) => Promise<unknown>;
 /** Middleware function - wraps an action, must call next() */
 export type ActionMiddleware = (ctx: ActionContext, next: NextFn) => Promise<unknown>;
 export type TestLifecycleEvents = {
@@ -37,22 +49,43 @@ export type TestLifecycleEvents = {
         page: Page;
         testInfo: TestInfo;
     };
+    afterTestFinalize: {
+        page: Page;
+        testInfo: TestInfo;
+    };
 };
-export type Plugin = {
+export type PageExtensionContext = {
+    page: Page;
+    testInfo: TestInfo;
+};
+export type Plugin<PageExtension extends object = {}> = {
     name: string;
     /** Middleware to wrap locator actions. Called in registration order. */
     middleware?: ActionMiddleware;
     /** Subscribe to test lifecycle events */
     testLifecycle?: (emitter: Emittery<TestLifecycleEvents>) => void | (() => void);
+    /** Add explicit test controls to the page returned from addPlugins. */
+    pageExtension?: (ctx: PageExtensionContext) => PageExtension;
 };
 declare const PLUGIN_STATE: unique symbol;
 type PluginState = {
-    actionMiddlewares: ActionMiddleware[];
+    actionMiddlewares: RegisteredActionMiddleware[];
     lifecycleEmitter: Emittery<TestLifecycleEvents>;
     lifecycleCleanups: (() => void)[];
     testInfo: TestInfo;
 };
-type PageWithPlugins = Page & {
+type RegisteredActionMiddleware = {
+    name: string;
+    middleware: ActionMiddleware;
+};
+type MaybePlugin = Plugin<object> | false | null | undefined;
+type PluginPageExtension<T> = T extends Plugin<infer PageExtension> ? PageExtension : {};
+type PluginPageExtensionForEntry<T> = [Extract<T, Plugin<object>>] extends [never] ? {} : [Exclude<T, Plugin<object>>] extends [never] ? PluginPageExtension<T> : Partial<PluginPageExtension<T>>;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
+type PageExtensions<T extends readonly MaybePlugin[]> = UnionToIntersection<{
+    [Index in keyof T]: PluginPageExtensionForEntry<T[Index]>;
+}[number]> & object;
+type PageWithPlugins<PageExtension extends object = {}> = Page & PageExtension & {
     [PLUGIN_STATE]: PluginState;
     [Symbol.asyncDispose]: () => Promise<void>;
 };
@@ -72,11 +105,11 @@ type PageWithPlugins = Page & {
  * });
  * ```
  */
-export declare const addPlugins: (params: {
+export declare const addPlugins: <const Plugins extends readonly MaybePlugin[]>(params: {
     page: Page;
     testInfo: TestInfo;
-    plugins: (Plugin | false | null | undefined)[];
+    plugins: Plugins;
     boxedStackPrefixes?: (defaults: string[]) => string[];
-}) => Promise<PageWithPlugins>;
+}) => Promise<PageWithPlugins<PageExtensions<Plugins>>>;
 export type { OverrideableMethod, OneArgMethod };
 export { oneArgMethods, overrideableMethods };

package/dist/plugin-system.js

@@ -85,7 +85,10 @@ export const addPlugins = async (params) => {
         if (!plugin)
             continue;
         if (plugin.middleware) {
-            state.actionMiddlewares.push(plugin.middleware);
+            state.actionMiddlewares.push({
+                middleware: plugin.middleware,
+                name: plugin.name,
+            });
         }
         if (plugin.testLifecycle) {
             const cleanup = plugin.testLifecycle(state.lifecycleEmitter);
@@ -95,11 +98,19 @@ export const addPlugins = async (params) => {
     }
     const pageWithPlugins = page;
     pageWithPlugins[PLUGIN_STATE] = state;
+    for (const plugin of plugins) {
+        if (!plugin)
+            continue;
+        if (!plugin.pageExtension)
+            continue;
+        Object.assign(pageWithPlugins, plugin.pageExtension({ page, testInfo }));
+    }
     // Emit beforeTest
     await state.lifecycleEmitter.emitSerial("beforeTest", { page, testInfo });
     // Add async dispose
     pageWithPlugins[Symbol.asyncDispose] = async () => {
         await state.lifecycleEmitter.emitSerial("afterTest", { page, testInfo });
+        await state.lifecycleEmitter.emitSerial("afterTestFinalize", { page, testInfo });
         state.lifecycleCleanups.forEach((cleanup) => cleanup());
     };
     return pageWithPlugins;
@@ -141,6 +152,41 @@ const loadSetBoxedStackPrefixes = (corePkg) => {
     }
     return null;
 };
+const locatorIsAttached = async (locator) => {
+    try {
+        return (await locator.count()) > 0;
+    }
+    catch {
+        return false;
+    }
+};
+const observeAttachedAt = (locator, timing, pollIntervalMs = 50) => {
+    let stopped = false;
+    let timeout;
+    const poll = async () => {
+        if (stopped || timing.attachedAt !== undefined) {
+            return;
+        }
+        const attached = await locatorIsAttached(locator);
+        if (stopped || timing.attachedAt !== undefined) {
+            return;
+        }
+        if (attached) {
+            timing.attachedAt = performance.now();
+            return;
+        }
+        timeout = setTimeout(() => {
+            void poll();
+        }, pollIntervalMs);
+    };
+    void poll();
+    return () => {
+        stopped = true;
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    };
+};
 /** Patch Locator prototype to run middleware. Safe to call multiple times. */
 const patchLocatorPrototype = (page, boxedStackPrefixes) => {
     if (prototypePatched)
@@ -170,30 +216,62 @@ const patchLocatorPrototype = (page, boxedStackPrefixes) => {
     for (const method of overrideableMethods) {
         locatorPrototype[`${method}_original`] = locatorPrototype[method];
         const value = async function patchedMethod(...args) {
-            const callOriginal = () => this[`${method}_original`](...args);
+            let currentArgs = args;
+            const callOriginal = () => this[`${method}_original`](...currentArgs);
             // 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 actionStartedAt = performance.now();
+            const attachedAtStart = await locatorIsAttached(this);
+            const timing = {
+                actionStartedAt,
+                attachedAt: attachedAtStart ? actionStartedAt : undefined,
+                attachedAtStart,
+                middlewares: [],
+            };
+            const stopObservingAttached = attachedAtStart
+                ? () => { }
+                : observeAttachedAt(this, timing);
             const ctx = {
                 locator: this,
                 method,
                 args,
                 page: this.page(),
                 testInfo: state.testInfo,
+                timing,
             };
             // Build middleware chain - each middleware calls next() to continue
             let index = 0;
-            const next = async () => {
+            const next = async (nextArgs) => {
+                if (nextArgs) {
+                    currentArgs = nextArgs;
+                    ctx.args = nextArgs;
+                }
                 if (index < actionMiddlewares.length) {
-                    const middleware = actionMiddlewares[index++];
-                    return middleware(ctx, next);
+                    const { middleware, name } = actionMiddlewares[index++];
+                    const middlewareTiming = {
+                        name,
+                        startedAt: performance.now(),
+                    };
+                    timing.middlewares.push(middlewareTiming);
+                    try {
+                        return await middleware(ctx, next);
+                    }
+                    finally {
+                        middlewareTiming.endedAt = performance.now();
+                    }
                 }
                 return callOriginal();
             };
-            return next();
+            try {
+                return await next();
+            }
+            finally {
+                stopObservingAttached();
+            }
         };
         Object.defineProperty(locatorPrototype, method, { value });
     }

package/dist/plugins/hydration-waiter.js

@@ -8,6 +8,9 @@
  * only runs client-side.
  */
 export const hydrationWaiter = (options = {}) => {
+    if (process.env.PWDEBUG) {
+        return { name: "hydration-waiter" };
+    }
     const selector = options.selector || '[data-hydrated="false"]';
     const timeout = options.timeout || 10_000;
     return {

package/dist/plugins/index.d.ts

@@ -1,5 +1,5 @@
 export { hydrationWaiter, type HydrationWaiterOptions } from "./hydration-waiter.ts";
-export { videoMode, type VideoModeOptions } from "./video-mode.ts";
+export { videoMode, type VideoModeControls, type VideoModeHighlight, type VideoModeMetadata, type VideoModeOptions, type VideoModeOutputPaths, type VideoModeOutputs, type VideoModePageExtension, type VideoModeRect, type VideoModePlugin, type VideoModeSourceRange, type VideoModeSpan, type VideoModeViewport, } 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

@@ -1,5 +1,5 @@
 export { hydrationWaiter } from "./hydration-waiter.js";
-export { videoMode } from "./video-mode.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";

package/dist/plugins/llm-recover.js

@@ -25,6 +25,9 @@ import { adjustError } from "../plugin-system.js";
 // Uses a WeakSet of pages currently being recovered.
 const pagesInRecovery = new WeakSet();
 export const llmRecover = (options = {}) => {
+    if (process.env.PWDEBUG) {
+        return { name: "llm-recover" };
+    }
     const expect = options.expect || playwrightExpect;
     const maxAttempts = options.maxAttempts || 3;
     const requestRecovery = options.requestRecoveryCode || createAnthropicProvider(options);

package/dist/plugins/spinner-waiter.js

@@ -7,12 +7,24 @@
  * a different effective action timeout while the app is visibly loading.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import { adjustError } from "../plugin-system.js";
+import { adjustError, oneArgMethods } from "../plugin-system.js";
+/** Match `loading...`, (or really `anyVerbing...`). Also matches an ellipsis character "…" rather than "..." since LLMs like fancy unicode. */
+const loadingTextPattern = /(loading|pending|creating|verifying|starting|processing|syncing|building|\b\w+ing)[\s\w]*(\.\.\.|…)$/;
 const defaultSelectors = [
     `[aria-label="Loading"]`,
     `[data-spinner='true']`,
-    `:text-matches("(loading|pending|creating|verifying|starting|processing|syncing)\\.\\.\\.$", "i")`,
+    `:text-matches(${JSON.stringify(loadingTextPattern.source)}, "i")`,
 ];
+const oneArgMethodNames = new Set(oneArgMethods);
+const enabledActionMethods = new Set([
+    "clear",
+    "click",
+    "dblclick",
+    "fill",
+    "focus",
+    "press",
+    "type",
+]);
 const defaults = {
     spinnerSelectors: defaultSelectors,
     spinnerTimeout: 30_000,
@@ -43,29 +55,32 @@ const suggestSpinnerMessage = (spinnerLocator) => [
  * `spinnerWaiter.settings.run({...}, () => locator.click())`.
  */
 export const spinnerWaiter = Object.assign((options = {}) => {
+    if (process.env.PWDEBUG) {
+        return { name: "spinner-waiter" };
+    }
     return {
         name: "spinner-waiter",
-        middleware: async ({ locator, method, page }, next) => {
+        middleware: async ({ args, locator, method, page }, next) => {
             const settings = getSettings(options);
             if (settings.disabled)
                 return next();
             const start = Date.now();
             settings.log(`${locator}.${method}(...) starting`);
-            // Quick check if element is already visible
-            const elementVisible = await waitForVisible(locator, { timeout: 1000 });
-            if (elementVisible) {
-                settings.log(`${locator} already visible, proceeding`);
+            // Quick check if element is already ready for the attempted action.
+            const elementReady = await waitForReady(locator, method, { timeout: 1000 });
+            if (elementReady) {
+                settings.log(`${locator} already ready, proceeding`);
                 return next();
             }
             // Check for spinner
             const spinnerSelector = settings.spinnerSelectors.join(",");
             const spinnerLocator = page.locator(spinnerSelector);
-            const spinnerVisible = await spinnerLocator.isVisible();
+            const spinnerVisible = await anySpinnerVisible(spinnerLocator);
             if (!spinnerVisible) {
                 // No spinner - call action, suggest adding one if it fails
-                settings.log(`${locator} not visible, no spinner, proceeding anyway`);
+                settings.log(`${locator} not ready, no spinner, failing fast`);
                 try {
-                    return await next();
+                    return await next(withTimeoutOption(method, args, 1));
                 }
                 catch (error) {
                     adjustError(error, suggestSpinnerMessage(spinnerLocator), "spinner-waiter.ts");
@@ -75,15 +90,15 @@ export const spinnerWaiter = Object.assign((options = {}) => {
             settings.log(`Spinner visible, waiting up to ${settings.spinnerTimeout - 2000}ms for ${locator}`);
             // Spinner is visible — wait for the element, but bail early if the spinner
             // disappears (the loading operation finished without producing the expected element).
-            const waitResult = await waitForVisibleWhileSpinning(locator, spinnerLocator, {
+            const waitResult = await waitForReadyWhileSpinning(locator, method, spinnerLocator, {
                 timeout: settings.spinnerTimeout - 2000,
             });
             if (waitResult === "appeared") {
-                settings.log(`${locator} appeared after waiting`);
+                settings.log(`${locator} became ready after waiting`);
                 return next();
             }
             if (waitResult === "spinner-gone") {
-                settings.log(`Spinner disappeared but element not visible — loading finished without expected result`);
+                settings.log(`Spinner disappeared but element not ready — loading finished without expected result`);
             }
             else {
                 settings.log(`Spinner still visible after ${settings.spinnerTimeout}ms, UI likely stuck`);
@@ -94,7 +109,7 @@ export const spinnerWaiter = Object.assign((options = {}) => {
             }
             catch (error) {
                 const message = waitResult === "spinner-gone"
-                    ? `Loading finished (spinner disappeared after ${Date.now() - start}ms) but the expected element never appeared.`
+                    ? `Loading finished (spinner disappeared after ${Date.now() - start}ms) but the expected element was not ready.`
                     : `Spinner was still visible after ${settings.spinnerTimeout}ms, the UI is likely stuck.`;
                 adjustError(error, [message], "spinner-waiter.ts");
                 throw error;
@@ -107,32 +122,63 @@ export const spinnerWaiter = Object.assign((options = {}) => {
     /** Default settings values */
     defaults,
 });
-async function waitForVisible(locator, { timeout = 1000 } = {}) {
+async function locatorIsReady(locator, method) {
+    if (!(await locator.isVisible()))
+        return false;
+    if (!enabledActionMethods.has(method))
+        return true;
+    return await locator.isEnabled();
+}
+async function waitForReady(locator, method, { timeout = 1000 } = {}) {
     const start = Date.now();
     while (Date.now() - start < timeout) {
-        if (await locator.isVisible())
+        if (await locatorIsReady(locator, method))
             return true;
         await new Promise((resolve) => setTimeout(resolve, 100));
     }
-    return false;
+    return await locatorIsReady(locator, method);
+}
+function withTimeoutOption(method, args, timeout) {
+    const optionsIndex = oneArgMethodNames.has(method) ? 1 : 0;
+    const nextArgs = [...args];
+    const options = nextArgs[optionsIndex];
+    if (isOptionsObject(options)) {
+        nextArgs[optionsIndex] = { ...options, timeout };
+    }
+    else {
+        nextArgs[optionsIndex] = { timeout };
+    }
+    return nextArgs;
+}
+function isOptionsObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * Wait for `target` to become visible, but bail early if `spinner` disappears.
- * Returns "appeared" if target showed up, "spinner-gone" if loading finished
+ * Wait for `target` to become ready, but bail early if `spinner` disappears.
+ * Returns "appeared" if target became ready, "spinner-gone" if loading finished
  * without the target, or "timeout" if spinner was still visible at deadline.
  */
-async function waitForVisibleWhileSpinning(target, spinner, { timeout = 1000 } = {}) {
+async function waitForReadyWhileSpinning(target, method, spinner, { timeout = 1000 } = {}) {
     const start = Date.now();
     // Give the spinner a grace period before checking — it may flicker during transitions
     const spinnerGracePeriodMs = 3000;
     while (Date.now() - start < timeout) {
-        if (await target.isVisible())
+        if (await locatorIsReady(target, method))
             return "appeared";
         const elapsed = Date.now() - start;
-        if (elapsed > spinnerGracePeriodMs && !(await spinner.isVisible()))
+        if (elapsed > spinnerGracePeriodMs && !(await anySpinnerVisible(spinner)))
             return "spinner-gone";
         await new Promise((resolve) => setTimeout(resolve, 250));
     }
     return "timeout";
 }
+/**
+ * Multi-element-safe "is any spinner visible": the spinner selector union can
+ * legitimately match several loading indicators at once (e.g. two panels each
+ * showing a pending fallback), where a bare `locator.isVisible()` throws a
+ * strict-mode violation. `filter({ visible: true })` needs no strictness.
+ */
+async function anySpinnerVisible(spinnerLocator) {
+    return (await spinnerLocator.filter({ visible: true }).count()) > 0;
+}
 export { defaultSelectors };

package/dist/plugins/ui-error-reporter.js

@@ -4,6 +4,9 @@ import { adjustError } from "../plugin-system.js";
  * their text to the error message for easier debugging.
  */
 export const uiErrorReporter = (options = {}) => {
+    if (process.env.PWDEBUG) {
+        return { name: "ui-error-reporter" };
+    }
     const selector = options.selector || '[data-type="error"]';
     return {
         name: "ui-error-reporter",