@wenathlan/saddle 2.0.154 → 2.0.159

package/dist/browser.d.ts

@@ -1,561 +0,0 @@
-/**
- * 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;
-}>;