craftdriver 0.0.3 → 0.2.0

package/dist/lib/clock.js

@@ -0,0 +1,407 @@
+/**
+ * Virtual clock control — freeze, advance, or override the wall clock the
+ * page sees: Date.now, new Date(), performance.now, setTimeout, setInterval,
+ * requestAnimationFrame.
+ */
+import { CraftdriverError, ErrorCode } from './errors.js';
+// ---------------------------------------------------------------------------
+// Fake-timer shim — injected into the page via addInitScript
+// ---------------------------------------------------------------------------
+//
+// The shim:
+//   • Captures real globals once (at controller-creation time).
+//   • Exposes window.__craftdriverClock__ with install / uninstall / tick /
+//     setFixedTime / setSystemTime / runFor.
+//   • The controller-creation block is guarded by an existence check so that
+//     re-evaluating the script on the same document doesn't re-capture
+//     already-faked globals.
+//   • Uses only ES5-compatible syntax so it works in every modern browser
+//     without transpilation.
+// ---------------------------------------------------------------------------
+const SHIM_SETUP = `(function() {
+  if (window.__craftdriverClock__) return;
+
+  var originals = {
+    Date: window.Date,
+    setTimeout: window.setTimeout,
+    clearTimeout: window.clearTimeout,
+    setInterval: window.setInterval,
+    clearInterval: window.clearInterval,
+    performanceNow: (window.performance && typeof window.performance.now === 'function')
+      ? window.performance.now.bind(window.performance)
+      : null,
+    requestAnimationFrame: typeof window.requestAnimationFrame === 'function'
+      ? window.requestAnimationFrame.bind(window)
+      : null,
+    cancelAnimationFrame: typeof window.cancelAnimationFrame === 'function'
+      ? window.cancelAnimationFrame.bind(window)
+      : null,
+  };
+
+  var state = {
+    installed: false,
+    fixedMode: false,
+    fixedTime: 0,
+    virtualNow: 0,
+    performanceOrigin: 0,
+    timers: [],
+    nextId: 1,
+  };
+
+  function fakeNow() {
+    if (state.fixedMode) return state.fixedTime;
+    return state.virtualNow;
+  }
+
+  function patchDate() {
+    var OrigDate = originals.Date;
+    function FakeDate() {
+      var t;
+      if (arguments.length === 0) {
+        t = new OrigDate(fakeNow());
+      } else if (arguments.length === 1) {
+        t = new OrigDate(arguments[0]);
+      } else if (arguments.length === 2) {
+        t = new OrigDate(arguments[0], arguments[1]);
+      } else if (arguments.length === 3) {
+        t = new OrigDate(arguments[0], arguments[1], arguments[2]);
+      } else if (arguments.length === 4) {
+        t = new OrigDate(arguments[0], arguments[1], arguments[2], arguments[3]);
+      } else if (arguments.length === 5) {
+        t = new OrigDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
+      } else if (arguments.length === 6) {
+        t = new OrigDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4], arguments[5]);
+      } else {
+        t = new OrigDate(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4], arguments[5], arguments[6]);
+      }
+      if (!(this instanceof FakeDate)) return t.toString();
+      return t;
+    }
+    FakeDate.now = function() { return fakeNow(); };
+    FakeDate.parse = OrigDate.parse.bind(OrigDate);
+    FakeDate.UTC = OrigDate.UTC.bind(OrigDate);
+    Object.setPrototypeOf(FakeDate, OrigDate);
+    FakeDate.prototype = OrigDate.prototype;
+    window.Date = FakeDate;
+  }
+
+  function runTimers(targetTime) {
+    while (true) {
+      var earliest = null;
+      for (var i = 0; i < state.timers.length; i++) {
+        var t = state.timers[i];
+        if (!t.cancelled && t.deadline <= targetTime) {
+          if (!earliest || t.deadline < earliest.deadline ||
+              (t.deadline === earliest.deadline && t.id < earliest.id)) {
+            earliest = t;
+          }
+        }
+      }
+      if (!earliest) break;
+
+      state.virtualNow = earliest.deadline;
+
+      if (earliest.interval !== null) {
+        earliest.deadline += earliest.interval;
+      } else {
+        var idx = state.timers.indexOf(earliest);
+        if (idx !== -1) state.timers.splice(idx, 1);
+      }
+
+      try {
+        if (typeof earliest.fn === 'function') {
+          earliest.fn.apply(null, earliest.args || []);
+        } else if (typeof earliest.fn === 'string') {
+          // setTimeout(codeString, ...) form
+          // eslint-disable-next-line no-new-func
+          new Function(earliest.fn)();
+        }
+      } catch (_e) { /* swallow timer errors */ }
+    }
+    state.virtualNow = targetTime;
+  }
+
+  var controller = {
+    install: function(opts) {
+      opts = opts || {};
+      var startTime = (opts.time != null) ? opts.time : originals.Date.now();
+      state.installed = true;
+      state.fixedMode = false;
+      state.virtualNow = startTime;
+      state.performanceOrigin = startTime;
+      state.timers = [];
+      state.nextId = 1;
+
+      patchDate();
+
+      if (window.performance && typeof window.performance.now === 'function') {
+        window.performance.now = function() {
+          return state.virtualNow - state.performanceOrigin;
+        };
+      }
+
+      window.setTimeout = function(fn, delay) {
+        var args = [];
+        for (var i = 2; i < arguments.length; i++) args.push(arguments[i]);
+        var id = state.nextId++;
+        var d = (delay == null || isNaN(+delay) || +delay < 0) ? 0 : +delay;
+        state.timers.push({ id: id, deadline: state.virtualNow + d, fn: fn, args: args, interval: null, cancelled: false });
+        return id;
+      };
+
+      window.clearTimeout = function(id) {
+        for (var i = 0; i < state.timers.length; i++) {
+          if (state.timers[i].id === id) { state.timers[i].cancelled = true; return; }
+        }
+      };
+
+      window.setInterval = function(fn, delay) {
+        var args = [];
+        for (var i = 2; i < arguments.length; i++) args.push(arguments[i]);
+        var id = state.nextId++;
+        var d = (delay == null || isNaN(+delay) || +delay < 0) ? 0 : +delay;
+        state.timers.push({ id: id, deadline: state.virtualNow + d, fn: fn, args: args, interval: d, cancelled: false });
+        return id;
+      };
+
+      window.clearInterval = function(id) {
+        for (var i = 0; i < state.timers.length; i++) {
+          if (state.timers[i].id === id) { state.timers[i].cancelled = true; return; }
+        }
+      };
+
+      if (originals.requestAnimationFrame) {
+        window.requestAnimationFrame = function(fn) { return window.setTimeout(fn, 16); };
+        window.cancelAnimationFrame = function(id) { window.clearTimeout(id); };
+      }
+    },
+
+    uninstall: function() {
+      if (!state.installed && !state.fixedMode) return;
+      window.Date = originals.Date;
+      if (window.performance && originals.performanceNow) {
+        window.performance.now = originals.performanceNow;
+      }
+      window.setTimeout = originals.setTimeout;
+      window.clearTimeout = originals.clearTimeout;
+      window.setInterval = originals.setInterval;
+      window.clearInterval = originals.clearInterval;
+      if (originals.requestAnimationFrame) {
+        window.requestAnimationFrame = originals.requestAnimationFrame;
+        window.cancelAnimationFrame = originals.cancelAnimationFrame;
+      }
+      state.installed = false;
+      state.fixedMode = false;
+      state.timers = [];
+    },
+
+    tick: function(ms) {
+      if (!state.installed) throw new Error('[craftdriver clock] tick() requires install() first');
+      runTimers(state.virtualNow + ms);
+    },
+
+    setFixedTime: function(time) {
+      state.fixedMode = true;
+      state.fixedTime = time;
+      patchDate();
+      if (window.performance && typeof window.performance.now === 'function') {
+        window.performance.now = function() { return 0; };
+      }
+    },
+
+    setSystemTime: function(time) {
+      if (!state.installed) throw new Error('[craftdriver clock] setSystemTime() requires install() first');
+      var delta = time - state.virtualNow;
+      state.virtualNow = time;
+      // Shift all pending timer deadlines by the same amount so they remain
+      // at the same relative distance from the new "now".
+      for (var i = 0; i < state.timers.length; i++) {
+        if (!state.timers[i].cancelled) {
+          state.timers[i].deadline += delta;
+        }
+      }
+    },
+
+    runFor: function(ms) {
+      if (!state.installed) throw new Error('[craftdriver clock] runFor() requires install() first');
+      var target = state.virtualNow + ms;
+      while (state.virtualNow < target) {
+        var next = Math.min(state.virtualNow + 16, target);
+        runTimers(next);
+      }
+    },
+  };
+
+  window.__craftdriverClock__ = controller;
+})();`;
+// ---------------------------------------------------------------------------
+// Node-side Clock class
+// ---------------------------------------------------------------------------
+/** Controls the virtual clock inside the browser page. */
+export class Clock {
+    adapter;
+    _preloadHandle = null;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    // ── Time helpers ──────────────────────────────────────────────────────────
+    parseTime(time) {
+        if (typeof time === 'number')
+            return time;
+        if (time instanceof Date)
+            return time.getTime();
+        const ms = new Date(time).getTime();
+        if (isNaN(ms)) {
+            throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `clock: cannot parse time "${String(time)}". ` +
+                'Pass a number (ms since epoch), a Date object, or an ISO date string ' +
+                'like "2026-01-01T00:00:00Z".', { detail: { time: String(time) } });
+        }
+        return ms;
+    }
+    /**
+     * Parse a duration string "MM:SS" or "HH:MM:SS" (numbers can exceed
+     * 59, e.g. "90:00" = 90 minutes).  A plain number is returned as-is.
+     */
+    parseDuration(d) {
+        if (typeof d === 'number')
+            return d;
+        const parts = d.split(':').map(Number);
+        if (parts.some(isNaN)) {
+            throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `clock.fastForward: cannot parse duration "${d}". ` +
+                'Pass a number (ms), "MM:SS", or "HH:MM:SS".', { detail: { duration: d } });
+        }
+        if (parts.length === 2) {
+            const [mm, ss] = parts;
+            return (mm * 60 + ss) * 1000;
+        }
+        if (parts.length === 3) {
+            const [hh, mm, ss] = parts;
+            return (hh * 3600 + mm * 60 + ss) * 1000;
+        }
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `clock.fastForward: cannot parse duration "${d}". ` +
+            'Pass a number (ms), "MM:SS", or "HH:MM:SS".', { detail: { duration: d } });
+    }
+    // ── Preload script management ──────────────────────────────────────────────
+    async registerPreload(methodCall) {
+        if (this._preloadHandle) {
+            await this._preloadHandle.remove();
+            this._preloadHandle = null;
+        }
+        const script = `${SHIM_SETUP}\nwindow.__craftdriverClock__.${methodCall};`;
+        this._preloadHandle = await this.adapter.addInitScript(script);
+    }
+    /**
+     * Evaluate the shim + method call in the current document, ignoring errors
+     * that occur when no page is loaded yet (about:blank / no context).
+     */
+    async applyNow(methodCall) {
+        const script = `${SHIM_SETUP}\nwindow.__craftdriverClock__.${methodCall}`;
+        try {
+            await this.adapter.evaluate(script);
+        }
+        catch {
+            // No document loaded yet — the preload script will handle it on next navigate.
+        }
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Install fake timers in the browser page.
+     *
+     * Patches `Date`, `performance.now`, `setTimeout`, `setInterval`,
+     * `clearTimeout`, `clearInterval`, `requestAnimationFrame`, and
+     * `cancelAnimationFrame`.  Timers only fire when you call `tick()`,
+     * `fastForward()`, or `runFor()`.
+     *
+     * Also registers a preload script so the fake clock is re-installed
+     * automatically on every subsequent navigation.
+     *
+     * @example
+     * await browser.clock.install({ time: '2026-01-01T09:00:00Z' });
+     * await browser.navigateTo('/dashboard');
+     * await browser.clock.fastForward('15:01');
+     */
+    async install(options) {
+        const timeMs = options?.time !== undefined ? this.parseTime(options.time) : Date.now();
+        const methodCall = `install({time: ${timeMs}})`;
+        await this.registerPreload(methodCall);
+        await this.applyNow(methodCall);
+    }
+    /**
+     * Uninstall fake timers and restore the real `Date`, `setTimeout`, etc.
+     * Also removes the preload script so navigations use the real clock again.
+     */
+    async uninstall() {
+        if (this._preloadHandle) {
+            await this._preloadHandle.remove();
+            this._preloadHandle = null;
+        }
+        await this.applyNow('uninstall()');
+    }
+    /**
+     * Advance the fake clock by `ms` milliseconds and fire all timers that
+     * come due within that window.
+     *
+     * Requires `install()` to have been called first.
+     */
+    async tick(ms) {
+        await this.adapter.evaluate(`window.__craftdriverClock__.tick(${ms})`);
+    }
+    /**
+     * Advance the fake clock and fire due timers.
+     * Accepts a number of milliseconds **or** a duration string:
+     * `"MM:SS"` (e.g. `"15:01"` = 15 min 1 s) or `"HH:MM:SS"`.
+     *
+     * Requires `install()` to have been called first.
+     *
+     * @example
+     * await browser.clock.fastForward('15:01'); // advance 15 minutes 1 second
+     * await browser.clock.fastForward(60_000);  // advance 60 seconds
+     */
+    async fastForward(duration) {
+        const ms = this.parseDuration(duration);
+        await this.tick(ms);
+    }
+    /**
+     * Freeze `Date.now()` / `new Date()` at the given instant.
+     *
+     * Unlike `install()`, this does **not** fake `setTimeout` or `setInterval`;
+     * real timers continue to fire.  Use this when you only need to control
+     * what "now" is for date-based rendering.
+     *
+     * Also registers a preload script so the fixed date persists across
+     * navigations.
+     *
+     * @example
+     * await browser.clock.setFixedTime('2026-06-15T23:59:00Z');
+     * await browser.navigateTo('/billing');
+     * await browser.expect('#trial-banner').toContainText('expires today');
+     */
+    async setFixedTime(time) {
+        const ms = this.parseTime(time);
+        const methodCall = `setFixedTime(${ms})`;
+        await this.registerPreload(methodCall);
+        await this.applyNow(methodCall);
+    }
+    /**
+     * Move the fake clock to `time` without advancing the timer queue.
+     * Timers that were scheduled continue to fire at their original
+     * relative offsets from the new base time when you call `tick()`.
+     *
+     * Requires `install()` to have been called first.
+     */
+    async setSystemTime(time) {
+        const ms = this.parseTime(time);
+        await this.adapter.evaluate(`window.__craftdriverClock__.setSystemTime(${ms})`);
+    }
+    /**
+     * Advance the fake clock by `ms` milliseconds, yielding between each
+     * ~16 ms frame so that microtasks and promise callbacks resolve in the
+     * correct order.
+     *
+     * Requires `install()` to have been called first.
+     */
+    async runFor(ms) {
+        await this.adapter.evaluate(`window.__craftdriverClock__.runFor(${ms})`);
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/lib/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/lib/clock.ts"],"names":[],"mappings":"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"}

package/dist/lib/driver.d.ts

@@ -5,15 +5,31 @@ import { type Condition, type WaitOptions } from './wait.js';
 export declare class Driver {
     private endpoint;
     private sessionId;
+    /** BiDi WebSocket URL if available */
+    __wsUrl?: string;
     constructor(endpoint: WebDriverEndpoint, sessionId: string);
     static create(endpoint: WebDriverEndpoint, caps: Capabilities): Promise<Driver>;
     navigateTo(url: string): Promise<void>;
+    /** W3C `POST /session/{id}/back` — navigate the current top-level browsing context back one step. */
+    back(): Promise<void>;
+    /** W3C `POST /session/{id}/forward` — navigate forward one step in the joint session history. */
+    forward(): Promise<void>;
+    /** W3C `POST /session/{id}/refresh` — reload the current top-level browsing context. */
+    refresh(): Promise<void>;
     quit(): Promise<void>;
     getCurrentUrl(): Promise<string>;
     getTitle(): Promise<string>;
     findElement(locator: By): Promise<WebElement>;
     findElements(locator: By): Promise<WebElement[]>;
     executeScript<T = unknown>(script: string, args?: unknown[]): Promise<T>;
+    /**
+     * Execute an asynchronous script. The script receives a callback as its
+     * last argument and must invoke it with the result (or with no argument
+     * for `undefined`). Resolves with the value passed to the callback.
+     */
+    executeAsyncScript<T = unknown>(script: string, args?: unknown[]): Promise<T>;
+    /** Configure the script (and async-script) timeout in milliseconds. */
+    setScriptTimeout(ms: number): Promise<void>;
     wait<T>(condition: Condition<T>, options?: WaitOptions & {
         message?: string;
     }): Promise<T>;
@@ -30,6 +46,35 @@ export declare class Driver {
     performTouchSwipe(from: [number, number], to: [number, number], durationMs?: number): Promise<void>;
     performTouchPinch(center: [number, number], scale?: number, distance?: number, durationMs?: number): Promise<void>;
     screenshotBase64(): Promise<string>;
+    /**
+     * W3C `POST /session/{id}/window/rect` — resize / reposition the
+     * current top-level browsing context's window. Approximates a
+     * viewport resize when BiDi's `browsingContext.setViewport` is not
+     * available.
+     */
+    setWindowRect(rect: {
+        width: number;
+        height: number;
+        x?: number;
+        y?: number;
+    }): Promise<void>;
+    getAlertText(): Promise<string>;
+    acceptAlert(): Promise<void>;
+    dismissAlert(): Promise<void>;
+    sendAlertText(text: string): Promise<void>;
     __sendActions(actions: any[]): Promise<void>;
+    /**
+     * Switch to an iframe by null (top-level), numeric index, or element reference.
+     * Pass `null` to switch back to the top-level browsing context.
+     */
+    switchToFrame(id: null | number | {
+        elementId: string;
+    }): Promise<void>;
+    /** Return all window handles for the current session. */
+    getWindowHandles(): Promise<string[]>;
+    /** Switch focus to the window with the given handle. */
+    switchToWindow(handle: string): Promise<void>;
+    /** Return the handle for the currently focused window. */
+    getCurrentWindowHandle(): Promise<string>;
 }
 //# sourceMappingURL=driver.d.ts.map

package/dist/lib/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/lib/driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/lib/driver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAmB,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AACpG,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAuC,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE5E,qBAAa,MAAM;IAKf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IALnB,sCAAsC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;gBAGd,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,MAAM;WAGd,MAAM,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA4B/E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C,qGAAqG;IAC/F,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,iGAAiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,wFAAwF;IAClF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAKxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAUhC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAU3B,WAAW,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAe7C,YAAY,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAkBhD,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAUlF;;;;OAIG;IACG,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAUvF,uEAAuE;IACjE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAC1F,IAAI,CAAC,CAAC,EACJ,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC;IAgBP,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB7D,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrC,aAAa,CACjB,aAAa,CAAC,EAAE,UAAU,EAC1B,CAAC,CAAC,EAAE,MAAM,EACV,CAAC,CAAC,EAAE,MAAM,EACV,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,IAAI,CAAC;IA6BV,SAAS,CAAC,MAAM,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB5C,OAAO,CAAC,MAAM,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1C,YAAY,CAChB,aAAa,CAAC,EAAE,UAAU,EAC1B,CAAC,CAAC,EAAE,MAAM,EACV,CAAC,CAAC,EAAE,MAAM,EACV,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAAU,EACjB,YAAY,GAAE,MAAW,GACxB,OAAO,CAAC,IAAI,CAAC;IA2BV,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,CAAC,GAAE,MAAU,EACb,CAAC,GAAE,MAAU,EACb,QAAQ,GAAE,MAAU,GACnB,OAAO,CAAC,IAAI,CAAC;IAiBV,iBAAiB,CACrB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACpB,UAAU,SAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAyBV,iBAAiB,CACrB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EACxB,KAAK,SAAM,EACX,QAAQ,SAAM,EACd,UAAU,SAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAyCV,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IASzC;;;;;OAKG;IACG,aAAa,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7F,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAS/B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1C,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlD;;;OAGG;IACG,aAAa,CAAC,EAAE,EAAE,IAAI,GAAG,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7E,yDAAyD;IACnD,gBAAgB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAO3C,wDAAwD;IAClD,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD,0DAA0D;IACpD,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;CAMhD"}

package/dist/lib/driver.js

@@ -4,6 +4,8 @@ import { WebDriverWait } from './wait.js';
 export class Driver {
     endpoint;
     sessionId;
+    /** BiDi WebSocket URL if available */
+    __wsUrl;
     constructor(endpoint, sessionId) {
         this.endpoint = endpoint;
         this.sessionId = sessionId;
@@ -23,12 +25,33 @@ export class Driver {
             const msg = v?.message || v?.data || JSON.stringify(res);
             throw new Error(`Failed to create session${err ? ` [${err}]` : ''}: ${msg}`);
         }
-        return new Driver(endpoint, sessionId);
+        const driver = new Driver(endpoint, sessionId);
+        // Capture BiDi WebSocket URL from capabilities if available
+        const capabilities = value?.capabilities || res?.capabilities;
+        if (capabilities?.webSocketUrl) {
+            driver.__wsUrl = capabilities.webSocketUrl;
+        }
+        return driver;
     }
     async navigateTo(url) {
         const client = new HttpClient(this.endpoint);
         await client.send({ method: 'POST', path: `/session/${this.sessionId}/url`, body: { url } });
     }
+    /** W3C `POST /session/{id}/back` — navigate the current top-level browsing context back one step. */
+    async back() {
+        const client = new HttpClient(this.endpoint);
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/back`, body: {} });
+    }
+    /** W3C `POST /session/{id}/forward` — navigate forward one step in the joint session history. */
+    async forward() {
+        const client = new HttpClient(this.endpoint);
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/forward`, body: {} });
+    }
+    /** W3C `POST /session/{id}/refresh` — reload the current top-level browsing context. */
+    async refresh() {
+        const client = new HttpClient(this.endpoint);
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/refresh`, body: {} });
+    }
     async quit() {
         const client = new HttpClient(this.endpoint);
         await client.send({ method: 'DELETE', path: `/session/${this.sessionId}` });
@@ -92,6 +115,29 @@ export class Driver {
         });
         return (res?.value ?? res);
     }
+    /**
+     * Execute an asynchronous script. The script receives a callback as its
+     * last argument and must invoke it with the result (or with no argument
+     * for `undefined`). Resolves with the value passed to the callback.
+     */
+    async executeAsyncScript(script, args = []) {
+        const client = new HttpClient(this.endpoint);
+        const res = await client.send({
+            method: 'POST',
+            path: `/session/${this.sessionId}/execute/async`,
+            body: { script, args },
+        });
+        return (res?.value ?? res);
+    }
+    /** Configure the script (and async-script) timeout in milliseconds. */
+    async setScriptTimeout(ms) {
+        const client = new HttpClient(this.endpoint);
+        await client.send({
+            method: 'POST',
+            path: `/session/${this.sessionId}/timeouts`,
+            body: { script: ms },
+        });
+    }
     wait(condition, a, b, c) {
         // Overload: prefer options object, but accept legacy positional args
         if (typeof a === 'object') {
@@ -334,6 +380,50 @@ export class Driver {
         });
         return String(res?.value ?? res ?? '');
     }
+    /**
+     * W3C `POST /session/{id}/window/rect` — resize / reposition the
+     * current top-level browsing context's window. Approximates a
+     * viewport resize when BiDi's `browsingContext.setViewport` is not
+     * available.
+     */
+    async setWindowRect(rect) {
+        const client = new HttpClient(this.endpoint);
+        const body = { width: rect.width, height: rect.height };
+        if (rect.x !== undefined)
+            body.x = rect.x;
+        if (rect.y !== undefined)
+            body.y = rect.y;
+        await client.send({
+            method: 'POST',
+            path: `/session/${this.sessionId}/window/rect`,
+            body,
+        });
+    }
+    // --- Alert / dialog endpoints (W3C Classic WebDriver) ---
+    async getAlertText() {
+        const client = new HttpClient(this.endpoint);
+        const res = await client.send({
+            method: 'GET',
+            path: `/session/${this.sessionId}/alert/text`,
+        });
+        return String(res?.value ?? res ?? '');
+    }
+    async acceptAlert() {
+        const client = new HttpClient(this.endpoint);
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/alert/accept`, body: {} });
+    }
+    async dismissAlert() {
+        const client = new HttpClient(this.endpoint);
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/alert/dismiss`, body: {} });
+    }
+    async sendAlertText(text) {
+        const client = new HttpClient(this.endpoint);
+        await client.send({
+            method: 'POST',
+            path: `/session/${this.sessionId}/alert/text`,
+            body: { text },
+        });
+    }
     // Internal helper for ActionsBuilder to send combined payloads
     async __sendActions(actions) {
         const client = new HttpClient(this.endpoint);
@@ -343,5 +433,43 @@ export class Driver {
             body: { actions },
         });
     }
+    // --- Frame / window switching (W3C Classic WebDriver) ---
+    /**
+     * Switch to an iframe by null (top-level), numeric index, or element reference.
+     * Pass `null` to switch back to the top-level browsing context.
+     */
+    async switchToFrame(id) {
+        const client = new HttpClient(this.endpoint);
+        let bodyId;
+        if (id === null) {
+            bodyId = null;
+        }
+        else if (typeof id === 'number') {
+            bodyId = id;
+        }
+        else {
+            bodyId = { [W3C_ELEMENT_KEY]: id.elementId, [LEGACY_ELEMENT_KEY]: id.elementId };
+        }
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/frame`, body: { id: bodyId } });
+    }
+    /** Return all window handles for the current session. */
+    async getWindowHandles() {
+        const client = new HttpClient(this.endpoint);
+        const res = await client.send({ method: 'GET', path: `/session/${this.sessionId}/window/handles` });
+        const v = res?.value ?? res;
+        return Array.isArray(v) ? v : [];
+    }
+    /** Switch focus to the window with the given handle. */
+    async switchToWindow(handle) {
+        const client = new HttpClient(this.endpoint);
+        await client.send({ method: 'POST', path: `/session/${this.sessionId}/window`, body: { handle } });
+    }
+    /** Return the handle for the currently focused window. */
+    async getCurrentWindowHandle() {
+        const client = new HttpClient(this.endpoint);
+        const res = await client.send({ method: 'GET', path: `/session/${this.sessionId}/window` });
+        const v = res?.value ?? res;
+        return String(v ?? '');
+    }
 }
 //# sourceMappingURL=driver.js.map