chrome-control-proxy 1.0.0 → 1.0.2

package/README.md

@@ -26,6 +26,43 @@ ccp status   # 需先启动服务，否则显示 unreachable
 
 ---
 
+## 发布
+
+升级版本号：
+
+```bash
+npm run release:patch
+# 或
+npm run release:minor
+# 或
+npm run release:major
+```
+
+说明：
+
+- 会同步更新 `package.json` 与 `chrome-control-proxy/SKILL.md` 的版本号
+- 不会自动修改 `CHANGELOG.md`，升级后按实际改动手动补充
+
+发布到 npm：
+
+```bash
+npm run publish:npm
+```
+
+发布到 ClawHub：
+
+```bash
+npm run publish:clawhub
+```
+
+说明：
+
+- `publish:npm` 等价于执行 `npm publish`
+- `publish:clawhub` 会打开 [ClawHub 导入页](https://clawhub.ai/import)，并在终端输出仓库地址与 Skill 目录：`chrome-control-proxy/`
+- 发布 ClawHub Skill 时，仓库地址使用：`https://github.com/zhengxiangqi/chrome-control-proxy`
+
+---
+
 ## CLI：`ccp`
 
 管理 **HTTP 服务进程**（`node index.js`），不是替代 `curl` 调接口。
@@ -87,9 +124,10 @@ node index.js
 |------|------|------|
 | `/playwright/status` | GET | CDP 是否可连 |
 | `/playwright/page-dom` | POST | 页面快照：HTML / innerText / a11y / **Playwright 专用可交互列表** |
+| `/playwright/pipeline` | POST | 单次请求串联导航、前后快照与脚本执行 |
 | `/playwright/run` | POST | 在 VM 中执行用户脚本（注入 `page`、`context`、`browser`） |
 
-`POST /playwright/page-dom` 与 `POST /playwright/run` 在服务端 **串行排队**，避免多请求抢同一浏览器。
+`POST /playwright/page-dom`、`POST /playwright/pipeline` 与 `POST /playwright/run` 在服务端 **串行排队**，避免多请求抢同一浏览器。
 
 ---
 
@@ -113,13 +151,24 @@ curl -s http://host.docker.internal:3333/health
 
 ## `POST /playwright/page-dom` 要点
 
+- 默认 `waitUntil` 为 **`domcontentloaded`**，更适合页面分析；若必须等待完整资源再改成 `load` / `networkidle`。
 - **`includeHtml: false`**：不返回整页 HTML，利于降 token。
 - **`includePlaywrightSnapshot: true`**：返回 `playwright.targets[]`（含 **`suggestedLocator`**），便于生成脚本。
-- **`selector`**：只截取子树。
+- **`playwrightSnapshotMode: "compact"`**：只返回更精简的可交互信息，适合先给 OpenClaw 做定位分析。
+- **`selector`**：只截取子树，优先限制到主内容区或弹窗根节点。
 - **`includeInnerText` / `includeAccessibility`**：按需打开。
 
 ---
 
+## `POST /playwright/pipeline` 要点
+
+- 用于一次请求内完成：**导航 -> 分析前快照 -> 执行脚本 -> 分析后快照**。
+- 适合“操作后还要再拿页面结构”的场景，减少额外 HTTP 往返。
+- 外层支持 `url` / `waitUntil` / `timeout` / `target`；快照部分用 `beforePageDom`、`afterPageDom` 传入，结构与 `page-dom` 参数基本一致。
+- 若只需要执行脚本，不必改成 `pipeline`，继续用 `/playwright/run` 即可。
+
+---
+
 ## `POST /playwright/run` 要点
 
 - 脚本为 **async 函数体**，可 `await`、`return`；返回值会尽量 JSON 序列化后返回。
@@ -138,4 +187,8 @@ curl -s http://host.docker.internal:3333/health
 
 ## OpenClaw 集成说明
 
-更完整的调用顺序、踩坑说明见仓库内 **`host-chrome-control/SKILL.md`**（随代码维护；**不会**打进 `npm pack` 的默认包文件，clone 仓库即可见）。
+更完整的调用顺序、踩坑说明见仓库内 **`chrome-control-proxy/SKILL.md`**（随代码维护；**不会**打进 `npm pack` 的默认包文件，clone 仓库即可见）。
+
+### 通过 ClawHub 安装 Skill
+
+在 [ClawHub](https://clawhub.ai) 搜索 **`chrome-control-proxy`** 并一键安装，OpenClaw 即可加载该 Skill，获得完整的调用指南与最佳实践提示。

package/index.js

@@ -13,6 +13,7 @@ const {
   enqueuePlaywright,
   getPageDomPayload,
   runPlaywrightUserScript,
+  runPlaywrightPipeline,
   packScriptReturnValue,
 } = require('./lib/playwright-controller');
 
@@ -131,7 +132,7 @@ app.post('/playwright/page-dom', async (req, res) => {
     const payload = await enqueuePlaywright(() =>
       getPageDomPayload({
         url: b.url,
-        waitUntil: b.waitUntil || 'load',
+        waitUntil: b.waitUntil || 'domcontentloaded',
         timeout: b.timeout ?? 30000,
         target: b.target || 'first',
         maxHtmlChars: b.maxHtmlChars,
@@ -144,6 +145,7 @@ app.post('/playwright/page-dom', async (req, res) => {
         includeAccessibility: Boolean(b.includeAccessibility),
         includePlaywrightSnapshot: Boolean(b.includePlaywrightSnapshot),
         maxPlaywrightTargets: b.maxPlaywrightTargets,
+        playwrightSnapshotMode: b.playwrightSnapshotMode,
       }),
     );
     res.json({
@@ -156,6 +158,77 @@ app.post('/playwright/page-dom', async (req, res) => {
   }
 });
 
+app.post('/playwright/pipeline', async (req, res) => {
+  try {
+    const b = req.body || {};
+    const hasScript = typeof b.script === 'string' && b.script !== '';
+    const hasBefore = Boolean(b.beforePageDom);
+    const hasAfter = Boolean(b.afterPageDom);
+    if (!hasScript && !hasBefore && !hasAfter) {
+      log.warn('http', 'POST /playwright/pipeline rejected: empty pipeline');
+      return res.status(400).json({
+        ok: false,
+        error: 'pipeline requires at least one of beforePageDom, script, afterPageDom',
+      });
+    }
+    log.info('http', 'POST /playwright/pipeline', {
+      hasScript,
+      hasBefore,
+      hasAfter,
+    });
+    const payload = await enqueuePlaywright(() =>
+      runPlaywrightPipeline({
+        url: b.url,
+        waitUntil: b.waitUntil || 'domcontentloaded',
+        timeout: b.timeout ?? 30000,
+        target: b.target || 'first',
+        script: hasScript ? String(b.script) : undefined,
+        scriptTimeout: b.scriptTimeout ?? PLAYWRIGHT_RUN_DEFAULT_MS,
+        beforePageDom: hasBefore
+          ? {
+              ...b.beforePageDom,
+              waitUntil: undefined,
+              url: undefined,
+              timeout: b.beforePageDom.timeout ?? b.timeout ?? 30000,
+              includeHtml: b.beforePageDom.includeHtml !== false,
+              includeInnerText: Boolean(b.beforePageDom.includeInnerText),
+              includeAccessibility: Boolean(b.beforePageDom.includeAccessibility),
+              includePlaywrightSnapshot: Boolean(b.beforePageDom.includePlaywrightSnapshot),
+            }
+          : null,
+        afterPageDom: hasAfter
+          ? {
+              ...b.afterPageDom,
+              waitUntil: undefined,
+              url: undefined,
+              timeout: b.afterPageDom.timeout ?? b.timeout ?? 30000,
+              includeHtml: b.afterPageDom.includeHtml !== false,
+              includeInnerText: Boolean(b.afterPageDom.includeInnerText),
+              includeAccessibility: Boolean(b.afterPageDom.includeAccessibility),
+              includePlaywrightSnapshot: Boolean(b.afterPageDom.includePlaywrightSnapshot),
+            }
+          : null,
+      }),
+    );
+    res.json({
+      ok: true,
+      step: 'pipeline',
+      ...payload,
+    });
+  } catch (err) {
+    if (err.code === 'BAD_SCRIPT' || err.code === 'SCRIPT_TOO_LARGE') {
+      log.warn('http', `playwright/pipeline client error ${err.code}`, err.message);
+      return res.status(400).json({
+        ok: false,
+        error: err.message,
+        code: err.code,
+        ...(err.currentUrl && { currentUrl: err.currentUrl }),
+      });
+    }
+    sendPlaywrightError(res, err);
+  }
+});
+
 app.post('/playwright/run', async (req, res) => {
   try {
     const { script, url, waitUntil, timeout, target, scriptTimeout } = req.body || {};

package/lib/playwright-controller.js

@@ -99,15 +99,20 @@ function truncateJsonValue(obj, maxChars) {
   };
 }
 
+function getSnapshotMode(mode) {
+  return mode === 'compact' ? 'compact' : 'full';
+}
+
 async function collectPlaywrightInteractiveSnapshot(page, options) {
-  const { selector, maxItems } = options;
+  const { selector, maxItems, mode } = options;
   const maxN = Math.min(
     Math.max(1, Number(maxItems) || PLAYWRIGHT_SNAPSHOT_MAX_ITEMS),
     2000,
   );
+  const snapshotMode = getSnapshotMode(mode);
 
   return page.evaluate(
-    ({ rootSelector, maxCount }) => {
+    ({ rootSelector, maxCount, snapshotMode }) => {
       const root = rootSelector ? document.querySelector(rootSelector) : document.body;
       if (!root) {
         return {
@@ -115,6 +120,7 @@ async function collectPlaywrightInteractiveSnapshot(page, options) {
           targets: [],
           visibleTotal: 0,
           listTruncated: false,
+          mode: snapshotMode,
         };
       }
 
@@ -210,8 +216,21 @@ async function collectPlaywrightInteractiveSnapshot(page, options) {
       const targets = slice.map((el) => {
         const tag = el.tagName.toLowerCase();
         const typeAttr = el.getAttribute('type');
-        return {
+        const base = {
           tag,
+          text: (el.innerText || el.textContent || '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 160),
+          placeholder: el.getAttribute('placeholder'),
+          role: el.getAttribute('role'),
+          suggestedLocator: suggestLocator(el),
+        };
+        if (snapshotMode === 'compact') {
+          return base;
+        }
+        return {
+          ...base,
           type: typeAttr ? typeAttr.toLowerCase() : null,
           name: el.getAttribute('name'),
           id: el.id || null,
@@ -220,17 +239,10 @@ async function collectPlaywrightInteractiveSnapshot(page, options) {
             el.getAttribute('data-test-id') ||
             el.getAttribute('data-cy') ||
             null,
-          placeholder: el.getAttribute('placeholder'),
           ariaLabel: el.getAttribute('aria-label'),
-          role: el.getAttribute('role'),
           href: el.getAttribute('href') ? el.getAttribute('href').slice(0, 400) : null,
           disabled:
             el.disabled === true || String(el.getAttribute('aria-disabled')).toLowerCase() === 'true',
-          text: (el.innerText || el.textContent || '')
-            .trim()
-            .replace(/\s+/g, ' ')
-            .slice(0, 160),
-          suggestedLocator: suggestLocator(el),
         };
       });
 
@@ -239,9 +251,10 @@ async function collectPlaywrightInteractiveSnapshot(page, options) {
         visibleTotal: visibleEls.length,
         listTruncated,
         maxCount,
+        mode: snapshotMode,
       };
     },
-    { rootSelector: selector || null, maxCount: maxN },
+    { rootSelector: selector || null, maxCount: maxN, snapshotMode },
   );
 }
 
@@ -367,6 +380,173 @@ function packScriptReturnValue(value) {
   }
 }
 
+function assertValidUserScript(userScript) {
+  if (typeof userScript !== 'string') {
+    const err = new Error('script must be a string');
+    err.code = 'BAD_SCRIPT';
+    throw err;
+  }
+  if (userScript.length > PLAYWRIGHT_RUN_MAX_SCRIPT_CHARS) {
+    const err = new Error(`script exceeds ${PLAYWRIGHT_RUN_MAX_SCRIPT_CHARS} characters`);
+    err.code = 'SCRIPT_TOO_LARGE';
+    throw err;
+  }
+}
+
+async function collectHtmlPayload(page, locator, maxHtmlChars, includeHtml) {
+  if (!includeHtml) {
+    return {
+      html: null,
+      htmlLength: null,
+      truncated: null,
+    };
+  }
+
+  const htmlFull = locator
+    ? await locator.evaluate((el) => el.outerHTML)
+    : await page.content();
+  const maxH = Math.min(
+    Number(maxHtmlChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+  );
+  const truncatedHtml = truncateStr(htmlFull, maxH);
+  return {
+    html: truncatedHtml.text,
+    htmlLength: htmlFull.length,
+    truncated: truncatedHtml.truncated,
+  };
+}
+
+async function collectInnerTextPayload(page, locator, maxTextChars, includeInnerText) {
+  if (!includeInnerText) {
+    return {};
+  }
+
+  const textFull = locator ? await locator.innerText() : await page.innerText('body');
+  const maxT = Math.min(
+    Number(maxTextChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+  );
+  const truncatedText = truncateStr(textFull, maxT);
+  return {
+    innerText: truncatedText.text,
+    innerTextLength: textFull.length,
+    innerTextTruncated: truncatedText.truncated,
+  };
+}
+
+async function collectAccessibilityPayload(page, locator, maxA11yChars, includeAccessibility) {
+  if (!includeAccessibility) {
+    return {};
+  }
+
+  const rootHandle = locator ? await locator.elementHandle() : null;
+  const snap = await page.accessibility.snapshot({ root: rootHandle || undefined });
+  const maxA = Math.min(
+    Number(maxA11yChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+  );
+  const packed = truncateJsonValue(snap, maxA);
+  if (packed.truncated) {
+    return {
+      accessibility: null,
+      accessibilityTruncated: true,
+      accessibilityJsonLength: packed.jsonLength,
+      accessibilityPreview: packed.preview,
+    };
+  }
+  return {
+    accessibility: packed.value,
+    accessibilityTruncated: false,
+    accessibilityJsonLength: packed.jsonLength,
+  };
+}
+
+async function collectPlaywrightSnapshotPayload(page, options) {
+  const {
+    selector,
+    maxPlaywrightTargets,
+    maxPlaywrightJsonChars,
+    includePlaywrightSnapshot,
+    playwrightSnapshotMode,
+  } = options;
+
+  if (!includePlaywrightSnapshot) {
+    return {};
+  }
+
+  const snapshot = await collectPlaywrightInteractiveSnapshot(page, {
+    selector,
+    maxItems: maxPlaywrightTargets,
+    mode: playwrightSnapshotMode,
+  });
+  const maxP = Math.min(
+    Number(maxPlaywrightJsonChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+  );
+  const packed = truncateJsonValue(snapshot, maxP);
+  if (packed.truncated) {
+    return {
+      playwright: null,
+      playwrightTruncated: true,
+      playwrightJsonLength: packed.jsonLength,
+      playwrightPreview: packed.preview,
+    };
+  }
+  return {
+    playwright: packed.value,
+    playwrightTruncated: false,
+    playwrightJsonLength: packed.jsonLength,
+  };
+}
+
+async function buildPageDomPayloadFromPage(page, options) {
+  const {
+    timeout = 30000,
+    maxHtmlChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    maxTextChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    maxA11yChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    maxPlaywrightJsonChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
+    selector,
+    includeHtml = true,
+    includeInnerText = false,
+    includeAccessibility = false,
+    includePlaywrightSnapshot = false,
+    maxPlaywrightTargets,
+    playwrightSnapshotMode = 'full',
+  } = options;
+
+  const locator = selector ? page.locator(selector).first() : null;
+  if (locator) {
+    await locator.waitFor({ state: 'attached', timeout });
+  }
+
+  const currentUrl = page.url();
+  const [title, htmlPayload, innerTextPayload, accessibilityPayload, snapshotPayload] = await Promise.all([
+    page.title(),
+    collectHtmlPayload(page, locator, maxHtmlChars, includeHtml),
+    collectInnerTextPayload(page, locator, maxTextChars, includeInnerText),
+    collectAccessibilityPayload(page, locator, maxA11yChars, includeAccessibility),
+    collectPlaywrightSnapshotPayload(page, {
+      selector,
+      maxPlaywrightTargets,
+      maxPlaywrightJsonChars,
+      includePlaywrightSnapshot,
+      playwrightSnapshotMode,
+    }),
+  ]);
+
+  return {
+    currentUrl,
+    title,
+    selector: selector || null,
+    ...htmlPayload,
+    ...innerTextPayload,
+    ...accessibilityPayload,
+    ...snapshotPayload,
+  };
+}
+
 async function getPageDomPayload(options) {
   let page;
   const tStart = Date.now();
@@ -376,16 +556,12 @@ async function getPageDomPayload(options) {
       waitUntil = 'load',
       timeout = 30000,
       target = 'first',
-      maxHtmlChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      maxTextChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      maxA11yChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      maxPlaywrightJsonChars = PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
       selector,
       includeHtml = true,
       includeInnerText = false,
       includeAccessibility = false,
       includePlaywrightSnapshot = false,
-      maxPlaywrightTargets,
+      playwrightSnapshotMode = 'full',
     } = options;
 
     log.info('playwright', 'page-dom start', {
@@ -396,6 +572,7 @@ async function getPageDomPayload(options) {
       includeInnerText,
       includeAccessibility,
       includePlaywrightSnapshot,
+      playwrightSnapshotMode: getSnapshotMode(playwrightSnapshotMode),
       selector: selector || null,
     });
 
@@ -406,110 +583,7 @@ async function getPageDomPayload(options) {
       target,
     });
 
-    const title = await page.title();
-    const currentUrl = page.url();
-
-    if (selector) {
-      await page.locator(selector).first().waitFor({ state: 'attached', timeout });
-    }
-
-    const payload = {
-      currentUrl,
-      title,
-      selector: selector || null,
-    };
-
-    if (includeHtml) {
-      let htmlFull;
-      if (selector) {
-        htmlFull = await page.locator(selector).first().evaluate((el) => el.outerHTML);
-      } else {
-        htmlFull = await page.content();
-      }
-
-      const htmlLength = htmlFull.length;
-      const maxH = Math.min(
-        Number(maxHtmlChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-        PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      );
-      let html = htmlFull;
-      let truncated = false;
-      if (html.length > maxH) {
-        html = html.slice(0, maxH);
-        truncated = true;
-      }
-
-      payload.html = html;
-      payload.htmlLength = htmlLength;
-      payload.truncated = truncated;
-    } else {
-      payload.html = null;
-      payload.htmlLength = null;
-      payload.truncated = null;
-    }
-
-    if (includeInnerText) {
-      let textFull;
-      if (selector) {
-        textFull = await page.locator(selector).first().innerText();
-      } else {
-        textFull = await page.innerText('body');
-      }
-      const maxT = Math.min(
-        Number(maxTextChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-        PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      );
-      const tt = truncateStr(textFull, maxT);
-      payload.innerText = tt.text;
-      payload.innerTextLength = textFull.length;
-      payload.innerTextTruncated = tt.truncated;
-    }
-
-    if (includeAccessibility) {
-      let rootHandle = null;
-      if (selector) {
-        rootHandle = await page.locator(selector).first().elementHandle();
-      }
-      const snap = await page.accessibility.snapshot({ root: rootHandle || undefined });
-      const maxA = Math.min(
-        Number(maxA11yChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-        PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      );
-      const packed = truncateJsonValue(snap, maxA);
-      if (packed.truncated) {
-        payload.accessibility = null;
-        payload.accessibilityTruncated = true;
-        payload.accessibilityJsonLength = packed.jsonLength;
-        payload.accessibilityPreview = packed.preview;
-      } else {
-        payload.accessibility = packed.value;
-        payload.accessibilityTruncated = false;
-        payload.accessibilityJsonLength = packed.jsonLength;
-      }
-    }
-
-    if (includePlaywrightSnapshot) {
-      const pw = await collectPlaywrightInteractiveSnapshot(page, {
-        selector,
-        maxItems: maxPlaywrightTargets,
-      });
-      const maxP = Math.min(
-        Number(maxPlaywrightJsonChars) || PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-        PLAYWRIGHT_PAGE_DOM_MAX_CHARS,
-      );
-      const packed = truncateJsonValue(pw, maxP);
-      if (packed.truncated) {
-        payload.playwright = null;
-        payload.playwrightTruncated = true;
-        payload.playwrightJsonLength = packed.jsonLength;
-        payload.playwrightPreview = packed.preview;
-      } else {
-        payload.playwright = packed.value;
-        payload.playwrightTruncated = false;
-        payload.playwrightJsonLength = packed.jsonLength;
-      }
-    }
-
+    const payload = await buildPageDomPayloadFromPage(page, options);
     log.info('playwright', `page-dom done ${Date.now() - tStart}ms`, {
       title: payload.title,
       currentUrl: payload.currentUrl,
@@ -522,6 +596,30 @@ async function getPageDomPayload(options) {
   }
 }
 
+async function executePlaywrightUserScript(browser, context, page, userScript, scriptTimeout) {
+  const sandbox = vm.createContext({
+    browser,
+    context,
+    page,
+    console,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+  });
+
+  const wrapped = `(async () => {\n${userScript}\n})()`;
+  const scriptVm = new vm.Script(wrapped, { filename: 'playwright-run-user.js' });
+  const completion = scriptVm.runInContext(sandbox, { displayErrors: true });
+  const run = async () => {
+    if (completion && typeof completion.then === 'function') {
+      return completion;
+    }
+    return completion;
+  };
+  return sleepRace(run(), scriptTimeout, 'playwright script');
+}
+
 async function runPlaywrightUserScript(userScript, options) {
   let page;
   const tStart = Date.now();
@@ -534,16 +632,7 @@ async function runPlaywrightUserScript(userScript, options) {
       scriptTimeout = PLAYWRIGHT_RUN_DEFAULT_MS,
     } = options;
 
-    if (typeof userScript !== 'string') {
-      const err = new Error('script must be a string');
-      err.code = 'BAD_SCRIPT';
-      throw err;
-    }
-    if (userScript.length > PLAYWRIGHT_RUN_MAX_SCRIPT_CHARS) {
-      const err = new Error(`script exceeds ${PLAYWRIGHT_RUN_MAX_SCRIPT_CHARS} characters`);
-      err.code = 'SCRIPT_TOO_LARGE';
-      throw err;
-    }
+    assertValidUserScript(userScript);
 
     log.info('playwright', 'run script start', {
       scriptChars: userScript.length,
@@ -560,39 +649,83 @@ async function runPlaywrightUserScript(userScript, options) {
       target: target || 'first',
     });
     page = resolvedPage;
+    const scriptReturn = await executePlaywrightUserScript(browser, context, page, userScript, scriptTimeout);
+
+    log.info('playwright', `run script done ${Date.now() - tStart}ms`, {
+      currentUrl: page.url(),
+      hasReturn: scriptReturn !== undefined,
+    });
+    return { browser, context, page, result: scriptReturn };
+  } catch (err) {
+    err.currentUrl = err.currentUrl || tryPageUrl(page);
+    log.error('playwright', `run script failed ${Date.now() - tStart}ms`, err);
+    throw err;
+  }
+}
+
+async function runPlaywrightPipeline(options) {
+  let page;
+  const tStart = Date.now();
+  try {
+    const {
+      url,
+      waitUntil,
+      timeout,
+      target,
+      beforePageDom,
+      afterPageDom,
+      script,
+      scriptTimeout = PLAYWRIGHT_RUN_DEFAULT_MS,
+    } = options;
 
-    const sandbox = vm.createContext({
-      browser,
-      context,
-      page,
-      console,
-      setTimeout,
-      clearTimeout,
-      setInterval,
-      clearInterval,
+    log.info('playwright', 'pipeline start', {
+      outerUrl: url || null,
+      waitUntil: waitUntil || 'load',
+      target: target || 'first',
+      hasBeforePageDom: Boolean(beforePageDom),
+      hasScript: typeof script === 'string' && script !== '',
+      hasAfterPageDom: Boolean(afterPageDom),
     });
 
-    const wrapped = `(async () => {\n${userScript}\n})()`;
-    const scriptVm = new vm.Script(wrapped, { filename: 'playwright-run-user.js' });
+    const { browser, context, page: resolvedPage } = await resolveBrowserContextPage({
+      url,
+      waitUntil: waitUntil || 'load',
+      timeout: timeout ?? 30000,
+      target: target || 'first',
+    });
+    page = resolvedPage;
 
-    const completion = scriptVm.runInContext(sandbox, { displayErrors: true });
-    const run = async () => {
-      if (completion && typeof completion.then === 'function') {
-        return completion;
-      }
-      return completion;
+    const response = {
+      currentUrl: page.url(),
     };
 
-    const scriptReturn = await sleepRace(run(), scriptTimeout, 'playwright script');
+    if (beforePageDom) {
+      response.before = await buildPageDomPayloadFromPage(page, beforePageDom);
+      response.currentUrl = page.url();
+    }
 
-    log.info('playwright', `run script done ${Date.now() - tStart}ms`, {
-      currentUrl: page.url(),
-      hasReturn: scriptReturn !== undefined,
+    if (typeof script === 'string' && script !== '') {
+      assertValidUserScript(script);
+      const scriptResult = await executePlaywrightUserScript(browser, context, page, script, scriptTimeout);
+      Object.assign(response, packScriptReturnValue(scriptResult));
+      response.currentUrl = page.url();
+    }
+
+    if (afterPageDom) {
+      response.after = await buildPageDomPayloadFromPage(page, afterPageDom);
+      response.currentUrl = page.url();
+    }
+
+    log.info('playwright', `pipeline done ${Date.now() - tStart}ms`, {
+      currentUrl: response.currentUrl,
+      hasBefore: Boolean(response.before),
+      hasAfter: Boolean(response.after),
+      hasReturnValue: Boolean(response.hasReturnValue),
     });
-    return { browser, context, page, result: scriptReturn };
+    return response;
   } catch (err) {
     err.currentUrl = err.currentUrl || tryPageUrl(page);
-    log.error('playwright', `run script failed ${Date.now() - tStart}ms`, err);
+    log.error('playwright', `pipeline failed ${Date.now() - tStart}ms`, err);
     throw err;
   }
 }
@@ -605,5 +738,6 @@ module.exports = {
   enqueuePlaywright,
   getPageDomPayload,
   runPlaywrightUserScript,
+  runPlaywrightPipeline,
   packScriptReturnValue,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-control-proxy",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Chrome CDP control proxy: HTTP API for browser lifecycle and Playwright automation",
   "main": "index.js",
   "bin": {
@@ -17,6 +17,11 @@
   "scripts": {
     "start": "node index.js",
     "ccp": "node bin/ccp.js",
+    "release:patch": "node scripts/release-version.js patch",
+    "release:minor": "node scripts/release-version.js minor",
+    "release:major": "node scripts/release-version.js major",
+    "publish:npm": "npm publish",
+    "publish:clawhub": "node -e \"const url='https://clawhub.ai/import'; const repo='https://github.com/zhengxiangqi/chrome-control-proxy'; const dir='chrome-control-proxy/'; console.log('Open ClawHub import page: ' + url); console.log('Repository: ' + repo); console.log('Skill directory: ' + dir); const { spawn } = require('child_process'); const platform = process.platform; const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open'; const args = platform === 'win32' ? ['/c', 'start', '', url] : [url]; const child = spawn(cmd, args, { stdio: 'ignore', detached: true }); child.on('error', () => {}); child.unref();\"",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [