@itmetsam/samurai-framework 0.1.0

package/src/types/bidi-modules/emulation.d.ts

@@ -0,0 +1,280 @@
+import type { EmptyResult } from "../bidi.js";
+import type { UserContext } from "./browser.js";
+import type { BrowsingContext } from "./browsing-context.js";
+
+/** Commands available in the emulation module, keyed by method name. */
+export interface EmulationCommands {
+  "emulation.setForcedColorsModeThemeOverride": {
+    params: SetForcedColorsModeThemeOverrideParameters;
+    result: SetForcedColorsModeThemeOverrideResult;
+  };
+  "emulation.setGeolocationOverride": {
+    params: SetGeolocationOverrideParameters;
+    result: SetGeolocationOverrideResult;
+  };
+  "emulation.setLocaleOverride": { params: SetLocaleOverrideParameters; result: SetLocaleOverrideResult };
+  "emulation.setNetworkConditions": { params: SetNetworkConditionsParameters; result: EmptyResult };
+  "emulation.setScreenOrientationOverride": {
+    params: SetScreenOrientationOverrideParameters;
+    result: SetScreenOrientationOverrideResult;
+  };
+  "emulation.setScreenSettingsOverride": { params: SetScreenSettingsOverrideParameters; result: EmptyResult };
+  "emulation.setScriptingEnabled": { params: SetScriptingEnabledParameters; result: SetScriptingEnabledResult };
+  "emulation.setScrollbarTypeOverride": {
+    params: SetScrollbarTypeOverrideParameters;
+    result: SetScrollbarTypeOverrideResult;
+  };
+  "emulation.setTimezoneOverride": { params: SetTimezoneOverrideParameters; result: SetTimezoneOverrideResult };
+  "emulation.setTouchOverride": { params: SetTouchOverrideParameters; result: SetTouchOverrideResult };
+  "emulation.setUserAgentOverride": { params: SetUserAgentOverrideParameters; result: SetUserAgentOverrideResult };
+}
+
+/** Union of all possible result types returned by emulation module commands. */
+export type EmulationResult =
+  | SetForcedColorsModeThemeOverrideResult
+  | SetGeolocationOverrideResult
+  | SetLocaleOverrideResult
+  | SetScreenOrientationOverrideResult
+  | SetScriptingEnabledResult
+  | SetScrollbarTypeOverrideResult
+  | SetTimezoneOverrideResult
+  | SetTouchOverrideResult
+  | SetUserAgentOverrideResult;
+
+/** Result of `emulation.setForcedColorsModeThemeOverride`. */
+export type SetForcedColorsModeThemeOverrideResult = EmptyResult;
+/** Result of `emulation.setGeolocationOverride`. */
+export type SetGeolocationOverrideResult = EmptyResult;
+/** Result of `emulation.setLocaleOverride`. */
+export type SetLocaleOverrideResult = EmptyResult;
+/** Result of `emulation.setScreenOrientationOverride`. */
+export type SetScreenOrientationOverrideResult = EmptyResult;
+/** Result of `emulation.setScriptingEnabled`. */
+export type SetScriptingEnabledResult = EmptyResult;
+/** Result of `emulation.setScrollbarTypeOverride`. */
+export type SetScrollbarTypeOverrideResult = EmptyResult;
+/** Result of `emulation.setTimezoneOverride`. */
+export type SetTimezoneOverrideResult = EmptyResult;
+/** Result of `emulation.setTouchOverride`. */
+export type SetTouchOverrideResult = EmptyResult;
+/** Result of `emulation.setUserAgentOverride`. */
+export type SetUserAgentOverrideResult = EmptyResult;
+
+/** Union of all commands in the emulation module, which overrides device and environment properties. */
+export type EmulationCommand =
+  | SetForcedColorsModeThemeOverride
+  | SetGeolocationOverride
+  | SetLocaleOverride
+  | SetNetworkConditions
+  | SetScreenOrientationOverride
+  | SetScreenSettingsOverride
+  | SetScriptingEnabled
+  | SetScrollbarTypeOverride
+  | SetTimezoneOverride
+  | SetTouchOverride
+  | SetUserAgentOverride;
+
+/** The color scheme theme to emulate for forced-colors media queries. */
+export type ForcedColorsModeTheme = "light" | "dark";
+
+/** Parameters for `emulation.setForcedColorsModeThemeOverride`. */
+export interface SetForcedColorsModeThemeOverrideParameters {
+  /** The theme to force, or `null` to reset to the real value. */
+  theme: ForcedColorsModeTheme | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides the forced-colors media feature theme (e.g. to simulate Windows High Contrast). */
+export interface SetForcedColorsModeThemeOverride {
+  method: "emulation.setForcedColorsModeThemeOverride";
+  params: SetForcedColorsModeThemeOverrideParameters;
+}
+
+/** Indicates that the geolocation position is unavailable. */
+export interface GeolocationPositionError {
+  type: "positionUnavailable";
+}
+
+/** A geolocation override response that simulates an unavailable position. */
+export interface GeolocationCoordinatesResponseError {
+  error: GeolocationPositionError;
+}
+
+/** A geolocation override response with specific coordinates (or `null` to reset). */
+export interface GeolocationCoordinatesResponse {
+  coordinates: GeolocationCoordinates | null;
+}
+
+/** Either a successful coordinates override or an error response. */
+export type GeolocationOverrideResponse =
+  | GeolocationCoordinatesResponse
+  | GeolocationCoordinatesResponseError;
+
+/** Parameters for `emulation.setGeolocationOverride`. */
+export type SetGeolocationOverrideParameters = GeolocationOverrideResponse & {
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+};
+
+/** Overrides the geolocation position reported to scripts. */
+export interface SetGeolocationOverride {
+  method: "emulation.setGeolocationOverride";
+  params: SetGeolocationOverrideParameters;
+}
+
+/** Parameters for `emulation.setLocaleOverride`. */
+export interface SetLocaleOverrideParameters {
+  /** BCP 47 locale tag to override with, or `null` to reset. */
+  locale: string | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides the locale reported to scripts (e.g. `Intl` APIs). */
+export interface SetLocaleOverride {
+  method: "emulation.setLocaleOverride";
+  params: SetLocaleOverrideParameters;
+}
+
+/** Network conditions to simulate — currently only `offline` is supported. */
+export type NetworkConditions = NetworkConditionsOffline;
+
+/** Simulates a completely offline network connection. */
+export interface NetworkConditionsOffline {
+  type: "offline";
+}
+
+/** Parameters for `emulation.setNetworkConditions`. */
+export interface SetNetworkConditionsParameters {
+  /** The network conditions to simulate, or `null` to reset. */
+  networkConditions: NetworkConditions | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Simulates network conditions such as being offline. */
+export interface SetNetworkConditions {
+  method: "emulation.setNetworkConditions";
+  params: SetNetworkConditionsParameters;
+}
+
+/** Parameters for `emulation.setScreenOrientationOverride`. */
+export interface SetScreenOrientationOverrideParameters {
+  /** The orientation to emulate, or `null` to reset. */
+  screenOrientation: ScreenOrientation | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** The natural orientation and current type of the screen. */
+export interface ScreenOrientation {
+  natural: ScreenOrientationNatural;
+  type: ScreenOrientationType;
+}
+
+/** The device's natural (hardware) orientation. */
+export type ScreenOrientationNatural = "landscape" | "portrait";
+
+/** The logical screen orientation type as defined by the Screen Orientation API. */
+export type ScreenOrientationType =
+  | "portrait-primary"
+  | "portrait-secondary"
+  | "landscape-primary"
+  | "landscape-secondary";
+
+/** Overrides the screen orientation reported to scripts. */
+export interface SetScreenOrientationOverride {
+  method: "emulation.setScreenOrientationOverride";
+  params: SetScreenOrientationOverrideParameters;
+}
+
+/** Width and height of a screen area in CSS pixels. */
+export interface ScreenArea {
+  width: number;
+  height: number;
+}
+
+/** Parameters for `emulation.setScreenSettingsOverride`. */
+export interface SetScreenSettingsOverrideParameters {
+  /** The screen area dimensions to emulate, or `null` to reset. */
+  screenArea: ScreenArea | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides screen size settings (e.g. `screen.width` / `screen.height`) reported to scripts. */
+export interface SetScreenSettingsOverride {
+  method: "emulation.setScreenSettingsOverride";
+  params: SetScreenSettingsOverrideParameters;
+}
+
+/** Parameters for `emulation.setScriptingEnabled`. */
+export interface SetScriptingEnabledParameters {
+  /** `false` to disable JavaScript execution, or `null` to reset to default. */
+  enabled: false | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Disables or re-enables JavaScript execution in the given contexts. */
+export interface SetScriptingEnabled {
+  method: "emulation.setScriptingEnabled";
+  params: SetScriptingEnabledParameters;
+}
+
+/** Parameters for `emulation.setScrollbarTypeOverride`. */
+export interface SetScrollbarTypeOverrideParameters {
+  /** `"classic"` for always-visible scrollbars, `"overlay"` for overlay scrollbars, or `null` to reset. */
+  scrollbarType: "classic" | "overlay" | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides the scrollbar rendering style in the given contexts. */
+export interface SetScrollbarTypeOverride {
+  method: "emulation.setScrollbarTypeOverride";
+  params: SetScrollbarTypeOverrideParameters;
+}
+
+/** Parameters for `emulation.setTimezoneOverride`. */
+export interface SetTimezoneOverrideParameters {
+  /** A valid IANA timezone identifier (e.g. `"America/New_York"`), or `null` to reset. */
+  timezone: string | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides the timezone used by scripts (e.g. `Intl.DateTimeFormat`). */
+export interface SetTimezoneOverride {
+  method: "emulation.setTimezoneOverride";
+  params: SetTimezoneOverrideParameters;
+}
+
+/** Parameters for `emulation.setTouchOverride`. */
+export interface SetTouchOverrideParameters {
+  /** Maximum number of simultaneous touch points to emulate, or `null` to reset. */
+  maxTouchPoints: number | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides touch support, enabling touch events in non-touch environments. */
+export interface SetTouchOverride {
+  method: "emulation.setTouchOverride";
+  params: SetTouchOverrideParameters;
+}
+
+/** Parameters for `emulation.setUserAgentOverride`. */
+export interface SetUserAgentOverrideParameters {
+  /** The user-agent string to report, or `null` to reset to the real value. */
+  userAgent: string | null;
+  contexts?: BrowsingContext[];
+  userContexts?: UserContext[];
+}
+
+/** Overrides the User-Agent string reported by the browser. */
+export interface SetUserAgentOverride {
+  method: "emulation.setUserAgentOverride";
+  params: SetUserAgentOverrideParameters;
+}

package/src/types/bidi-modules/input.d.ts

@@ -0,0 +1,201 @@
+import type { EmptyResult } from "../bidi.js";
+import type { UserContext } from "./browser.js";
+import type { BrowsingContext, SharedReference } from "./browsing-context.js";
+
+/** Commands available in the WebDriver BiDi input module, which simulates user input. */
+export interface InputCommands {
+  /** Performs a sequence of input actions (keyboard, mouse, wheel, etc.) in the given browsing context. */
+  "input.performActions": {
+    params: {
+      context: BrowsingContext;
+      actions: SourceActions[];
+    };
+    result: {};
+  };
+  /** Sets the files of an `<input type=file>` element; `[]` clears them. */
+  "input.setFiles": {
+    params: {
+      context: BrowsingContext;
+      element: SharedReference;
+      files: string[];
+    };
+    result: {};
+  };
+}
+
+/** A set of actions for a single input source — none, key, pointer, or wheel. */
+export type SourceActions =
+  | NoneSourceActions
+  | KeySourceActions
+  | PointerSourceActions
+  | WheelSourceActions;
+
+/** Actions for a null input source, which only supports pause. */
+export interface NoneSourceActions {
+  type: "none";
+  id: string;
+  actions: NoneSourceAction[];
+}
+
+/** A single action for a null input source. */
+export type NoneSourceAction = PauseAction;
+
+/** Actions for a keyboard input source. */
+export interface KeySourceActions {
+  type: "key";
+  id: string;
+  actions: KeySourceAction[];
+}
+
+/** A single action for a keyboard input source. */
+export type KeySourceAction = PauseAction | KeyDownAction | KeyUpAction;
+
+/** Actions for a pointer input source (mouse, pen, or touch). */
+export interface PointerSourceActions {
+  type: "pointer";
+  id: string;
+  parameters?: PointerParameters | undefined;
+  actions: PointerSourceAction[];
+}
+
+/** The kind of pointer device being simulated. */
+export type PointerType = "mouse" | "pen" | "touch";
+
+/** Optional configuration for a pointer input source. */
+export interface PointerParameters {
+  pointerType: PointerType;
+}
+
+/** A single action for a pointer input source. */
+export type PointerSourceAction =
+  | PauseAction
+  | PointerDownAction
+  | PointerUpAction
+  | PointerMoveAction;
+
+/** Actions for a wheel input source. */
+export interface WheelSourceActions {
+  type: "wheel";
+  id: string;
+  actions: WheelSourceAction[];
+}
+
+/** A single action for a wheel input source. */
+export type WheelSourceAction = PauseAction | WheelScrollAction;
+
+/** Pauses the input sequence for an optional duration in milliseconds. */
+export interface PauseAction {
+  type: "pause";
+  duration?: number | undefined;
+}
+
+/** Simulates pressing a key down. */
+export interface KeyDownAction {
+  type: "keyDown";
+  value: string;
+}
+
+/** Simulates releasing a key. */
+export interface KeyUpAction {
+  type: "keyUp";
+  value: string;
+}
+
+/**
+ * 0 — Left button (primary)
+ * 1 — Middle button (scroll wheel click)
+ * 2 — Right button (context menu)
+ * 3 — Back button
+ * 4 — Forward button
+ */
+export type PointerButton = 0 | 1 | 2 | 3 | 4;
+
+/** Simulates releasing a pointer button. */
+export interface PointerUpAction {
+  type: "pointerUp";
+  button: PointerButton;
+}
+
+/** Simulates pressing a pointer button down. */
+export interface PointerDownAction {
+  type: "pointerDown";
+  button: PointerButton;
+}
+
+/** Simulates moving a pointer to a new position. */
+export interface PointerMoveAction extends PointerCommonProperties {
+  type: "pointerMove";
+  x: number;
+  y: number;
+  duration?: number;
+  origin?: Origin;
+}
+
+/** Physical properties common to all pointer actions (pressure, tilt, etc.). */
+export interface PointerCommonProperties {
+  width?: number;
+  height?: number;
+  /** Normalized pressure of the pointer; 0.0..1.0 */
+  pressure?: number;
+  /** Tangential (barrel) pressure; -1.0..1.0 */
+  tangentialPressure?: number;
+  /** Clockwise rotation of the pointer around its major axis; 0..359 */
+  twist?: number;
+  /** Angle between the pointer and the device surface; 0 .. Math.PI / 2 */
+  altitudeAngle?: number;
+  /** Clockwise angle of the pointer projection on the XY plane; 0 .. 2 * Math.PI */
+  azimuthAngle?: number;
+}
+
+/** Simulates a wheel scroll at a given position. */
+export interface WheelScrollAction extends PointerCommonProperties {
+  type: "scroll";
+  x: number;
+  y: number;
+  deltaX: number;
+  deltaY: number;
+  duration?: number | undefined;
+  origin: Origin;
+}
+
+/** An origin defined by a specific DOM element's position. */
+export interface ElementOrigin {
+  type: "element";
+  element: SharedReference;
+}
+
+/** The reference point for pointer/wheel coordinates — viewport, current pointer position, or a specific element. */
+export type Origin = "viewport" | "pointer" | ElementOrigin;
+
+/** Events emitted by the input module, keyed by method name. */
+export interface InputEvents {
+  "input.fileDialogOpened": { params: FileDialogInfo };
+}
+
+/** Union of all events emitted by the input module. */
+export type InputEvent = FileDialogOpened;
+
+/** Parameters for the `input.fileDialogOpened` event. */
+export interface FileDialogInfo {
+  context: BrowsingContext;
+  userContext?: UserContext;
+  /** The file input element that triggered the dialog, if any. */
+  element?: SharedReference;
+  /** Whether the dialog allows selecting multiple files. */
+  multiple: boolean;
+}
+
+/** Emitted when a file picker dialog is opened. */
+export interface FileDialogOpened {
+  method: "input.fileDialogOpened";
+  params: FileDialogInfo;
+}
+
+export type InputResult =
+  | PerformActionResult
+  | ReleaseActionResult
+  | SetFilesResult;
+
+export type PerformActionResult = EmptyResult;
+export type ReleaseActionResult = EmptyResult;
+export type SetFilesResult = EmptyResult;

package/src/types/bidi-modules/log.d.ts

@@ -0,0 +1,49 @@
+import type { RemoteValue, Source, StackTrace } from "./script.js";
+
+/** The severity level of a log entry. */
+export type Level = "debug" | "info" | "warn" | "error";
+
+/** A log entry — either a generic, console, or JavaScript error entry. */
+export type Entry = GenericLogEntry | ConsoleLogEntry | JavascriptLogEntry;
+
+/** Common fields shared by all log entry types. */
+export interface BaseLogEntry {
+  level: Level;
+  source: Source;
+  /** Human-readable text representation of the log entry. */
+  text: string | null;
+  timestamp: number;
+  stackTrace?: StackTrace;
+}
+
+/** A log entry of an unrecognized or custom type. */
+export interface GenericLogEntry extends BaseLogEntry {
+  type: string;
+}
+
+/** A log entry produced by a `console.*` method call. */
+export interface ConsoleLogEntry extends BaseLogEntry {
+  type: "console";
+  /** The console method that produced this entry (e.g. `log`, `warn`, `error`). */
+  method: string;
+  args: RemoteValue[];
+}
+
+/** A log entry produced by an uncaught JavaScript error. */
+export interface JavascriptLogEntry extends BaseLogEntry {
+  type: "javascript";
+}
+
+/** Events emitted by the log module, keyed by method name. */
+export interface LogEvents {
+  "log.entryAdded": { params: Entry };
+}
+
+/** Union of all events emitted by the log module. */
+export type LogEvent = EntryAdded;
+
+/** Emitted when a new log entry is added (e.g. a console message or JS error). */
+export interface EntryAdded {
+  method: "log.entryAdded";
+  params: Entry;
+}