@ohos-ports/vibium 26.5.31-beta.0

package/dist/sync.d.mts

@@ -0,0 +1,613 @@
+/**
+ * Signal protocol (2-slot SharedArrayBuffer):
+ *   signal[0]: worker → main  (0=idle, 1=result ready, 2=callback needed)
+ *   signal[1]: main → worker  (0=idle, 1=callback response ready)
+ */
+declare class SyncBridge {
+    private worker;
+    private signal;
+    private commandId;
+    private terminated;
+    private callbackPortMain;
+    private callbackPortWorker;
+    private handlers;
+    private constructor();
+    static create(): SyncBridge;
+    /** Register a callback handler that can be invoked from the worker thread. */
+    registerHandler(id: string, handler: Function): void;
+    /** Remove a previously registered callback handler. */
+    unregisterHandler(id: string): void;
+    /** Process any pending callbacks that fired between bridge calls. */
+    private processPendingCallbacks;
+    /** Handle a single callback request from the worker. */
+    private handleCallback;
+    call<T = unknown>(method: string, args?: unknown[]): T;
+    tryQuit(): void;
+    terminate(): void;
+}
+
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ElementInfo {
+    tag: string;
+    text: string;
+    box: BoundingBox;
+}
+interface ActionOptions {
+    /** Timeout in milliseconds for actionability checks. Default: 30000 */
+    timeout?: number;
+}
+interface SelectorOptions {
+    role?: string;
+    text?: string;
+    label?: string;
+    placeholder?: string;
+    alt?: string;
+    title?: string;
+    testid?: string;
+    xpath?: string;
+    near?: string;
+    timeout?: number;
+}
+
+declare const customInspect$2: unique symbol;
+declare class ElementSync {
+    private bridge;
+    private elementId;
+    readonly info: ElementInfo;
+    constructor(bridge: SyncBridge, elementId: number, info: ElementInfo);
+    [customInspect$2](): string;
+    /**
+     * Click the element.
+     * Waits for element to be visible, stable, receive events, and enabled.
+     */
+    click(options?: ActionOptions): void;
+    /** Double-click the element. */
+    dblclick(options?: ActionOptions): void;
+    /**
+     * Fill the element with text (clears existing content first).
+     * For inputs and textareas.
+     */
+    fill(value: string, options?: ActionOptions): void;
+    /**
+     * Type text into the element.
+     * Waits for element to be visible, stable, receive events, enabled, and editable.
+     */
+    type(text: string, options?: ActionOptions): void;
+    /**
+     * Press a key while the element is focused.
+     * Supports key names ("Enter", "Tab") and combos ("Control+a").
+     */
+    press(key: string, options?: ActionOptions): void;
+    /** Clear the element's content (select all + delete). */
+    clear(options?: ActionOptions): void;
+    /** Check a checkbox (no-op if already checked). */
+    check(options?: ActionOptions): void;
+    /** Uncheck a checkbox (no-op if already unchecked). */
+    uncheck(options?: ActionOptions): void;
+    /** Select an option in a <select> element by value. */
+    selectOption(value: string, options?: ActionOptions): void;
+    /** Hover over the element (move mouse to center, no click). */
+    hover(options?: ActionOptions): void;
+    /** Focus the element. */
+    focus(options?: ActionOptions): void;
+    /** Drag this element to a target element. */
+    dragTo(target: ElementSync, options?: ActionOptions): void;
+    /** Tap the element (touch action). */
+    tap(options?: ActionOptions): void;
+    /** Scroll the element into view. */
+    scrollIntoView(options?: ActionOptions): void;
+    /** Dispatch a DOM event on the element. */
+    dispatchEvent(eventType: string, eventInit?: Record<string, unknown>, options?: ActionOptions): void;
+    text(): string;
+    innerText(): string;
+    html(): string;
+    value(): string;
+    attr(name: string): string | null;
+    getAttribute(name: string): string | null;
+    bounds(): BoundingBox;
+    boundingBox(): BoundingBox;
+    isVisible(): boolean;
+    isHidden(): boolean;
+    isEnabled(): boolean;
+    isChecked(): boolean;
+    isEditable(): boolean;
+    screenshot(): Buffer;
+    waitUntil(state?: string, options?: {
+        timeout?: number;
+    }): void;
+    setFiles(files: string[], options?: ActionOptions): void;
+    role(): string;
+    label(): string;
+    find(selector: string | SelectorOptions, options?: {
+        timeout?: number;
+    }): ElementSync;
+    findAll(selector: string | SelectorOptions, options?: {
+        timeout?: number;
+    }): ElementSync[];
+}
+
+declare class KeyboardSync {
+    private bridge;
+    private pageId;
+    constructor(bridge: SyncBridge, pageId: number);
+    press(key: string): void;
+    down(key: string): void;
+    up(key: string): void;
+    type(text: string): void;
+}
+declare class MouseSync {
+    private bridge;
+    private pageId;
+    constructor(bridge: SyncBridge, pageId: number);
+    click(x: number, y: number): void;
+    move(x: number, y: number): void;
+    down(): void;
+    up(): void;
+    wheel(deltaX: number, deltaY: number): void;
+}
+declare class TouchSync {
+    private bridge;
+    private pageId;
+    constructor(bridge: SyncBridge, pageId: number);
+    tap(x: number, y: number): void;
+}
+
+interface ClockInstallOptions {
+    time?: number | string | Date;
+    timezone?: string;
+}
+declare class ClockSync {
+    private bridge;
+    private pageId;
+    constructor(bridge: SyncBridge, pageId: number);
+    install(options?: ClockInstallOptions): void;
+    fastForward(ticks: number): void;
+    runFor(ticks: number): void;
+    pauseAt(time: number | string | Date): void;
+    resume(): void;
+    setFixedTime(time: number | string | Date): void;
+    setSystemTime(time: number | string | Date): void;
+    setTimezone(timezone: string): void;
+}
+
+interface RecordingStartOptions {
+    name?: string;
+    screenshots?: boolean;
+    snapshots?: boolean;
+    sources?: boolean;
+    title?: string;
+    bidi?: boolean;
+    /** Screenshot format: 'jpeg' (default, faster/smaller) or 'png' (lossless). */
+    format?: 'jpeg' | 'png';
+    /** JPEG quality 0.0-1.0 (default 0.5). Ignored for PNG. */
+    quality?: number;
+}
+interface RecordingStopOptions {
+    path?: string;
+}
+
+declare class RecordingSync {
+    private bridge;
+    private contextId;
+    constructor(bridge: SyncBridge, contextId: number);
+    start(options?: RecordingStartOptions): void;
+    stop(options?: RecordingStopOptions): Buffer;
+    startChunk(options?: {
+        name?: string;
+        title?: string;
+    }): void;
+    stopChunk(options?: RecordingStopOptions): Buffer;
+    startGroup(name: string, options?: {
+        location?: {
+            file: string;
+            line?: number;
+            column?: number;
+        };
+    }): void;
+    stopGroup(): void;
+}
+
+interface FindOptions {
+    /** Timeout in milliseconds to wait for element. Default: 30000 */
+    timeout?: number;
+}
+interface ScreenshotOptions {
+    /** Capture full scrollable page instead of just the viewport. */
+    fullPage?: boolean;
+    /** Capture a specific region of the page. */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+interface A11yNode {
+    role: string;
+    name?: string;
+    value?: string | number;
+    description?: string;
+    disabled?: boolean;
+    expanded?: boolean;
+    focused?: boolean;
+    checked?: boolean | 'mixed';
+    pressed?: boolean | 'mixed';
+    selected?: boolean;
+    required?: boolean;
+    readonly?: boolean;
+    level?: number;
+    valuemin?: number;
+    valuemax?: number;
+    children?: A11yNode[];
+}
+
+interface Cookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    size: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: string;
+    expiry?: number;
+}
+interface SetCookieParam {
+    name: string;
+    value: string;
+    domain?: string;
+    url?: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+    expiry?: number;
+}
+interface OriginState {
+    origin: string;
+    localStorage: {
+        name: string;
+        value: string;
+    }[];
+    sessionStorage: {
+        name: string;
+        value: string;
+    }[];
+}
+interface StorageState {
+    cookies: Cookie[];
+    origins: OriginState[];
+}
+
+declare class BrowserContextSync {
+    private bridge;
+    private contextId;
+    readonly recording: RecordingSync;
+    constructor(bridge: SyncBridge, contextId: number);
+    newPage(): PageSync;
+    close(): void;
+    cookies(urls?: string[]): Cookie[];
+    setCookies(cookies: SetCookieParam[]): void;
+    clearCookies(): void;
+    storage(): StorageState;
+    setStorage(state: StorageState): void;
+    clearStorage(): void;
+    addInitScript(script: string): string;
+}
+
+/** Sync route handler data — plain object representing the intercepted request. */
+interface RouteRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    postData: string | null;
+}
+/** Decision returned by a sync route handler. */
+interface RouteDecision {
+    action: 'fulfill' | 'continue' | 'abort';
+    status?: number;
+    headers?: Record<string, string>;
+    contentType?: string;
+    body?: string;
+    url?: string;
+    method?: string;
+    postData?: string;
+}
+/**
+ * Sync wrapper for an intercepted network request.
+ * The user's handler calls fulfill(), continue(), or abort() to set the decision.
+ * If none is called, the default is 'continue'.
+ */
+declare class RouteSync {
+    readonly request: RouteRequest;
+    /** @internal */
+    _decision: RouteDecision;
+    constructor(request: RouteRequest);
+    /** Fulfill the request with a custom response. */
+    fulfill(response?: {
+        status?: number;
+        headers?: Record<string, string>;
+        contentType?: string;
+        body?: string;
+    }): void;
+    /** Continue the request, optionally with overrides. */
+    continue(overrides?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+        postData?: string;
+    }): void;
+    /** Abort the request. */
+    abort(): void;
+}
+
+/** Serialized dialog data sent from worker to main thread. */
+interface DialogData {
+    type: string;
+    message: string;
+    defaultValue: string;
+}
+/** Decision returned by a sync dialog handler. */
+interface DialogDecision {
+    action: 'accept' | 'dismiss';
+    promptText?: string;
+}
+/**
+ * Sync wrapper for a browser dialog (alert, confirm, prompt, beforeunload).
+ * The user's handler calls accept() or dismiss() to set the decision.
+ * If none is called, the default is 'dismiss'.
+ */
+declare class DialogSync {
+    private data;
+    /** @internal */
+    _decision: DialogDecision;
+    constructor(data: DialogData);
+    /** The dialog type: 'alert', 'confirm', 'prompt', or 'beforeunload'. */
+    type(): string;
+    /** The dialog message text. */
+    message(): string;
+    /** The default value for prompt dialogs. */
+    defaultValue(): string;
+    /** Accept the dialog. For prompt dialogs, optionally provide text. */
+    accept(promptText?: string): void;
+    /** Dismiss the dialog (cancel/close). */
+    dismiss(): void;
+}
+
+declare const customInspect$1: unique symbol;
+interface RequestData {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    postData: string | null;
+}
+interface ResponseData {
+    url: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string | null;
+}
+declare class DownloadData {
+    readonly url: string;
+    readonly suggestedFilename: string;
+    readonly path: string | null;
+    constructor(data: {
+        url: string;
+        suggestedFilename: string;
+        path: string | null;
+    });
+    /** Save the downloaded file to a destination path. */
+    saveAs(destPath: string): void;
+}
+type MessageHandler = (data: string, info: {
+    direction: 'sent' | 'received';
+}) => void;
+type CloseHandler = (code?: number, reason?: string) => void;
+declare class WebSocketInfoSync {
+    private _url;
+    private _isClosed;
+    private _messageHandlers;
+    private _closeHandlers;
+    constructor(url: string);
+    url(): string;
+    onMessage(fn: MessageHandler): void;
+    onClose(fn: CloseHandler): void;
+    isClosed(): boolean;
+    /** @internal */
+    _emitMessage(data: string, direction: 'sent' | 'received'): void;
+    /** @internal */
+    _emitClose(code?: number, reason?: string): void;
+}
+declare class PageSync {
+    /** @internal */
+    readonly _bridge: SyncBridge;
+    /** @internal */
+    readonly _pageId: number;
+    readonly keyboard: KeyboardSync;
+    readonly mouse: MouseSync;
+    readonly touch: TouchSync;
+    readonly clock: ClockSync;
+    private _nextHandlerId;
+    private _routeHandlerIds;
+    private _dialogHandlerId;
+    private _requestHandlerId;
+    private _responseHandlerId;
+    private _downloadHandlerId;
+    private _wsHandlerId;
+    private _wsInstances;
+    private _cachedContext;
+    constructor(bridge: SyncBridge, pageId: number);
+    [customInspect$1](): string;
+    /** The parent BrowserContext that owns this page. */
+    get context(): BrowserContextSync;
+    go(url: string): void;
+    back(): void;
+    forward(): void;
+    reload(): void;
+    url(): string;
+    title(): string;
+    content(): string;
+    find(selector: string | SelectorOptions, options?: FindOptions): ElementSync;
+    findAll(selector: string | SelectorOptions, options?: FindOptions): ElementSync[];
+    /** Capture namespace — set up a listener before performing an action. */
+    get capture(): {
+        response(pattern: string, fn?: () => void, options?: {
+            timeout?: number;
+        }): {
+            url: string;
+            status: number;
+            headers: Record<string, string>;
+            body: string | null;
+        };
+        request(pattern: string, fn?: () => void, options?: {
+            timeout?: number;
+        }): {
+            url: string;
+            method: string;
+            headers: Record<string, string>;
+            postData: string | null;
+        };
+        navigation(fn?: () => void, options?: {
+            timeout?: number;
+        }): {
+            url: string;
+        };
+        download(fn?: () => void, options?: {
+            timeout?: number;
+        }): DownloadData;
+        dialog(fn?: () => void, options?: {
+            timeout?: number;
+        }): {
+            type: string;
+            message: string;
+            defaultValue: string;
+        };
+        event(name: string, fn?: () => void, options?: {
+            timeout?: number;
+        }): unknown;
+    };
+    /** Wait until a condition is met. Callable with a function, or use .url() / .loaded() sub-methods. */
+    readonly waitUntil: ((fn: string, options?: {
+        timeout?: number;
+    }) => unknown) & {
+        url(pattern: string, options?: {
+            timeout?: number;
+        }): void;
+        loaded(state?: string, options?: {
+            timeout?: number;
+        }): void;
+    };
+    wait(ms: number): void;
+    screenshot(options?: ScreenshotOptions): Buffer;
+    pdf(): Buffer;
+    evaluate<T = unknown>(expression: string): T;
+    addScript(source: string): void;
+    addStyle(source: string): void;
+    expose(name: string, fn: string): void;
+    bringToFront(): void;
+    close(): void;
+    scroll(direction?: string, amount?: number, selector?: string): void;
+    setViewport(size: {
+        width: number;
+        height: number;
+    }): void;
+    viewport(): {
+        width: number;
+        height: number;
+    };
+    emulateMedia(opts: {
+        media?: 'screen' | 'print' | null;
+        colorScheme?: 'light' | 'dark' | 'no-preference' | null;
+        reducedMotion?: 'reduce' | 'no-preference' | null;
+        forcedColors?: 'active' | 'none' | null;
+        contrast?: 'more' | 'no-preference' | null;
+    }): void;
+    setContent(html: string): void;
+    setGeolocation(coords: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    }): void;
+    setWindow(options: {
+        width?: number;
+        height?: number;
+        x?: number;
+        y?: number;
+        state?: 'normal' | 'maximized' | 'minimized' | 'fullscreen';
+    }): void;
+    window(): {
+        state: string;
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    };
+    frames(): PageSync[];
+    frame(nameOrUrl: string): PageSync | null;
+    mainFrame(): PageSync;
+    a11yTree(options?: {
+        everything?: boolean;
+        root?: string;
+    }): A11yNode;
+    route(pattern: string, action: 'continue' | 'abort' | {
+        status?: number;
+        body?: string;
+        headers?: Record<string, string>;
+    } | ((route: RouteSync) => void)): void;
+    unroute(pattern: string): void;
+    setHeaders(headers: Record<string, string>): void;
+    onDialog(action: 'accept' | 'dismiss' | ((dialog: DialogSync) => void)): void;
+    onConsole(mode: 'collect'): void;
+    consoleMessages(): {
+        type: string;
+        text: string;
+    }[];
+    onError(mode: 'collect'): void;
+    errors(): {
+        message: string;
+    }[];
+    onRequest(fn: (req: RequestData) => void): void;
+    onResponse(fn: (resp: ResponseData) => void): void;
+    onDownload(fn: (dl: DownloadData) => void): void;
+    onWebSocket(fn: (ws: WebSocketInfoSync) => void): void;
+    removeAllListeners(event?: 'request' | 'response' | 'dialog' | 'console' | 'error' | 'download' | 'websocket'): void;
+}
+
+declare const customInspect: unique symbol;
+interface StartOptions {
+    headless?: boolean;
+    headers?: Record<string, string>;
+}
+declare class BrowserSync {
+    /** @internal */
+    readonly _bridge: SyncBridge;
+    private _nextHandlerId;
+    private _pageHandlerId?;
+    private _popupHandlerId?;
+    constructor(bridge: SyncBridge);
+    [customInspect](): string;
+    page(): PageSync;
+    newPage(): PageSync;
+    pages(): PageSync[];
+    newContext(): BrowserContextSync;
+    waitForPage(options?: {
+        timeout?: number;
+    }): PageSync;
+    waitForPopup(options?: {
+        timeout?: number;
+    }): PageSync;
+    onPage(callback: (page: PageSync) => void): void;
+    onPopup(callback: (page: PageSync) => void): void;
+    removeAllListeners(event?: 'page' | 'popup'): void;
+    stop(): void;
+}
+declare const browser: {
+    start(urlOrOptions?: string | StartOptions, options?: StartOptions): BrowserSync;
+};
+
+export { BrowserContextSync, BrowserSync, ClockSync, DialogSync, DownloadData, ElementSync, KeyboardSync, MouseSync, PageSync, RecordingSync, type RequestData, type ResponseData, RouteSync, type StartOptions, TouchSync, WebSocketInfoSync, browser };