browser-use 0.2.0 → 0.3.0

package/dist/browser/watchdogs/recording-watchdog.js

@@ -0,0 +1,249 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AgentFocusChangedEvent, BrowserConnectedEvent, BrowserErrorEvent, BrowserStopEvent, BrowserStoppedEvent, TabCreatedEvent, } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export class RecordingWatchdog extends BaseWatchdog {
+    static LISTENS_TO = [
+        BrowserConnectedEvent,
+        BrowserStopEvent,
+        BrowserStoppedEvent,
+        AgentFocusChangedEvent,
+        TabCreatedEvent,
+    ];
+    _traceStarted = false;
+    _videoCloseListeners = new Map();
+    _cdpScreencastSession = null;
+    _cdpScreencastHandler = null;
+    _cdpScreencastPath = null;
+    _cdpScreencastStream = null;
+    async on_BrowserConnectedEvent() {
+        this._prepareVideoDirectory();
+        this._attachVideoListenersToKnownPages();
+        await this._startCdpScreencastIfConfigured();
+        await this._startTracingIfConfigured();
+    }
+    async on_BrowserStopEvent() {
+        await this._stopCdpScreencastIfStarted();
+        await this._stopTracingIfStarted();
+    }
+    async on_BrowserStoppedEvent() {
+        this._detachVideoListeners();
+    }
+    async on_AgentFocusChangedEvent(event) {
+        this._attachVideoListenersToKnownPages();
+        await this._startCdpScreencastIfConfigured();
+        if (!this._traceStarted) {
+            return;
+        }
+        this.browser_session.logger.debug(`[RecordingWatchdog] Focus changed to ${event.target_id}; tracing remains active`);
+    }
+    async on_TabCreatedEvent() {
+        this._attachVideoListenersToKnownPages();
+        await this._startCdpScreencastIfConfigured();
+    }
+    onDetached() {
+        void this._stopCdpScreencastIfStarted();
+        this._detachVideoListeners();
+    }
+    _prepareVideoDirectory() {
+        const configuredPath = this.browser_session.browser_profile.config.record_video_dir;
+        if (typeof configuredPath !== 'string' || configuredPath.trim() === '') {
+            return;
+        }
+        const resolvedPath = path.resolve(configuredPath);
+        fs.mkdirSync(resolvedPath, { recursive: true });
+        this.browser_session.browser_profile.config.record_video_dir = resolvedPath;
+    }
+    async _startTracingIfConfigured() {
+        if (this._traceStarted ||
+            !this.browser_session.browser_profile.traces_dir) {
+            return;
+        }
+        try {
+            await this.browser_session.start_trace_recording();
+            this._traceStarted = true;
+        }
+        catch (error) {
+            await this.event_bus.dispatch(new BrowserErrorEvent({
+                error_type: 'RecordingStartFailed',
+                message: `Failed to start trace recording: ${error.message}`,
+                details: {
+                    traces_dir: this.browser_session.browser_profile.traces_dir,
+                },
+            }));
+        }
+    }
+    async _stopTracingIfStarted() {
+        if (!this._traceStarted) {
+            return;
+        }
+        try {
+            await this.browser_session.save_trace_recording();
+        }
+        catch (error) {
+            await this.event_bus.dispatch(new BrowserErrorEvent({
+                error_type: 'RecordingStopFailed',
+                message: `Failed to save trace recording: ${error.message}`,
+                details: {
+                    traces_dir: this.browser_session.browser_profile.traces_dir,
+                },
+            }));
+        }
+        finally {
+            this._traceStarted = false;
+        }
+    }
+    _attachVideoListenersToKnownPages() {
+        const configuredPath = this.browser_session.browser_profile.config.record_video_dir;
+        if (typeof configuredPath !== 'string' || configuredPath.trim() === '') {
+            return;
+        }
+        for (const page of this._getKnownPages()) {
+            this._attachVideoListener(page);
+        }
+    }
+    _attachVideoListener(page) {
+        if (this._videoCloseListeners.has(page) || typeof page?.on !== 'function') {
+            return;
+        }
+        const listener = () => {
+            this._videoCloseListeners.delete(page);
+            if (typeof page.off === 'function') {
+                page.off('close', listener);
+            }
+            else if (typeof page.removeListener === 'function') {
+                page.removeListener('close', listener);
+            }
+            void this._captureVideoArtifact(page);
+        };
+        page.on('close', listener);
+        this._videoCloseListeners.set(page, listener);
+    }
+    _detachVideoListeners() {
+        for (const [page, listener] of [...this._videoCloseListeners.entries()]) {
+            if (typeof page.off === 'function') {
+                page.off('close', listener);
+            }
+            else if (typeof page.removeListener === 'function') {
+                page.removeListener('close', listener);
+            }
+        }
+        this._videoCloseListeners.clear();
+    }
+    _getKnownPages() {
+        const pagesFromContext = typeof this.browser_session.browser_context?.pages === 'function'
+            ? this.browser_session.browser_context.pages()
+            : [];
+        const activePage = this.browser_session
+            .agent_current_page;
+        if (!activePage) {
+            return pagesFromContext;
+        }
+        if (pagesFromContext.includes(activePage)) {
+            return pagesFromContext;
+        }
+        return [...pagesFromContext, activePage];
+    }
+    async _captureVideoArtifact(page) {
+        try {
+            const video = typeof page.video === 'function' ? page.video() : null;
+            const videoPath = await video?.path?.();
+            if (typeof videoPath === 'string' && videoPath.length > 0) {
+                this.browser_session.add_downloaded_file(videoPath);
+            }
+        }
+        catch (error) {
+            this.browser_session.logger.debug(`[RecordingWatchdog] Failed to capture video artifact: ${error.message}`);
+        }
+    }
+    async _startCdpScreencastIfConfigured() {
+        const configuredPath = this.browser_session.browser_profile.config.record_video_dir;
+        if (typeof configuredPath !== 'string' || configuredPath.trim() === '') {
+            return;
+        }
+        if (this._cdpScreencastSession || this._cdpScreencastStream) {
+            return;
+        }
+        try {
+            const page = await this.browser_session.get_current_page();
+            if (!page) {
+                return;
+            }
+            const session = (await this.browser_session.get_or_create_cdp_session(page));
+            const filePath = path.join(configuredPath, `${Date.now()}-${this.browser_session.id.slice(-6)}.cdp-screencast.ndjson`);
+            const stream = fs.createWriteStream(filePath, { flags: 'a' });
+            const handler = (payload) => {
+                const frameData = typeof payload?.data === 'string' ? payload.data : '';
+                if (frameData && this._cdpScreencastStream) {
+                    this._cdpScreencastStream.write(`${JSON.stringify({
+                        ts: Date.now(),
+                        session_id: typeof payload?.sessionId === 'number' ||
+                            typeof payload?.sessionId === 'string'
+                            ? payload.sessionId
+                            : null,
+                        data: frameData,
+                    })}\n`);
+                }
+                const sessionId = typeof payload?.sessionId === 'number' ||
+                    typeof payload?.sessionId === 'string'
+                    ? payload.sessionId
+                    : null;
+                if (!sessionId) {
+                    return;
+                }
+                void session.send?.('Page.screencastFrameAck', {
+                    sessionId,
+                });
+            };
+            await session.send?.('Page.enable');
+            session.on?.('Page.screencastFrame', handler);
+            await session.send?.('Page.startScreencast', {
+                format: 'jpeg',
+                quality: 85,
+                everyNthFrame: 1,
+            });
+            this._cdpScreencastSession = session;
+            this._cdpScreencastHandler = handler;
+            this._cdpScreencastPath = filePath;
+            this._cdpScreencastStream = stream;
+        }
+        catch (error) {
+            await this.event_bus.dispatch(new BrowserErrorEvent({
+                error_type: 'RecordingCdpStartFailed',
+                message: `Failed to start CDP screencast recording: ${error.message}`,
+                details: {
+                    record_video_dir: this.browser_session.browser_profile.config.record_video_dir,
+                },
+            }));
+            await this._stopCdpScreencastIfStarted();
+        }
+    }
+    async _stopCdpScreencastIfStarted() {
+        if (!this._cdpScreencastSession) {
+            return;
+        }
+        try {
+            await this._cdpScreencastSession.send?.('Page.stopScreencast');
+        }
+        catch {
+            // Ignore stop errors.
+        }
+        if (this._cdpScreencastHandler) {
+            this._cdpScreencastSession.off?.('Page.screencastFrame', this._cdpScreencastHandler);
+        }
+        if (this._cdpScreencastStream) {
+            await new Promise((resolve) => {
+                this._cdpScreencastStream?.end(() => resolve());
+            });
+        }
+        if (this._cdpScreencastPath &&
+            fs.existsSync(this._cdpScreencastPath) &&
+            fs.statSync(this._cdpScreencastPath).size > 0) {
+            this.browser_session.add_downloaded_file(this._cdpScreencastPath);
+        }
+        this._cdpScreencastSession = null;
+        this._cdpScreencastHandler = null;
+        this._cdpScreencastPath = null;
+        this._cdpScreencastStream = null;
+    }
+}

package/dist/browser/watchdogs/screenshot-watchdog.d.ts

@@ -0,0 +1,6 @@
+import { ScreenshotEvent } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export declare class ScreenshotWatchdog extends BaseWatchdog {
+    static LISTENS_TO: (typeof ScreenshotEvent)[];
+    on_ScreenshotEvent(event: ScreenshotEvent): Promise<string | null>;
+}

package/dist/browser/watchdogs/screenshot-watchdog.js

@@ -0,0 +1,13 @@
+import { ScreenshotEvent } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export class ScreenshotWatchdog extends BaseWatchdog {
+    static LISTENS_TO = [ScreenshotEvent];
+    async on_ScreenshotEvent(event) {
+        try {
+            return await this.browser_session.take_screenshot(event.full_page);
+        }
+        finally {
+            await this.browser_session.remove_highlights();
+        }
+    }
+}

package/dist/browser/watchdogs/security-watchdog.d.ts

@@ -0,0 +1,10 @@
+import { BrowserErrorEvent, CloseTabEvent, NavigateToUrlEvent, NavigationCompleteEvent, TabCreatedEvent } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export declare class SecurityWatchdog extends BaseWatchdog {
+    static LISTENS_TO: (typeof NavigateToUrlEvent | typeof TabCreatedEvent)[];
+    static EMITS: (typeof CloseTabEvent | typeof BrowserErrorEvent)[];
+    on_NavigateToUrlEvent(event: NavigateToUrlEvent): Promise<void>;
+    on_NavigationCompleteEvent(event: NavigationCompleteEvent): Promise<void>;
+    on_TabCreatedEvent(event: TabCreatedEvent): Promise<void>;
+    private _getUrlDenialReason;
+}

package/dist/browser/watchdogs/security-watchdog.js

@@ -0,0 +1,84 @@
+import { BrowserErrorEvent, CloseTabEvent, NavigateToUrlEvent, NavigationCompleteEvent, TabCreatedEvent, } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export class SecurityWatchdog extends BaseWatchdog {
+    static LISTENS_TO = [
+        NavigateToUrlEvent,
+        NavigationCompleteEvent,
+        TabCreatedEvent,
+    ];
+    static EMITS = [BrowserErrorEvent, CloseTabEvent];
+    async on_NavigateToUrlEvent(event) {
+        const denialReason = this._getUrlDenialReason(event.url);
+        if (!denialReason) {
+            return;
+        }
+        await this.event_bus.dispatch(new BrowserErrorEvent({
+            error_type: 'NavigationBlocked',
+            message: `Navigation blocked to disallowed URL: ${event.url}`,
+            details: {
+                url: event.url,
+                reason: denialReason,
+            },
+        }));
+        throw new Error(`Navigation to ${event.url} blocked by security policy`);
+    }
+    async on_NavigationCompleteEvent(event) {
+        const denialReason = this._getUrlDenialReason(event.url);
+        if (!denialReason) {
+            return;
+        }
+        await this.event_bus.dispatch(new BrowserErrorEvent({
+            error_type: 'NavigationBlocked',
+            message: `Navigation blocked to non-allowed URL: ${event.url} - redirecting to about:blank`,
+            details: {
+                url: event.url,
+                target_id: event.target_id,
+                reason: denialReason,
+            },
+        }));
+        try {
+            await this.browser_session.navigate_to('about:blank');
+        }
+        catch (error) {
+            this.browser_session.logger.debug(`SecurityWatchdog failed to redirect to about:blank: ${error.message}`);
+        }
+    }
+    async on_TabCreatedEvent(event) {
+        const denialReason = this._getUrlDenialReason(event.url);
+        if (!denialReason) {
+            return;
+        }
+        await this.event_bus.dispatch(new BrowserErrorEvent({
+            error_type: 'TabCreationBlocked',
+            message: `Tab created with non-allowed URL: ${event.url}`,
+            details: {
+                url: event.url,
+                target_id: event.target_id,
+                reason: denialReason,
+            },
+        }));
+        await this.event_bus.dispatch(new CloseTabEvent({
+            target_id: event.target_id,
+        }));
+    }
+    _getUrlDenialReason(url) {
+        const session = this.browser_session;
+        if (typeof session._get_url_access_denial_reason === 'function') {
+            try {
+                return session._get_url_access_denial_reason(url);
+            }
+            catch {
+                // Ignore private method failures and fallback to boolean check.
+            }
+        }
+        if (typeof session._is_url_allowed === 'function') {
+            try {
+                return session._is_url_allowed(url) ? null : 'blocked';
+            }
+            catch {
+                return 'blocked';
+            }
+        }
+        return null;
+    }
+}

package/dist/browser/watchdogs/storage-state-watchdog.d.ts

@@ -0,0 +1,24 @@
+import { BrowserConnectedEvent, BrowserStopEvent, LoadStorageStateEvent, SaveStorageStateEvent, StorageStateSavedEvent } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export declare class StorageStateWatchdog extends BaseWatchdog {
+    static LISTENS_TO: (typeof BrowserStopEvent | typeof BrowserConnectedEvent | typeof SaveStorageStateEvent)[];
+    static EMITS: (typeof StorageStateSavedEvent)[];
+    private _monitorInterval;
+    private _autoSaveIntervalMs;
+    private _monitoring;
+    private _lastSavedSnapshot;
+    on_BrowserConnectedEvent(): Promise<void>;
+    on_BrowserStopEvent(): Promise<void>;
+    on_SaveStorageStateEvent(event: SaveStorageStateEvent): Promise<void>;
+    on_LoadStorageStateEvent(event: LoadStorageStateEvent): Promise<void>;
+    protected onDetached(): void;
+    private _resolveStoragePath;
+    private _startMonitoring;
+    private _stopMonitoring;
+    private _checkAndAutoSave;
+    private _snapshotStorageState;
+    private _readStoredState;
+    private _mergeStorageStates;
+    private _applyOriginsStorage;
+    private _normalizeStorageEntries;
+}

package/dist/browser/watchdogs/storage-state-watchdog.js

@@ -0,0 +1,288 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { BrowserConnectedEvent, BrowserStopEvent, LoadStorageStateEvent, SaveStorageStateEvent, StorageStateLoadedEvent, StorageStateSavedEvent, } from '../events.js';
+import { BaseWatchdog } from './base.js';
+export class StorageStateWatchdog extends BaseWatchdog {
+    static LISTENS_TO = [
+        BrowserConnectedEvent,
+        BrowserStopEvent,
+        SaveStorageStateEvent,
+        LoadStorageStateEvent,
+    ];
+    static EMITS = [StorageStateSavedEvent, StorageStateLoadedEvent];
+    _monitorInterval = null;
+    _autoSaveIntervalMs = 30_000;
+    _monitoring = false;
+    _lastSavedSnapshot = null;
+    async on_BrowserConnectedEvent() {
+        this._startMonitoring();
+        await this.event_bus.dispatch(new LoadStorageStateEvent());
+    }
+    async on_BrowserStopEvent() {
+        this._stopMonitoring();
+        await this.event_bus.dispatch(new SaveStorageStateEvent());
+    }
+    async on_SaveStorageStateEvent(event) {
+        const targetPath = this._resolveStoragePath(event.path);
+        if (!targetPath) {
+            return;
+        }
+        const browserContext = this.browser_session.browser_context;
+        if (!browserContext?.storageState) {
+            this.browser_session.logger.debug('[StorageStateWatchdog] Browser context unavailable for save');
+            return;
+        }
+        const storageState = (await browserContext.storageState());
+        const normalized = storageState ?? {};
+        const merged = this._mergeStorageStates(this._readStoredState(targetPath), {
+            cookies: Array.isArray(normalized.cookies) ? normalized.cookies : [],
+            origins: Array.isArray(normalized.origins) ? normalized.origins : [],
+        });
+        this._lastSavedSnapshot = this._snapshotStorageState(merged);
+        const dirPath = path.dirname(targetPath);
+        fs.mkdirSync(dirPath, { recursive: true });
+        const tempPath = `${targetPath}.tmp`;
+        fs.writeFileSync(tempPath, JSON.stringify(merged, null, 2));
+        if (fs.existsSync(targetPath)) {
+            const backupPath = `${targetPath}.bak`;
+            try {
+                fs.renameSync(targetPath, backupPath);
+            }
+            catch {
+                // Ignore backup failures and continue with atomic swap.
+            }
+        }
+        fs.renameSync(tempPath, targetPath);
+        await this.event_bus.dispatch(new StorageStateSavedEvent({
+            path: targetPath,
+            cookies_count: Array.isArray(merged.cookies)
+                ? merged.cookies.length
+                : 0,
+            origins_count: Array.isArray(merged.origins)
+                ? merged.origins.length
+                : 0,
+        }));
+    }
+    async on_LoadStorageStateEvent(event) {
+        const targetPath = this._resolveStoragePath(event.path);
+        if (!targetPath || !fs.existsSync(targetPath)) {
+            return;
+        }
+        const browserContext = this.browser_session.browser_context;
+        if (!browserContext) {
+            this.browser_session.logger.debug('[StorageStateWatchdog] Browser context unavailable for load');
+            return;
+        }
+        const raw = fs.readFileSync(targetPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const cookies = Array.isArray(parsed.cookies) ? parsed.cookies : [];
+        const origins = Array.isArray(parsed.origins) ? parsed.origins : [];
+        this._lastSavedSnapshot = this._snapshotStorageState({
+            cookies,
+            origins,
+        });
+        if (cookies.length > 0 && typeof browserContext.addCookies === 'function') {
+            await browserContext.addCookies(cookies);
+        }
+        if (origins.length > 0) {
+            await this._applyOriginsStorage(origins);
+        }
+        await this.event_bus.dispatch(new StorageStateLoadedEvent({
+            path: targetPath,
+            cookies_count: cookies.length,
+            origins_count: origins.length,
+        }));
+    }
+    onDetached() {
+        this._stopMonitoring();
+    }
+    _resolveStoragePath(pathFromEvent) {
+        if (typeof pathFromEvent === 'string' && pathFromEvent.trim().length > 0) {
+            return path.resolve(pathFromEvent);
+        }
+        const configured = this.browser_session.browser_profile.config.storage_state;
+        if (typeof configured === 'string' && configured.trim().length > 0) {
+            return path.resolve(configured);
+        }
+        const cookiesFile = this.browser_session.browser_profile.cookies_file;
+        if (typeof cookiesFile === 'string' && cookiesFile.trim().length > 0) {
+            return path.resolve(cookiesFile);
+        }
+        return null;
+    }
+    _startMonitoring() {
+        if (this._monitorInterval) {
+            return;
+        }
+        if (!this._resolveStoragePath(null)) {
+            return;
+        }
+        this._monitorInterval = setInterval(() => {
+            void this._checkAndAutoSave().catch((error) => {
+                this.browser_session.logger.debug(`[StorageStateWatchdog] Auto-save monitor failed: ${error.message}`);
+            });
+        }, this._autoSaveIntervalMs);
+    }
+    _stopMonitoring() {
+        if (!this._monitorInterval) {
+            return;
+        }
+        clearInterval(this._monitorInterval);
+        this._monitorInterval = null;
+    }
+    async _checkAndAutoSave() {
+        if (this._monitoring) {
+            return;
+        }
+        const browserContext = this.browser_session.browser_context;
+        if (!browserContext?.storageState) {
+            return;
+        }
+        this._monitoring = true;
+        try {
+            const storageState = (await browserContext.storageState());
+            const normalized = storageState ?? {};
+            const snapshot = this._snapshotStorageState(normalized);
+            if (snapshot === this._lastSavedSnapshot) {
+                return;
+            }
+            await this.event_bus.dispatch(new SaveStorageStateEvent());
+        }
+        finally {
+            this._monitoring = false;
+        }
+    }
+    _snapshotStorageState(state) {
+        const cookies = Array.isArray(state.cookies) ? state.cookies : [];
+        const origins = Array.isArray(state.origins) ? state.origins : [];
+        return JSON.stringify({
+            cookies,
+            origins,
+        });
+    }
+    _readStoredState(targetPath) {
+        if (!fs.existsSync(targetPath)) {
+            return {
+                cookies: [],
+                origins: [],
+            };
+        }
+        try {
+            const raw = fs.readFileSync(targetPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return {
+                cookies: Array.isArray(parsed.cookies) ? parsed.cookies : [],
+                origins: Array.isArray(parsed.origins) ? parsed.origins : [],
+            };
+        }
+        catch (error) {
+            this.browser_session.logger.debug(`[StorageStateWatchdog] Failed to parse existing storage state: ${error.message}`);
+            return {
+                cookies: [],
+                origins: [],
+            };
+        }
+    }
+    _mergeStorageStates(existing, incoming) {
+        const mergedCookies = new Map();
+        const toCookieKey = (cookie) => `${String(cookie?.name ?? '')}::${String(cookie?.domain ?? '')}::${String(cookie?.path ?? '')}`;
+        for (const cookie of Array.isArray(existing.cookies)
+            ? existing.cookies
+            : []) {
+            mergedCookies.set(toCookieKey(cookie), cookie);
+        }
+        for (const cookie of Array.isArray(incoming.cookies)
+            ? incoming.cookies
+            : []) {
+            mergedCookies.set(toCookieKey(cookie), cookie);
+        }
+        const mergedOrigins = new Map();
+        const toOriginKey = (origin) => String(origin?.origin ?? '');
+        for (const origin of Array.isArray(existing.origins)
+            ? existing.origins
+            : []) {
+            mergedOrigins.set(toOriginKey(origin), origin);
+        }
+        for (const origin of Array.isArray(incoming.origins)
+            ? incoming.origins
+            : []) {
+            mergedOrigins.set(toOriginKey(origin), origin);
+        }
+        return {
+            cookies: [...mergedCookies.values()],
+            origins: [...mergedOrigins.values()],
+        };
+    }
+    async _applyOriginsStorage(origins) {
+        const browserContext = this.browser_session.browser_context;
+        if (!browserContext?.newPage) {
+            return;
+        }
+        for (const originState of origins) {
+            const origin = typeof originState?.origin === 'string'
+                ? originState.origin.trim()
+                : '';
+            if (!origin || !/^https?:\/\//i.test(origin)) {
+                continue;
+            }
+            const localStorageEntries = this._normalizeStorageEntries(originState?.localStorage);
+            const sessionStorageEntries = this._normalizeStorageEntries(originState?.sessionStorage);
+            if (localStorageEntries.length === 0 &&
+                sessionStorageEntries.length === 0) {
+                continue;
+            }
+            let page = null;
+            try {
+                page = await browserContext.newPage();
+                await page.goto?.(origin, {
+                    waitUntil: 'domcontentloaded',
+                    timeout: 5_000,
+                });
+                await page.evaluate?.((payload) => {
+                    for (const entry of payload.localStorageEntries) {
+                        window.localStorage.setItem(entry.name, entry.value);
+                    }
+                    for (const entry of payload.sessionStorageEntries) {
+                        window.sessionStorage.setItem(entry.name, entry.value);
+                    }
+                }, {
+                    localStorageEntries,
+                    sessionStorageEntries,
+                });
+            }
+            catch (error) {
+                this.browser_session.logger.debug(`[StorageStateWatchdog] Failed to apply origin storage for ${origin}: ${error.message}`);
+            }
+            finally {
+                try {
+                    await page?.close?.();
+                }
+                catch {
+                    // Ignore cleanup errors.
+                }
+            }
+        }
+    }
+    _normalizeStorageEntries(entries) {
+        if (!Array.isArray(entries)) {
+            return [];
+        }
+        const normalized = [];
+        for (const entry of entries) {
+            const name = entry && typeof entry === 'object' && 'name' in entry
+                ? String(entry.name ?? '')
+                : '';
+            if (!name) {
+                continue;
+            }
+            const value = entry && typeof entry === 'object' && 'value' in entry
+                ? String(entry.value ?? '')
+                : '';
+            normalized.push({
+                name,
+                value,
+            });
+        }
+        return normalized;
+    }
+}