@mearl/browser-core 3.0.0-beta.5 → 3.0.0-beta.7

package/dist/pageAct.js

@@ -209,7 +209,21 @@ export async function runPageAct(input, dependencies) {
         throw new Error('actionData must be an object');
     }
     const typedAction = action;
-    const checkpoint = await dependencies.startObservation();
+    const dialogs = dependencies.dialogs;
+    const guarded = (work) => dialogs ? dialogs.command(work) : work();
+    const dialogResult = (failure, data) => ({
+        action: { name: typedAction, success: !failure, ...(data !== undefined ? { data } : {}), ...failure },
+        ...(dialogs?.info() ? { dialog: dialogs.info() } : {}),
+    });
+    let checkpoint;
+    try {
+        checkpoint = await guarded(() => dependencies.startObservation());
+    }
+    catch (error) {
+        if (!dialogs?.pending)
+            throw error;
+        return dialogResult({ ...describePageActionFailure(error), stage: 'precondition' });
+    }
     const navigationOptions = resolveNavigationWaitOptions(observe);
     const sourceTabId = typeof actionData.tabId === 'number' && Number.isInteger(actionData.tabId)
         ? actionData.tabId
@@ -232,6 +246,14 @@ export async function runPageAct(input, dependencies) {
     catch (error) {
         actionFailure = describePageActionFailure(error);
     }
+    const dispose = () => Promise.allSettled([
+        Promise.resolve().then(() => navigationObserver?.dispose()),
+        Promise.resolve().then(() => dependencies.disposeObservation?.()),
+    ]);
+    if (dialogs?.pending) {
+        await dispose();
+        return dialogResult(actionFailure, actionResult);
+    }
     if (actionFailure?.stage === 'precondition') {
         await Promise.allSettled([
             Promise.resolve().then(() => navigationObserver?.dispose()),
@@ -248,11 +270,15 @@ export async function runPageAct(input, dependencies) {
     }
     let observation;
     try {
-        observation = await dependencies.finishObservation(checkpoint, observe);
+        observation = await guarded(() => dependencies.finishObservation(checkpoint, observe));
     }
     catch (error) {
         observation = unavailableObservation(checkpoint, error);
     }
+    if (dialogs?.pending) {
+        await dispose();
+        return dialogResult(actionFailure, actionResult);
+    }
     const navigationInterruptedAction = isNavigationInterruptedActionFailure(actionFailure);
     if (navigationInterruptedAction && observation.mode === 'navigation') {
         actionFailure = undefined;
@@ -277,22 +303,22 @@ export async function runPageAct(input, dependencies) {
             (navigationObserver.hasStarted() ||
                 shouldWaitForPotentialNavigation(typedAction, observation))) {
             const didNavigate = navigationObserver.hasStarted() ||
-                (await navigationObserver.waitForStart(navigationOptions.graceMs));
+                (await guarded(() => navigationObserver.waitForStart(navigationOptions.graceMs)));
             if (didNavigate) {
-                observation = await navigationObserver.waitForResult(navigationOptions.timeoutMs);
+                observation = await guarded(() => navigationObserver.waitForResult(navigationOptions.timeoutMs));
             }
         }
         if (navigationObserver &&
             (actionFailure === undefined || navigationInterruptedAction) &&
             observation.mode !== 'navigation' &&
             navigationObserver.hasNetworkActivity()) {
-            const network = await navigationObserver.waitForNetworkIdle(navigationOptions.timeoutMs);
+            const network = await guarded(() => navigationObserver.waitForNetworkIdle(navigationOptions.timeoutMs));
             if (navigationObserver.hasStarted()) {
-                observation = await navigationObserver.waitForResult(navigationOptions.timeoutMs);
+                observation = await guarded(() => navigationObserver.waitForResult(navigationOptions.timeoutMs));
             }
             else {
                 try {
-                    observation = await dependencies.finishObservation(checkpoint, observe);
+                    observation = await guarded(() => dependencies.finishObservation(checkpoint, observe));
                 }
                 catch (error) {
                     observation = unavailableObservation(checkpoint, error);
@@ -309,7 +335,7 @@ export async function runPageAct(input, dependencies) {
         }
         if (dependencies.finalizeObservation) {
             try {
-                observation = await dependencies.finalizeObservation(observation);
+                observation = await guarded(() => dependencies.finalizeObservation(observation));
             }
             catch {
                 // Ref enrichment and other response finalizers are best-effort and must
@@ -317,19 +343,25 @@ export async function runPageAct(input, dependencies) {
             }
         }
         if (navigationObserver) {
-            const openedTabs = await navigationObserver
-                .getOpenedTabs(navigationOptions.timeoutMs)
+            const openedTabs = await guarded(() => navigationObserver.getOpenedTabs(navigationOptions.timeoutMs))
                 .catch(() => []);
             if (openedTabs.length > 0)
                 observation = { ...observation, openedTabs };
         }
     }
+    catch (error) {
+        if (!dialogs?.pending)
+            throw error;
+        return dialogResult(actionFailure, actionResult);
+    }
     finally {
         await Promise.allSettled([
             Promise.resolve().then(() => navigationObserver?.dispose()),
             Promise.resolve().then(() => dependencies.disposeObservation?.()),
         ]);
     }
+    if (dialogs?.pending)
+        return dialogResult(actionFailure, actionResult);
     return {
         action: {
             name: typedAction,

package/dist/pageDialog.d.ts

@@ -0,0 +1,66 @@
+export interface PageDialogInfo {
+    id: string;
+    type: 'alert' | 'confirm' | 'prompt' | 'beforeunload';
+    message: string;
+    defaultPrompt?: string;
+    truncated?: true;
+}
+export declare class PageDialogInterruptedError extends Error {
+    readonly pageActionFailureStage: 'precondition' | 'dispatch-uncertain';
+    readonly code = "DIALOG_PENDING";
+    readonly dialog?: PageDialogInfo;
+    readonly details: {
+        dialog?: PageDialogInfo;
+    };
+    constructor(dialog?: PageDialogInfo, pageActionFailureStage?: 'precondition' | 'dispatch-uncertain');
+}
+/** Host-side state only: no page injection, implicit acceptance, or action replay. */
+export declare class PageDialogState {
+    private epoch;
+    private readonly prefix;
+    private current?;
+    private defaultPromptTruncated;
+    private readonly work;
+    private readonly listeners;
+    private handling?;
+    onIdle?: () => void;
+    get pending(): boolean;
+    get busy(): boolean;
+    info(maxChars?: number): PageDialogInfo | undefined;
+    opened(event: {
+        type?: unknown;
+        message?: unknown;
+        defaultPrompt?: unknown;
+    }): void;
+    closed(): void;
+    invalidate(): void;
+    assertCanDispatch(): void;
+    /** Register the actual handler, including its finally; never retain a raw browser Promise here. */
+    execute<T>(work: () => Promise<T>, interrupt?: boolean): Promise<T>;
+    /** Every real eval/input dispatch must pass here, so a late ack cannot resume its handler. */
+    command<T>(work: () => Promise<T>): Promise<T>;
+    private race;
+    press(input: {
+        dialogId?: string;
+        key: string;
+        promptText?: string;
+        selector?: string;
+        modifiers?: unknown[];
+        pressMode?: string;
+    }, send: (params: {
+        accept: boolean;
+        promptText?: string;
+    }) => Promise<unknown>): Promise<{
+        pressed: true;
+        key: string;
+        dispatchMode: 'native-dialog';
+    }>;
+    private notifyIdle;
+}
+export declare function pageDialogSnapshot(dialogs: PageDialogState, mode?: string, maxChars?: number): {
+    snapshot: string;
+    mode: string;
+    elementCount: number;
+    outputNodeCount: number;
+    dialog: PageDialogInfo;
+} | undefined;

package/dist/pageDialog.js

@@ -0,0 +1,175 @@
+import { PageActionDispatchUncertainError } from './pageAct.js';
+export class PageDialogInterruptedError extends Error {
+    pageActionFailureStage;
+    code = 'DIALOG_PENDING';
+    dialog;
+    details;
+    constructor(dialog, pageActionFailureStage = 'dispatch-uncertain') {
+        super(dialog
+            ? `DIALOG_PENDING: native ${dialog.type} dialog ${dialog.id}. Read it with page_snapshot, then use page_press with dialogId and Enter/Escape.`
+            : 'DIALOG_PENDING: a previous page operation was interrupted; observe the page before continuing.');
+        this.pageActionFailureStage = pageActionFailureStage;
+        this.name = 'PageDialogInterruptedError';
+        this.dialog = dialog;
+        this.details = { ...(dialog ? { dialog } : {}) };
+    }
+}
+/** Host-side state only: no page injection, implicit acceptance, or action replay. */
+export class PageDialogState {
+    epoch = 0;
+    prefix = crypto.randomUUID();
+    current;
+    defaultPromptTruncated = false;
+    work = new Set();
+    listeners = new Set();
+    handling;
+    onIdle;
+    get pending() { return this.current !== undefined; }
+    get busy() { return this.work.size > 0 || this.handling !== undefined; }
+    info(maxChars = 240) {
+        if (!this.current)
+            return undefined;
+        const limit = Number.isFinite(maxChars) ? Math.max(0, Math.min(maxChars, 100000)) : 240;
+        const { message, defaultPrompt, ...rest } = this.current;
+        return {
+            ...rest,
+            message: message.slice(0, limit),
+            ...(defaultPrompt ? { defaultPrompt: defaultPrompt.slice(0, limit) } : {}),
+            ...(message.length > limit || (defaultPrompt?.length ?? 0) > limit ? { truncated: true } : {}),
+        };
+    }
+    opened(event) {
+        if (!['alert', 'confirm', 'prompt', 'beforeunload'].includes(String(event.type)))
+            return;
+        this.defaultPromptTruncated = typeof event.defaultPrompt === 'string' && event.defaultPrompt.length > 65536;
+        this.current = {
+            id: `${this.prefix}:${++this.epoch}`,
+            type: event.type,
+            message: typeof event.message === 'string' ? event.message.slice(0, 65536) : '',
+            ...(typeof event.defaultPrompt === 'string' && event.defaultPrompt
+                ? { defaultPrompt: event.defaultPrompt.slice(0, 65536) } : {}),
+            ...((typeof event.message === 'string' && event.message.length > 65536) ||
+                (typeof event.defaultPrompt === 'string' && event.defaultPrompt.length > 65536) ? { truncated: true } : {}),
+        };
+        for (const listener of this.listeners)
+            listener();
+    }
+    closed() {
+        this.current = undefined;
+        this.notifyIdle();
+    }
+    invalidate() {
+        this.epoch += 1;
+        this.current = undefined;
+        for (const listener of this.listeners)
+            listener();
+        this.notifyIdle();
+    }
+    assertCanDispatch() {
+        if (this.pending || [...this.work].some(entry => entry.epoch !== this.epoch)) {
+            throw new PageDialogInterruptedError(this.info(), 'precondition');
+        }
+    }
+    /** Register the actual handler, including its finally; never retain a raw browser Promise here. */
+    execute(work, interrupt = true) {
+        this.assertCanDispatch();
+        const entry = { epoch: this.epoch };
+        this.work.add(entry);
+        let started = false;
+        const release = () => {
+            this.work.delete(entry);
+            this.notifyIdle();
+        };
+        const start = () => {
+            started = true;
+            return Promise.resolve().then(() => {
+                this.assertCanDispatch();
+                return work();
+            }).finally(release);
+        };
+        return (interrupt ? this.race(start) : start()).finally(() => {
+            if (!started)
+                release();
+        });
+    }
+    /** Every real eval/input dispatch must pass here, so a late ack cannot resume its handler. */
+    command(work) {
+        this.assertCanDispatch();
+        return this.race(work);
+    }
+    race(work) {
+        if (this.pending)
+            return Promise.reject(new PageDialogInterruptedError(this.info()));
+        const epoch = this.epoch;
+        return new Promise((resolve, reject) => {
+            const changed = () => {
+                if (epoch === this.epoch)
+                    return;
+                this.listeners.delete(changed);
+                reject(new PageDialogInterruptedError(this.info()));
+            };
+            this.listeners.add(changed);
+            let result;
+            try {
+                result = work();
+            }
+            catch (error) {
+                this.listeners.delete(changed);
+                reject(error);
+                return;
+            }
+            Promise.resolve(result).then(value => {
+                this.listeners.delete(changed);
+                resolve(value);
+            }, error => {
+                this.listeners.delete(changed);
+                reject(error);
+            });
+        });
+    }
+    async press(input, send) {
+        const dialog = this.current;
+        if (!input.dialogId || dialog?.id !== input.dialogId)
+            throw new Error('page_press: dialogId is stale or no native dialog is open. Run page_snapshot.');
+        if (this.handling)
+            throw new Error('page_press: this native dialog is already being handled.');
+        if (!['Enter', 'Escape'].includes(input.key) || input.selector !== undefined || input.modifiers?.length || (input.pressMode && input.pressMode !== 'auto')) {
+            throw new Error('page_press: dialogId requires Enter/Escape without selector, modifiers, or an explicit pressMode.');
+        }
+        if (input.promptText !== undefined && (typeof input.promptText !== 'string' || dialog.type !== 'prompt' || input.key !== 'Enter')) {
+            throw new Error('page_press: promptText is only valid when accepting a native prompt.');
+        }
+        const acceptsPrompt = dialog.type === 'prompt' && input.key === 'Enter';
+        if (acceptsPrompt && input.promptText === undefined && this.defaultPromptTruncated) {
+            throw new Error('page_press: the native prompt default was truncated. Specify promptText explicitly.');
+        }
+        this.handling = dialog.id;
+        try {
+            // No await between the last ID check and send. CDP itself has no atomic dialog-ID CAS.
+            await send({ accept: input.key === 'Enter', ...(acceptsPrompt ? { promptText: input.promptText ?? dialog.defaultPrompt ?? '' } : {}) });
+            return { pressed: true, key: input.key, dispatchMode: 'native-dialog' };
+        }
+        catch (error) {
+            throw new PageActionDispatchUncertainError('page_press: native dialog handling was not acknowledged. Read page_snapshot before trying again.', { cause: error });
+        }
+        finally {
+            this.handling = undefined;
+            // Closed/Opening events own current state; an ack for A must not clear a new dialog B.
+            this.notifyIdle();
+        }
+    }
+    notifyIdle() {
+        if (!this.pending && !this.busy)
+            this.onIdle?.();
+    }
+}
+export function pageDialogSnapshot(dialogs, mode = 'full', maxChars = 25000) {
+    const dialog = dialogs.info(maxChars);
+    return dialog ? {
+        snapshot: `[native ${dialog.type} dialog]`,
+        mode,
+        elementCount: 0,
+        outputNodeCount: 0,
+        dialog,
+    } : undefined;
+}

package/dist/pageObserver.js

@@ -28,9 +28,7 @@ export function isPotentialNavigationRequest(resourceType, url = '') {
     const normalizedType = resourceType.toLowerCase();
     if (normalizedType === 'xhr' || normalizedType === 'fetch')
         return true;
-    if (normalizedType !== 'other')
-        return false;
-    return /(?:\/h5\/(?:mtop|mopen)|\/mtop\.|api-proxy)/i.test(url);
+    return false;
 }
 export function resolveNavigationWaitOptions(options = {}) {
     const timeoutMs = Math.min(Math.max(options.navigationTimeoutMs ?? 15000, 1000), 30000);
@@ -171,7 +169,7 @@ export function installPageObserverInPage(maxBatches = 50) {
     const escapeAttribute = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     const isInternal = (input) => {
         const element = input?.nodeType === Node.ELEMENT_NODE ? input : (input?.parentElement ?? null);
-        return Boolean(element?.closest('[data-mearl-overlay], #__mtop_click_style'));
+        return Boolean(element?.closest('[data-mearl-overlay], #__mearl_click_style'));
     };
     const isVisible = (element) => {
         if (element.closest('[hidden], [aria-hidden="true"]'))
@@ -810,7 +808,20 @@ export function installPageObserverInPage(maxBatches = 50) {
                 const texts = [];
                 let incompleteText = latestTexts.size > textLimit;
                 for (const [element, effect] of latestTexts) {
-                    const current = readPlainText(element);
+                    let current = readPlainText(element);
+                    // Frameworks can replace a just-observed text leaf with an equivalent node.
+                    // Only reuse its stable selector when the replacement is unique and passes
+                    // the same visibility, clipping and text-completeness checks.
+                    if (!element.isConnected) {
+                        try {
+                            const matches = document.querySelectorAll(effect.selector);
+                            if (matches.length === 1)
+                                current = readPlainText(matches[0]);
+                        }
+                        catch {
+                            // Preserve the fallback when the recorded selector cannot be resolved.
+                        }
+                    }
                     if (!current || current.selector !== effect.selector || current.text !== effect.text) {
                         incompleteText = true;
                         continue;

package/dist/pagePressing.d.ts

@@ -31,7 +31,7 @@ export interface PagePressDomTarget {
 export interface PagePressResultData {
     pressed: true;
     key: string;
-    dispatchMode: PagePressDispatchMode;
+    dispatchMode: PagePressDispatchMode | 'native-dialog';
     fallbackReason?: PagePressFallbackReason;
     target?: PagePressDomTarget;
     keydownCanceled?: boolean;

package/dist/providerAppResources.d.ts

@@ -0,0 +1,39 @@
+import type { AppProfileOptions } from './appProfileDefinition.js';
+import type { InjectedAppProfileConfig } from './app-profile-runtime/types.js';
+import type { BrowserCapabilityCatalog } from './browserCapabilities.js';
+import type { GetCapabilitiesParams, BrowserDevicePresetName } from './browserActionProtocol.js';
+import type { ProviderEnhancementTarget } from './browserEnhancement.js';
+export declare const PROVIDER_APP_RESOURCE_PROTOCOL_VERSION = 1;
+export declare const MAX_PROVIDER_APP_RESOURCE_MESSAGE_BYTES: number;
+export type ProviderAppResourceRequest = {
+    operation: 'catalog';
+    params?: GetCapabilitiesParams;
+} | {
+    operation: 'resolve';
+    providerTabId: number;
+    profile: string;
+    options?: AppProfileOptions;
+};
+export interface ProviderAppResourceRevision {
+    capabilityRevision: string | null;
+    installationRevision: string | null;
+}
+export interface ResolvedProviderAppResources extends ProviderAppResourceRevision {
+    config: InjectedAppProfileConfig;
+    recommendedPreset: BrowserDevicePresetName;
+    runtime?: {
+        binding: {
+            id: string;
+            sha256: string;
+        };
+        source: string;
+    };
+}
+/** Code is returned only by explicit resolution, never with ordinary capability discovery. */
+export type ProviderAppResourceResponse = (ProviderAppResourceRevision & {
+    catalog: BrowserCapabilityCatalog['apps'];
+}) | (ResolvedProviderAppResources & {
+    target: Extract<ProviderEnhancementTarget, {
+        ready: true;
+    }>;
+});

package/dist/providerAppResources.js

@@ -0,0 +1,2 @@
+export const PROVIDER_APP_RESOURCE_PROTOCOL_VERSION = 1;
+export const MAX_PROVIDER_APP_RESOURCE_MESSAGE_BYTES = 16 * 1024 * 1024;

package/dist/proxyPermissions.js

@@ -6,7 +6,7 @@ export class DomainPermissionError extends Error {
     domain;
     code = 'DOMAIN_PERMISSION_REQUIRED';
     requestDispatched = false;
-    constructor(action, domain, message = `${action}: Access to "${domain}" is not authorized. Call request_domain_permission with domain="${domain}" to request user authorization, then retry.`) {
+    constructor(action, domain, message = `${action}: Access to "${domain}" is not authorized. Call request_permission with domain="${domain}" to request user authorization, then retry.`) {
         super(message);
         this.action = action;
         this.domain = domain;
@@ -83,11 +83,11 @@ export function isDomainAuthorized(domain, allowedOrigins) {
  * wrappers whose individual steps are checked independently.
  */
 export const ACTIONS_SKIP_DOMAIN_CHECK = new Set([
-    'request_domain_permission',
+    'request_permission',
     'get_browser_info',
     'get_capabilities',
     '__export_cookies',
-    'send_mtop_request',
+    'send_protocol_request',
     'run_actions',
     'browser_release',
     '__control_cleanup',

package/dist/requestMetadata.d.ts

@@ -0,0 +1,9 @@
+/** Optional protocol annotations; the collector retains the original HTTP record. */
+export interface RequestMetadata {
+    apiName: string;
+    namespace?: string;
+    isProxy: boolean;
+    proxyRequestUrl: string | null;
+    environment?: string;
+}
+export declare function parseRequestMetadata(value: unknown): RequestMetadata | null;

package/dist/requestMetadata.js

@@ -0,0 +1,8 @@
+export function parseRequestMetadata(value) {
+    if (value === null || value === undefined)
+        return null;
+    const metadata = value;
+    if (typeof value !== 'object' || Array.isArray(value) || metadata.namespace !== undefined && (typeof metadata.namespace !== 'string' || metadata.namespace.length > 256) || typeof metadata.apiName !== 'string' || metadata.apiName.length > 4096 || typeof metadata.isProxy !== 'boolean' || metadata.proxyRequestUrl !== null && typeof metadata.proxyRequestUrl !== 'string' || metadata.environment !== undefined && (typeof metadata.environment !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$/.test(metadata.environment)))
+        throw new Error('Invalid request metadata');
+    return { ...(metadata.namespace ? { namespace: metadata.namespace } : {}), apiName: metadata.apiName, isProxy: metadata.isProxy, proxyRequestUrl: metadata.proxyRequestUrl, ...(metadata.environment ? { environment: metadata.environment } : {}) };
+}

package/dist/requestSerializer.d.ts

@@ -1,7 +1,7 @@
 /**
  * Request serialization utilities — pure computation, no environment dependencies.
  */
-import type { MtopRequest } from './types.js';
+import type { CapturedRequest } from './types.js';
 export interface SerializeOptions {
     includeBody?: boolean;
     includeHeaders?: boolean;
@@ -10,4 +10,4 @@ export interface SerializeOptions {
     keysOnly?: boolean;
 }
 export declare function setValueByPath(obj: any, path: string, value: any): void;
-export declare function serializeRequest(request: MtopRequest, options?: SerializeOptions): any;
+export declare function serializeRequest(request: CapturedRequest, options?: SerializeOptions): any;

package/dist/requestStreamCapture.d.ts

@@ -1,6 +1,6 @@
-import type { MtopRequest } from './types.js';
+import type { CapturedRequest } from './types.js';
 export interface RequestStreamCapture {
-    request: MtopRequest;
+    request: CapturedRequest;
     startTimeMs: number;
     lastMessageTimeMs?: number;
 }
@@ -8,7 +8,9 @@ export interface RequestStreamCaptureStart {
     id: number;
     api: string;
     url: string;
-    source?: MtopRequest['source'];
+    source?: CapturedRequest['source'];
+    namespace?: string;
+    environment?: string;
     method: string;
     requestHeaders?: Array<{
         name: string;

package/dist/requestStreamCapture.js

@@ -34,6 +34,8 @@ export function createRequestStreamCapture(data) {
             method: data.method,
             url,
             apiName: data.api,
+            ...(data.namespace !== undefined ? { namespace: data.namespace } : {}),
+            ...(data.environment !== undefined ? { environment: data.environment } : {}),
             status: 0,
             statusText: 'SSE Streaming',
             headers: redactSensitiveHeaders(data.requestHeaders ?? []),

package/dist/types.d.ts

@@ -19,7 +19,9 @@ export interface ResponseOverride {
     disabled?: boolean;
     isSSE?: boolean;
 }
-export interface MtopRequest {
+export interface CapturedRequest {
+    namespace?: string;
+    environment?: string;
     id: number;
     timestamp: string;
     timestampMs: number;
@@ -59,7 +61,7 @@ export interface MtopRequest {
     _createdByInjected?: boolean;
     tabId?: number;
     isAutoTranslated?: boolean;
-    source?: 'mtop' | 'requests';
+    source?: 'protocol' | 'requests';
     resourceType?: string;
     /** Monotonic sequence assigned when the request started. */
     captureSequence?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/browser-core",
-  "version": "3.0.0-beta.5",
+  "version": "3.0.0-beta.7",
   "description": "Shared pure-logic utilities for Mearl — usable in both browser extension and Node.js environments",
   "type": "module",
   "main": "dist/index.js",
@@ -60,7 +60,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/browser-core"
   },
   "scripts": {