@wenathlan/saddle 2.0.150 → 2.0.152

package/dist/browser.d.ts

@@ -0,0 +1,561 @@
+/**
+ * browser.ts — browser, virtual-browser and browser-extension contracts.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (browser, extension) into the single
+ * root-level domain file of the saddle family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (browser/index.ts, extension/index.ts) folded their surface into this file directly.
+ */
+export declare function fingerprintprofile(name?: string, overrides?: {}): any;
+export declare function fingerprintvalidate(profile: any): boolean;
+export declare function fingerprintfor(sessionid: any, options?: {}): any;
+/**
+ * browser sessions bind one fingerprint to one proxy and one event recorder.
+ */
+export declare function browsersession(options?: {}): {
+    id: any;
+    fingerprint: any;
+    proxy: any;
+    record(event: any): any;
+    events(): any[];
+    manifest(): {
+        id: any;
+        fingerprint: any;
+        proxy: any;
+        eventcount: number;
+    };
+};
+/**
+ * browser actions normalize adapter outcomes and preserve failure metadata for agents and replay.
+ */
+export declare const browseractions: readonly string[];
+/** Creates a stable action result independent of the underlying browser vendor. */
+export declare function actionresult(action: any, options?: {}): {
+    version: number;
+    action: any;
+    ok: boolean;
+    startedat: number;
+    finishedat: number;
+    tabid: string;
+    frameid: string;
+    snapshotid: any;
+    value: any;
+    metadata: any;
+};
+/** Creates a stable action failure without leaking adapter internals or credentials. */
+export declare function actionfailure(action: any, error: any, options?: {}): {
+    version: number;
+    action: string;
+    ok: boolean;
+    code: string;
+    message: string;
+    retryable: boolean;
+    tabid: string;
+    frameid: string;
+    snapshotid: any;
+    metadata: any;
+};
+/** Executes a bounded list of actions through an injected adapter and keeps per-action outcomes. */
+export declare function actionbatch(adapter: any, actions?: any[], options?: {}): Promise<any[]>;
+/**
+ * browser context tracks tabs and frames without owning a browser implementation.
+ */
+/** Creates a serializable browser context registry for an injected browser adapter. */
+export declare function browsercontext(options?: {}): {
+    sessionid: string;
+    opentab: (input?: {}) => {
+        id: any;
+        url: any;
+        title: any;
+        active: any;
+        frames: any[];
+    };
+    closetab: (id: any) => boolean;
+    setactive: (id: any) => {
+        id: any;
+        url: any;
+        title: any;
+        active: any;
+        frames: any[];
+    };
+    openframe: (tabid: any, input?: {}) => any;
+    closeframe: (tabid: any, frameid: any) => boolean;
+    activetab: () => {
+        id: any;
+        url: any;
+        title: any;
+        active: any;
+        frames: any[];
+    };
+    describe: () => {
+        sessionid: string;
+        activeid: string;
+        tabs: {
+            id: any;
+            url: any;
+            title: any;
+            active: any;
+            frames: any[];
+        }[];
+    };
+};
+/**
+ * browser snapshots turn page state into bounded serializable data with stable references.
+ */
+/** Creates a validated page snapshot for browser, MCP and extension adapters. */
+export declare function pagesnapshot(input?: {}): {
+    version: number;
+    snapshotid: string;
+    tabid: string;
+    frameid: string;
+    url: string;
+    title: string;
+    text: string;
+    elements: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+};
+/** Creates an element reference bound to a snapshot and browser context. */
+export declare function snapshotref(snapshot: any, input?: {}): {
+    version: number;
+    snapshotid: string;
+    tabid: string;
+    frameid: string;
+    ref: string;
+};
+/** Throws a stable error when an action uses a reference from a previous page state. */
+export declare function assertfreshsnapshot(snapshot: any, reference: any): boolean;
+/** Computes additions, removals and changed labels between two page snapshots (the page-side diff of the former browser/snapshot.ts; the extension-protocol diff of the same name lives in the protocol section below). */
+export declare function pagesnapshotdiff(previous: any, current: any): {
+    from: string;
+    to: string;
+    added: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+    removed: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+    changed: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+};
+/** Projects a page snapshot into a byte-bounded, allowlisted browser context. */
+export declare function projectcontext(snapshot: any, options?: {}): {
+    version: number;
+    snapshotid: string;
+    context: {
+        snapshotid: string;
+    };
+    fields: string[];
+    bytes: number;
+    maxbytes: number;
+    truncated: any[];
+};
+/**
+ * browser recorder captures action and snapshot boundaries for deterministic replay.
+ * The optional event limit keeps long sessions bounded without owning persistence.
+ */
+/** Creates a recorder that links actions to snapshots and optionally bounds events. */
+export declare function actionrecorder(options?: {}): {
+    snapshot: (value: any) => any;
+    action: (input?: {}) => any;
+    list: () => any[];
+    manifest: () => {
+        version: number;
+        startedat: number;
+        eventcount: number;
+        dropped: number;
+        lastsnapshotid: any;
+        events: any[];
+    };
+    exportjson: () => string;
+    clear: () => void;
+};
+/**
+ * browser agent delegates browser actions to an injected runtime adapter.
+ */
+export declare function browseragent(adapter: any): {
+    navigate: (options: any) => any;
+    click: (target: any) => any;
+    type: (value: any) => any;
+    screenshot: (options: any) => any;
+    html: () => any;
+    text: () => any;
+    title: () => any;
+    scrolltobottom: (options: any) => any;
+    executecommands: (commands: any) => any;
+    fill: (...args: any[]) => any;
+    key: (...args: any[]) => any;
+    upload: (...args: any[]) => any;
+    snapshot: (...args: any[]) => any;
+    tabs: (...args: any[]) => any;
+    frames: (...args: any[]) => any;
+};
+/** Creates a data-only request for a remote, adapter-owned browser session. */
+export declare function virtualbrowserrequest(input?: {}): Readonly<{
+    version: 1;
+    state: "requested";
+    id: string;
+    engine: string;
+    distribution: string;
+    display: string;
+    storage: string;
+    execution: Readonly<{
+        version: 1;
+        id: string;
+        effect: string;
+        target: string;
+        source: string;
+        budget: Readonly<{
+            maxbytes: number;
+            maxmilliseconds: number;
+            network: boolean;
+        }>;
+        state: "requested";
+    }>;
+    localaccess: Readonly<{
+        browser: false;
+        filesystem: false;
+        storage: false;
+        process: false;
+    }>;
+    effects: readonly any[];
+}>;
+/** Evaluates a virtual browser request without contacting a runtime or provider. */
+export declare function virtualbrowserdecision(input: any, configuration?: {}): Readonly<{
+    version: 1;
+    request: Readonly<{
+        version: 1;
+        state: "requested";
+        id: string;
+        engine: string;
+        distribution: string;
+        display: string;
+        storage: string;
+        execution: Readonly<{
+            version: 1;
+            id: string;
+            effect: string;
+            target: string;
+            source: string;
+            budget: Readonly<{
+                maxbytes: number;
+                maxmilliseconds: number;
+                network: boolean;
+            }>;
+            state: "requested";
+        }>;
+        localaccess: Readonly<{
+            browser: false;
+            filesystem: false;
+            storage: false;
+            process: false;
+        }>;
+        effects: readonly any[];
+    }>;
+    state: "caller-delegates" | "denied";
+    reasons: readonly any[];
+    adapter: Readonly<{
+        owner: string;
+        engines: readonly string[];
+        distributions: readonly string[];
+    }>;
+    effects: readonly any[];
+}>;
+/** Projects an adapter handoff without launching a browser or transferring user state. */
+export declare function virtualbrowserhandoff(input?: {}): Readonly<{
+    version: 1;
+    state: "browser-disabled";
+    code: "VIRTUAL_BROWSER_POLICY_DENIED";
+    decision: Readonly<{
+        version: 1;
+        request: Readonly<{
+            version: 1;
+            state: "requested";
+            id: string;
+            engine: string;
+            distribution: string;
+            display: string;
+            storage: string;
+            execution: Readonly<{
+                version: 1;
+                id: string;
+                effect: string;
+                target: string;
+                source: string;
+                budget: Readonly<{
+                    maxbytes: number;
+                    maxmilliseconds: number;
+                    network: boolean;
+                }>;
+                state: "requested";
+            }>;
+            localaccess: Readonly<{
+                browser: false;
+                filesystem: false;
+                storage: false;
+                process: false;
+            }>;
+            effects: readonly any[];
+        }>;
+        state: "caller-delegates" | "denied";
+        reasons: readonly any[];
+        adapter: Readonly<{
+            owner: string;
+            engines: readonly string[];
+            distributions: readonly string[];
+        }>;
+        effects: readonly any[];
+    }>;
+    effects: readonly any[];
+}> | Readonly<{
+    version: 1;
+    state: "caller-delegates";
+    code: "REMOTE_BROWSER_ADAPTER_REQUIRED";
+    decision: Readonly<{
+        version: 1;
+        request: Readonly<{
+            version: 1;
+            state: "requested";
+            id: string;
+            engine: string;
+            distribution: string;
+            display: string;
+            storage: string;
+            execution: Readonly<{
+                version: 1;
+                id: string;
+                effect: string;
+                target: string;
+                source: string;
+                budget: Readonly<{
+                    maxbytes: number;
+                    maxmilliseconds: number;
+                    network: boolean;
+                }>;
+                state: "requested";
+            }>;
+            localaccess: Readonly<{
+                browser: false;
+                filesystem: false;
+                storage: false;
+                process: false;
+            }>;
+            effects: readonly any[];
+        }>;
+        state: "caller-delegates" | "denied";
+        reasons: readonly any[];
+        adapter: Readonly<{
+            owner: string;
+            engines: readonly string[];
+            distributions: readonly string[];
+        }>;
+        effects: readonly any[];
+    }>;
+    effects: readonly any[];
+}>;
+/** Records declared or observed remote-browser capabilities without asserting isolation or trust. */
+export declare function virtualbrowserreceipt(input?: {}): Readonly<{
+    version: 1;
+    state: string;
+    request: Readonly<{
+        version: 1;
+        state: "requested";
+        id: string;
+        engine: string;
+        distribution: string;
+        display: string;
+        storage: string;
+        execution: Readonly<{
+            version: 1;
+            id: string;
+            effect: string;
+            target: string;
+            source: string;
+            budget: Readonly<{
+                maxbytes: number;
+                maxmilliseconds: number;
+                network: boolean;
+            }>;
+            state: "requested";
+        }>;
+        localaccess: Readonly<{
+            browser: false;
+            filesystem: false;
+            storage: false;
+            process: false;
+        }>;
+        effects: readonly any[];
+    }>;
+    adapterid: string;
+    image: string;
+    capabilities: readonly string[];
+    effects: readonly any[];
+}>;
+/**
+ * browser playwright adapter keeps the optional Node browser provider outside the transport-neutral surface.
+ */
+/** Creates a caller-owned Playwright browser session when the optional peer is installed. */
+export declare function createplaywrightsession(options?: {}): Promise<{
+    browser: any;
+    context: any;
+    page: any;
+    close: () => any;
+}>;
+/**
+ * extension permission policies keep the browser capability boundary explicit and caller-owned.
+ */
+export declare const extensionpermissions: readonly string[];
+/** Creates a minimal permission policy without requesting broad host access. */
+export declare function permissionpolicy(options?: {}): {
+    version: number;
+    requested: unknown[];
+    optional: unknown[];
+    hostpermissions: any[];
+    allows(permission: any): boolean;
+    missing(permissions?: any[]): string[];
+};
+/** Requests an optional capability through an injected browser permission function. */
+export declare function requestpermission(policy: any, permission: any, request: any): Promise<{
+    permission: string;
+    granted: boolean;
+    code?: undefined;
+    message?: undefined;
+} | {
+    permission: string;
+    granted: boolean;
+    code: string;
+    message: string;
+}>;
+/**
+ * extension protocol defines serializable commands, responses, errors and page snapshots.
+ */
+export declare const protocolversion = 1;
+export declare const extensioncommands: readonly string[];
+/** Creates a compact identifier without embedding a host, port or credential. */
+export declare function createid(prefix: string, source: any): string;
+/** Creates a versioned command for the extension message bus. */
+export declare function createcommand(command: any, payload?: {}, options?: {}): {
+    version: number;
+    type: any;
+    id: any;
+};
+/** Creates a serializable message envelope. */
+export declare function createmessage(type: any, options?: {}): {
+    version: number;
+    type: any;
+    id: any;
+};
+/** Creates a correlated successful response. */
+export declare function createresponse(request: any, payload?: {}): {
+    version: number;
+    type: any;
+    id: any;
+};
+/** Creates a correlated error response with stable error fields. */
+export declare function createerror(request: any, error: any, options?: {}): {
+    version: number;
+    type: any;
+    id: any;
+};
+/** Validates a message before a privileged context handles it. */
+export declare function assertmessage(message: any): any;
+/** Creates a structured page snapshot with stable element references. */
+export declare function createsnapshot(input?: {}): {
+    version: number;
+    snapshotid: string;
+    createdat: number;
+    windowid: string;
+    tabid: string;
+    frameid: string;
+    url: string;
+    title: string;
+    text: string;
+    elements: any;
+};
+/** Returns whether a reference still belongs to the current page snapshot. */
+export declare function isfreshsnapshot(snapshotid: any, currentid: any): boolean;
+/** Computes bounded additions, removals and changed elements between extension snapshots. */
+export declare function snapshotdiff(previous: any, current: any): {
+    from: string;
+    to: string;
+    contextchanged: boolean;
+    added: any;
+    removed: any;
+    changed: any;
+};
+/**
+ * worker binds the generic extension router to the Manifest V3 runtime APIs.
+ */
+/** Installs the service worker listeners against a caller supplied Chrome API object. */
+export declare function startworker(chromeapi?: any): {
+    router: {
+        ensurecontent: (tabid: any) => Promise<void>;
+        readstate: () => Promise<any>;
+        savestate: (value: any) => Promise<void>;
+        rehydrate: () => Promise<any>;
+        enqueue: (request: any, sender: any) => Promise<{
+            requestid: any;
+            command: any;
+            message: any;
+            tabid: any;
+            frameid: any;
+            windowid: any;
+            attempts: number;
+            createdat: number;
+            updatedat: number;
+        }>;
+        resume: (requestid: any, sender?: {}) => Promise<any>;
+        cancel: (requestid: any) => Promise<void>;
+        handle: (message: any, sender?: {}) => Promise<any>;
+    };
+    dispose(): void;
+};
+/**
+ * service worker router forwards user initiated commands to the active tab and persists resumable state.
+ */
+/** Creates a browser independent router around Chrome tabs, scripting and storage APIs. */
+export declare function createworkerrouter(options?: {}): {
+    ensurecontent: (tabid: any) => Promise<void>;
+    readstate: () => Promise<any>;
+    savestate: (value: any) => Promise<void>;
+    rehydrate: () => Promise<any>;
+    enqueue: (request: any, sender: any) => Promise<{
+        requestid: any;
+        command: any;
+        message: any;
+        tabid: any;
+        frameid: any;
+        windowid: any;
+        attempts: number;
+        createdat: number;
+        updatedat: number;
+    }>;
+    resume: (requestid: any, sender?: {}) => Promise<any>;
+    cancel: (requestid: any) => Promise<void>;
+    handle: (message: any, sender?: {}) => Promise<any>;
+};
+/** Builds the extension into an isolated directory and returns its manifest. */
+export declare function buildextension(options?: {}): Promise<{
+    output: string;
+    manifest: any;
+}>;