@agentrhq/webcmd 0.2.0 → 0.2.1

package/README.md

@@ -1,26 +1,38 @@
 <img width="2054" height="766" alt="Webcmd banner" src="https://github.com/user-attachments/assets/3e5b9702-5ffd-43bd-ab1b-2319a8cc0e2a" />
 
-# Webcmd
-
 <p align="center">
   <a href="https://www.npmjs.com/package/@agentrhq/webcmd">
     <img alt="NPM version" src="https://img.shields.io/npm/v/@agentrhq/webcmd.svg?style=for-the-badge&color=1E88E5&labelColor=000000">
   </a>
+  <a href="https://www.npmjs.com/package/@agentrhq/webcmd">
+    <img alt="NPM downloads" src="https://img.shields.io/npm/dt/@agentrhq/webcmd.svg?style=for-the-badge&color=1E88E5&labelColor=000000">
+  </a>
   <a href="https://github.com/agentrhq/webcmd/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-1E88E5.svg?style=for-the-badge&labelColor=000000">
   </a>
-  <a href="https://github.com/agentrhq/webcmd/discussions">
-    <img alt="Join the community on GitHub" src="https://img.shields.io/badge/Join%20the%20community-1E88E5.svg?style=for-the-badge&logo=github&labelColor=000000&logoWidth=20">
+  <a href="https://discord.gg/9YP2C9tvMp">
+    <img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-7C3AED.svg?style=for-the-badge&logo=discord&logoColor=white&labelColor=000000&logoWidth=20">
+  </a>
+  <a href="https://x.com/agentrhq">
+    <img alt="Follow AgentR on X" src="https://img.shields.io/badge/Follow%20%40agentrhq-000000.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000&logoWidth=20">
   </a>
 </p>
 
-**Turn websites, browser sessions, desktop apps, and local tools into deterministic command-line surfaces for people and AI agents.**
+# Webcmd
+
+**Self-learning browser infra for AI agents.**
+
+WebCMD learns the navigational context of websites as agents use them, then compiles that knowledge into deterministic commands for faster, cheaper, more reliable browser automation. The goal is simple: stop making agents rediscover the same sites on every run and cut browser-agent token spend by up to 90%.
+
+On top of vanilla browser interactions, WebCMD adds 3 layers of learnings. Each layer collapses cost and variance for the layer above it.
 
-Webcmd gives you one command surface for three kinds of automation:
+| Layer | Scenario | What Webcmd Helps With |
+| --- | --- | --- |
+| 1. Live browser control | The site is unfamiliar. | Use `webcmd browser` to inspect, click, type, extract, capture network calls, and complete the task in a real browser. |
+| 2. Sitemap memory | The site is familiar, but the action space is not fully known. | Capture an agent-facing sitemap of observed pages, states, actions, workflows, APIs, pitfalls, and fallback paths. |
+| 3. CLI authoring | The action space is known, but the path is still too variable for one fixed sequence. | Explicitly author a reusable `webcmd <site> <command>` adapter with structured output, so future agents spend tokens on the task instead of navigation. |
+| 4. Custom CLI commands | The workflow is deterministic enough to stop browsing. | Extend the CLI with a tailored command so the workflow runs instantly with the least amount of tokens. |
 
-- **Use built-in adapters** for sites like Reddit, Hacker News, LinkedIn, Twitter/X, TikTok, Amazon, PubMed, ChatGPT, Claude, Gemini, NotebookLM, and many more.
-- **Let AI agents operate a real browser** with `webcmd browser <session> ...` primitives: open pages, inspect DOM snapshots, click, type, select, extract, capture network calls, and verify flows.
-- **Wrap local tools and desktop apps** so agents can discover and invoke `gh`, `docker`, `vercel`, Electron apps, and other command surfaces through the same `webcmd ...` entrypoint.
 
 ## Quick Start
 
@@ -139,7 +151,7 @@ webcmd <site> <command> -f json
 webcmd <site> <command> --trace retain-on-failure -f json
 ```
 
-Start with adapters. Fall back to `webcmd browser` only when no adapter covers the task or you are debugging/building one.
+Start with adapters. Fall back to `webcmd browser` only when no adapter covers the task or you are teaching Webcmd a new site flow.
 
 ## Browser Automation
 
@@ -235,7 +247,7 @@ Use plugins for private company workflows, community adapters, or experiments th
 
 ## Writing Adapters
 
-When a site is not covered yet, author a reusable adapter instead of leaving an agent to click through the same browser flow every time.
+When a site is not covered yet, author a reusable adapter instead of leaving an agent to spend tokens clicking through the same browser flow every time.
 
 ```bash
 webcmd browser init <site>/<command>

package/cli-manifest.json

@@ -23638,6 +23638,8 @@
       "likes",
       "retweets",
       "replies",
+      "quotes",
+      "bookmarks",
       "views",
       "created_at",
       "url",

package/clis/twitter/delete.js

@@ -1,28 +1,36 @@
 import { cli, Strategy } from '@agentrhq/webcmd/registry';
 import { CommandExecutionError } from '@agentrhq/webcmd/errors';
-import { parseTweetUrl, buildTwitterArticleScopeSource } from './shared.js';
+import { parseTweetUrl, buildTwitterArticleScopeSource, unwrapBrowserResult } from './shared.js';
 
 function buildDeleteScript(tweetId) {
     return `(async () => {
       try {
           const visible = (el) => !!el && (el.offsetParent !== null || el.getClientRects().length > 0);
           ${buildTwitterArticleScopeSource(tweetId)}
-          const targetArticle = findTargetArticle();
+          let targetArticle = findTargetArticle();
+          for (let i = 0; i < 20 && !targetArticle; i++) {
+              await new Promise(r => setTimeout(r, 250));
+              targetArticle = findTargetArticle();
+          }
 
           if (!targetArticle) {
               return { ok: false, message: 'Could not find the tweet card matching the requested URL.' };
           }
 
-          const buttons = Array.from(targetArticle.querySelectorAll('button,[role="button"]'));
-          const moreMenu = buttons.find((el) => visible(el) && (el.getAttribute('aria-label') || '').trim() === 'More');
+          const belongsToTargetArticle = (el) => el.closest('article') === targetArticle;
+          const buttons = Array.from(targetArticle.querySelectorAll('button,[role="button"]')).filter(belongsToTargetArticle);
+          const moreMenu = Array.from(targetArticle.querySelectorAll('[data-testid="caret"]')).filter(belongsToTargetArticle).find(visible)
+              || buttons.find((el) => visible(el) && /^More/.test((el.getAttribute('aria-label') || '').trim()));
           if (!moreMenu) {
               return { ok: false, message: 'Could not find the "More" context menu on the matched tweet. Are you sure you are logged in and looking at a valid tweet?' };
           }
 
+          const beforeMenuItems = new Set(document.querySelectorAll('[role="menuitem"]'));
           moreMenu.click();
           await new Promise(r => setTimeout(r, 1000));
 
-          const items = Array.from(document.querySelectorAll('[role="menuitem"]'));
+          const items = Array.from(document.querySelectorAll('[role="menuitem"]'))
+              .filter((item) => visible(item) && !beforeMenuItems.has(item));
           const deleteBtn = items.find((item) => {
               const text = (item.textContent || '').trim();
               return text.includes('Delete') && !text.includes('List');
@@ -69,7 +77,7 @@ cli({
         const target = parseTweetUrl(kwargs.url);
         await page.goto(target.url);
         await page.wait({ selector: '[data-testid="primaryColumn"]' }); // Wait for tweet to load completely
-        const result = await page.evaluate(buildDeleteScript(target.id));
+        const result = unwrapBrowserResult(await page.evaluate(buildDeleteScript(target.id)));
         if (result.ok) {
             // Wait for the deletion request to be processed
             await page.wait(2);

package/clis/twitter/delete.test.js

@@ -1,7 +1,8 @@
 import { describe, expect, it, vi } from 'vitest';
+import { JSDOM } from 'jsdom';
 import { ArgumentError, CommandExecutionError } from '@agentrhq/webcmd/errors';
 import { getRegistry } from '@agentrhq/webcmd/registry';
-import './delete.js';
+import { __test__ } from './delete.js';
 describe('twitter delete command', () => {
     it('targets the matched tweet article instead of the first More button on the page', async () => {
         const cmd = getRegistry().get('twitter/delete');
@@ -27,6 +28,12 @@ describe('twitter delete command', () => {
         expect(script).toContain('__twGetStatusIdFromHref');
         expect(script).toContain("document.querySelectorAll('article')");
         expect(script).toContain("targetArticle.querySelectorAll('button,[role=\"button\"]')");
+        expect(script).toContain("closest('article') === targetArticle");
+        expect(script).toContain(".filter(belongsToTargetArticle)");
+        expect(script).toContain('[data-testid="caret"]');
+        expect(script).toContain('/^More/');
+        expect(script).toContain('i < 20');
+        expect(script).toContain('beforeMenuItems');
         // Substring match must NOT appear — exact-id match only.
         expect(script).not.toContain("'/status/' + tweetId");
         expect(result).toEqual([
@@ -58,6 +65,72 @@ describe('twitter delete command', () => {
         ]);
         expect(page.wait).toHaveBeenCalledTimes(1);
     });
+    it('unwraps browser runtime evaluate envelopes before checking delete success', async () => {
+        const cmd = getRegistry().get('twitter/delete');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                session: 'twitter',
+                data: { ok: true, message: 'Tweet successfully deleted.' },
+            }),
+        };
+        const result = await cmd.func(page, {
+            url: 'https://x.com/alice/status/2040254679301718161',
+        });
+        expect(result).toEqual([
+            {
+                status: 'success',
+                message: 'Tweet successfully deleted.',
+            },
+        ]);
+        expect(page.wait).toHaveBeenNthCalledWith(2, 2);
+    });
+    it('ignores stale non-target delete menu items that existed before opening the matched tweet menu', async () => {
+        const dom = new JSDOM(`
+            <body>
+              <div role="menuitem" data-stale-delete>Delete</div>
+              <article>
+                <a href="https://x.com/bob/status/999">wrong tweet</a>
+                <button data-testid="caret" aria-label="More"></button>
+              </article>
+              <article>
+                <a href="https://x.com/alice/status/2040254679301718161">target tweet</a>
+                <button data-testid="caret" aria-label="More" data-target-caret></button>
+              </article>
+            </body>
+        `, { runScripts: 'outside-only', url: 'https://x.com/alice/status/2040254679301718161' });
+        dom.window.setTimeout = (handler) => {
+            if (typeof handler === 'function') handler();
+            return 0;
+        };
+        Object.defineProperty(dom.window.HTMLElement.prototype, 'getClientRects', {
+            configurable: true,
+            value() {
+                return [{ bottom: 1, height: 1, left: 0, right: 1, top: 0, width: 1 }];
+            },
+        });
+        let staleDeleteClicked = false;
+        let targetCaretClicked = false;
+        dom.window.document.querySelector('[data-stale-delete]')?.addEventListener('click', () => {
+            staleDeleteClicked = true;
+        });
+        dom.window.document.querySelector('[data-target-caret]')?.addEventListener('click', () => {
+            targetCaretClicked = true;
+            const item = dom.window.document.createElement('div');
+            item.setAttribute('role', 'menuitem');
+            item.textContent = 'Pin to your profile';
+            dom.window.document.body.appendChild(item);
+        });
+        const result = await dom.window.eval(__test__.buildDeleteScript('2040254679301718161'));
+        expect(targetCaretClicked).toBe(true);
+        expect(staleDeleteClicked).toBe(false);
+        expect(result).toEqual({
+            ok: false,
+            message: 'The matched tweet menu did not contain Delete. This tweet may not belong to you.',
+        });
+    });
     it('rejects malformed or off-domain URLs with ArgumentError before navigation', async () => {
         const cmd = getRegistry().get('twitter/delete');
         expect(cmd?.func).toBeTypeOf('function');

package/clis/twitter/timeline.js

@@ -85,6 +85,8 @@ function extractTweet(result, seen) {
         likes: l.favorite_count || 0,
         retweets: l.retweet_count || 0,
         replies: l.reply_count || 0,
+        quotes: l.quote_count || 0,
+        bookmarks: l.bookmark_count || 0,
         views,
         created_at: l.created_at || '',
         url: `https://x.com/${screenName}/status/${tw.rest_id}`,
@@ -156,7 +158,7 @@ cli({
         { name: 'limit', type: 'int', default: 20, help: 'Maximum number of tweets to return (default 20).' },
         { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the timeline by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps X\'s native ordering.' },
     ],
-    columns: ['id', 'author', 'bio', 'text', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url', 'has_media', 'media_urls', 'media_posters', 'card', 'quoted_tweet'],
+    columns: ['id', 'author', 'bio', 'text', 'likes', 'retweets', 'replies', 'quotes', 'bookmarks', 'views', 'created_at', 'url', 'has_media', 'media_urls', 'media_posters', 'card', 'quoted_tweet'],
     func: async (page, kwargs) => {
         const limit = kwargs.limit || 20;
         const timelineType = kwargs.type === 'following' ? 'following' : 'for-you';

package/clis/twitter/timeline.test.js

@@ -50,6 +50,8 @@ describe('twitter timeline helpers', () => {
                                                             favorite_count: 3,
                                                             retweet_count: 2,
                                                             reply_count: 1,
+                                                            quote_count: 4,
+                                                            bookmark_count: 5,
                                                             created_at: 'now',
                                                         },
                                                         core: {
@@ -96,6 +98,8 @@ describe('twitter timeline helpers', () => {
             likes: 3,
             retweets: 2,
             replies: 1,
+            quotes: 4,
+            bookmarks: 5,
             views: 9,
             created_at: 'now',
             url: 'https://x.com/alice/status/1',

package/dist/src/browser/bridge-readiness.test.js

@@ -9,7 +9,7 @@ function status(runtimeConnected) {
         runtimeName: 'fake',
         pending: 0,
         memoryMB: 0,
-        port: 19825,
+        port: 9777,
     };
 }
 function readyHealth() {

package/dist/src/browser/bridge.d.ts

@@ -17,6 +17,7 @@ export declare class BrowserBridge implements IBrowserFactory {
         session?: string;
         idleTimeout?: number;
         contextId?: string;
+        preferredContextId?: string;
         windowMode?: 'foreground' | 'background';
         surface?: 'browser' | 'adapter';
         siteSession?: 'ephemeral' | 'persistent';

package/dist/src/browser/bridge.js

@@ -2,7 +2,7 @@
  * Browser session manager — auto-spawns daemon and provides IPage.
  */
 import { Page } from './page.js';
-import { resolveProfileContextId } from './profile.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
@@ -26,11 +26,13 @@ export class BrowserBridge {
             throw new Error('Session is closed');
         this._state = 'connecting';
         try {
-            const contextId = opts.contextId ?? resolveProfileContextId();
-            await this._ensureDaemon(opts.timeout, contextId);
+            const routing = opts.contextId || opts.preferredContextId
+                ? { contextId: opts.contextId, preferredContextId: opts.preferredContextId }
+                : profileRouteParams(resolveProfileSelection());
+            await this._ensureDaemon(opts.timeout, routing.contextId);
             if (!opts.session?.trim())
                 throw new Error('Browser session is required');
-            this._page = new Page(opts.session.trim(), opts.idleTimeout, contextId, opts.windowMode, opts.surface, opts.siteSession);
+            this._page = new Page(opts.session.trim(), opts.idleTimeout, routing.contextId, opts.windowMode, opts.surface, opts.siteSession, routing.preferredContextId);
             this._state = 'connected';
             return this._page;
         }

package/dist/src/browser/cdp.d.ts

@@ -26,6 +26,7 @@ export declare class CDPBridge implements IBrowserFactory {
         session?: string;
         cdpEndpoint?: string;
         contextId?: string;
+        preferredContextId?: string;
         idleTimeout?: number;
         windowMode?: 'foreground' | 'background';
         surface?: 'browser' | 'adapter';

package/dist/src/browser/daemon-client.d.ts

@@ -28,6 +28,7 @@ export declare function sendCommandFull(action: DaemonCommand['action'], params?
 }>;
 export declare function bindTab(session: string, opts?: {
     contextId?: string;
+    preferredContextId?: string;
     page?: string;
     index?: number;
 }): Promise<unknown>;

package/dist/src/browser/daemon-client.js

@@ -7,7 +7,7 @@ import { sleep } from '../utils.js';
 import { BrowserConnectError } from '../errors.js';
 import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT } from '../daemon-utils.js';
 import { classifyBrowserError } from './errors.js';
-import { resolveProfileContextId } from './profile.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './config.js';
 import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
 import { isPreDispatchError } from './bridge-readiness.js';
@@ -90,7 +90,11 @@ async function sendCommandRaw(action, params) {
     const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
         ? rawWindowMode
         : undefined;
-    const contextId = params.contextId ?? resolveProfileContextId();
+    const routing = params.contextId || params.preferredContextId
+        ? { contextId: params.contextId, preferredContextId: params.preferredContextId }
+        : profileRouteParams(resolveProfileSelection());
+    const contextId = routing.contextId;
+    const preferredContextId = routing.preferredContextId;
     const windowMode = params.windowMode ?? envWindowMode;
     let id = generateId();
     let ensureUsed = false;
@@ -115,6 +119,7 @@ async function sendCommandRaw(action, params) {
             timeout: timeoutSeconds,
             deadlineAt,
             ...(contextId && { contextId }),
+            ...(preferredContextId && { preferredContextId }),
             ...(windowMode && { windowMode }),
         };
         try {

package/dist/src/browser/daemon-client.test.js

@@ -22,7 +22,7 @@ describe('daemon-client', () => {
             runtimeVersion: '1.2.3',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         const fetchMock = vi.mocked(fetch);
         fetchMock.mockResolvedValue({
@@ -60,7 +60,7 @@ describe('daemon-client', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 16,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -78,7 +78,7 @@ describe('daemon-client', () => {
             runtimeVersion: '1.2.3',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -100,7 +100,7 @@ describe('daemon-client', () => {
             ],
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -119,32 +119,12 @@ describe('daemon-client', () => {
                 runtimeName: 'fake',
                 pending: 0,
                 memoryMB: 1,
-                port: 19825,
+                port: 9777,
             }),
         });
         await fetchDaemonStatus({ contextId: 'work' });
         expect(vi.mocked(fetch).mock.calls[0][0]).toMatch(/\/status\?contextId=work$/);
     });
-    it('rejects WEBCMD_DAEMON_PORT so CLI and extension cannot split bridge ports', async () => {
-        vi.resetModules();
-        vi.stubEnv('WEBCMD_DAEMON_PORT', '19999');
-        vi.mocked(fetch).mockResolvedValue({
-            ok: true,
-            json: () => Promise.resolve({
-                ok: true,
-                pid: 1,
-                uptime: 0,
-                runtimeConnected: true,
-                runtimeName: 'fake',
-                pending: 0,
-                memoryMB: 1,
-                port: 19825,
-            }),
-        });
-        const freshClient = await import('./daemon-client.js');
-        await expect(freshClient.fetchDaemonStatus()).rejects.toThrow('WEBCMD_DAEMON_PORT is no longer supported');
-        expect(vi.mocked(fetch)).not.toHaveBeenCalled();
-    });
     it('sendCommand includes the current pid in generated command ids', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -162,7 +142,7 @@ describe('daemon-client', () => {
         expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
         expect(ids[0]).not.toBe(ids[1]);
     });
-    it('sendCommand forwards WEBCMD_PROFILE as command contextId', async () => {
+    it('sendCommand forwards WEBCMD_PROFILE as a hard contextId requirement', async () => {
         vi.stubEnv('WEBCMD_PROFILE', 'work');
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -172,6 +152,29 @@ describe('daemon-client', () => {
         await sendCommand('exec', { code: '1 + 1' });
         const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
         expect(body.contextId).toBe('work');
+        expect(body.preferredContextId).toBeUndefined();
+    });
+    it('sendCommand forwards the config default as preferredContextId', async () => {
+        const fs = await import('node:fs');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-dc-profile-'));
+        fs.writeFileSync(path.join(configDir, 'browser-profiles.json'), JSON.stringify({ version: 1, aliases: {}, defaultContextId: 'profile-default' }));
+        vi.stubEnv('WEBCMD_CONFIG_DIR', configDir);
+        vi.stubEnv('WEBCMD_PROFILE', '');
+        try {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+            });
+            await sendCommand('exec', { code: '1 + 1' });
+            const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+            expect(body.contextId).toBeUndefined();
+            expect(body.preferredContextId).toBe('profile-default');
+        }
+        finally {
+            fs.rmSync(configDir, { recursive: true, force: true });
+        }
     });
     it('sendCommand uses explicit windowMode before WEBCMD_WINDOW env fallback', async () => {
         vi.stubEnv('WEBCMD_WINDOW', 'foreground');
@@ -230,7 +233,7 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,
@@ -269,13 +272,13 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,
         });
         const refused = new TypeError('fetch failed');
-        refused.cause = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:19825'), { code: 'ECONNREFUSED' });
+        refused.cause = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:9777'), { code: 'ECONNREFUSED' });
         const fetchMock = vi.mocked(fetch);
         fetchMock
             .mockRejectedValueOnce(refused)
@@ -300,7 +303,7 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,

package/dist/src/browser/daemon-transport.js

@@ -1,20 +1,8 @@
-import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT, unsupportedDaemonPortEnvMessage } from '../constants.js';
+import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT } from '../constants.js';
 const DAEMON_PORT = DEFAULT_DAEMON_PORT;
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const WEBCMD_HEADERS = { [DAEMON_HEADER_NAME]: '1' };
-class UnsupportedDaemonPortEnvError extends Error {
-    constructor(value) {
-        super(unsupportedDaemonPortEnvMessage(value));
-        this.name = 'UnsupportedDaemonPortEnvError';
-    }
-}
-function assertSupportedDaemonPortEnv() {
-    const value = process.env.WEBCMD_DAEMON_PORT;
-    if (value !== undefined && value !== '')
-        throw new UnsupportedDaemonPortEnvError(value);
-}
 export async function requestDaemon(pathname, init) {
-    assertSupportedDaemonPortEnv();
     const { timeout = 2000, headers, ...rest } = init ?? {};
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
@@ -37,9 +25,7 @@ export async function fetchDaemonStatus(opts) {
             return null;
         return await res.json();
     }
-    catch (err) {
-        if (err instanceof UnsupportedDaemonPortEnvError)
-            throw err;
+    catch {
         return null;
     }
 }
@@ -60,9 +46,7 @@ export async function requestDaemonShutdown(opts) {
         const res = await requestDaemon('/shutdown', { method: 'POST', timeout: opts?.timeout ?? 5000 });
         return res.ok;
     }
-    catch (err) {
-        if (err instanceof UnsupportedDaemonPortEnvError)
-            throw err;
+    catch {
         return false;
     }
 }

package/dist/src/browser/page.d.ts

@@ -19,8 +19,9 @@ export declare class Page extends BasePage {
     private readonly windowMode?;
     private readonly surface;
     private readonly siteSession?;
+    readonly preferredContextId?: string | undefined;
     private readonly _idleTimeout;
-    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined);
+    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined, preferredContextId?: string | undefined);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;

package/dist/src/browser/page.js

@@ -40,14 +40,16 @@ export class Page extends BasePage {
     windowMode;
     surface;
     siteSession;
+    preferredContextId;
     _idleTimeout;
-    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession) {
+    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession, preferredContextId) {
         super();
         this.session = session;
         this.contextId = contextId;
         this.windowMode = windowMode;
         this.surface = surface;
         this.siteSession = siteSession;
+        this.preferredContextId = preferredContextId;
         this._idleTimeout = idleTimeout;
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
@@ -60,6 +62,7 @@ export class Page extends BasePage {
             session: this.session,
             surface: this.surface,
             ...(this.contextId && { contextId: this.contextId }),
+            ...(this.preferredContextId && { preferredContextId: this.preferredContextId }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
             ...(this.siteSession && { siteSession: this.siteSession }),
@@ -71,6 +74,7 @@ export class Page extends BasePage {
             session: this.session,
             surface: this.surface,
             ...(this.contextId && { contextId: this.contextId }),
+            ...(this.preferredContextId && { preferredContextId: this.preferredContextId }),
             ...(this._page !== undefined && { page: this._page }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),

package/dist/src/browser/profile.d.ts

@@ -8,6 +8,15 @@ export declare function normalizeContextId(value: string | undefined | null): st
 export declare function emptyProfileConfig(): ProfileConfig;
 export declare function loadProfileConfig(): ProfileConfig;
 export declare function saveProfileConfig(config: ProfileConfig): void;
+export type ProfileSelection = {
+    contextId: string;
+    source: 'explicit' | 'preferred';
+};
+export declare function resolveProfileSelection(profile?: string): ProfileSelection | undefined;
+export declare function profileRouteParams(selection: ProfileSelection | undefined): {
+    contextId?: string;
+    preferredContextId?: string;
+};
 export declare function resolveProfileContextId(profile?: string): string | undefined;
 export declare function aliasForContextId(config: ProfileConfig, contextId: string): string | undefined;
 export declare function renameProfile(contextId: string, alias: string): ProfileConfig;

package/dist/src/browser/profile.js

@@ -42,14 +42,25 @@ export function saveProfileConfig(config) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
-export function resolveProfileContextId(profile) {
+export function resolveProfileSelection(profile) {
     const config = loadProfileConfig();
-    const requested = normalizeContextId(profile)
-        ?? normalizeContextId(process.env[`${ENV_PREFIX}_PROFILE`])
-        ?? normalizeContextId(config.defaultContextId);
-    if (!requested)
-        return undefined;
-    return config.aliases[requested] ?? requested;
+    const explicit = normalizeContextId(profile) ?? normalizeContextId(process.env[`${ENV_PREFIX}_PROFILE`]);
+    if (explicit)
+        return { contextId: config.aliases[explicit] ?? explicit, source: 'explicit' };
+    const preferred = normalizeContextId(config.defaultContextId);
+    if (preferred)
+        return { contextId: config.aliases[preferred] ?? preferred, source: 'preferred' };
+    return undefined;
+}
+export function profileRouteParams(selection) {
+    if (!selection)
+        return {};
+    return selection.source === 'explicit'
+        ? { contextId: selection.contextId }
+        : { preferredContextId: selection.contextId };
+}
+export function resolveProfileContextId(profile) {
+    return resolveProfileSelection(profile)?.contextId;
 }
 export function aliasForContextId(config, contextId) {
     for (const [alias, id] of Object.entries(config.aliases)) {

package/dist/src/browser/profile.test.d.ts

@@ -0,0 +1 @@
+export {};