cdp-skill 1.0.18 → 1.0.20

package/EXAMPLES.md

@@ -68,7 +68,7 @@ Close when done:
   },
   "screenshot": "/tmp/cdp-skill/t1.after.png",
   "fullSnapshot": "/tmp/cdp-skill/t1.after.yaml",
-  "viewportSnapshot": "- heading \"Title\" [level=1]\n- button \"Submit\" [ref=f0s1e1]\n...",
+  "viewportSnapshot": "/tmp/cdp-skill/t1.viewport.yaml",
   "steps": [{"action": "goto", "status": "ok"}]
 }
 ```
@@ -130,7 +130,7 @@ Close when done:
   },
   "screenshot": "/tmp/cdp-skill/t1.after.png",
   "fullSnapshot": "/tmp/cdp-skill/t1.after.yaml",
-  "viewportSnapshot": "- heading \"New Page\" [level=1]\n- button \"Submit\" [ref=f0s1e1]\n...",
+  "viewportSnapshot": "/tmp/cdp-skill/t1.viewport.yaml",
   "steps": [{"action": "click", "status": "ok"}]
 }
 ```

package/SKILL.md

@@ -33,12 +33,12 @@ Tab IDs (t1, t2, ...) persist across CLI invocations. Chrome auto-launches if no
 **Output fields:**
 - `status`: "ok" or "error"
 - `tab`: short tab ID (e.g. "t1")
-- `siteProfile`: full markdown content of existing profile (after goto/newTab to known site)
+- `siteProfile`: path to site profile file (after goto/newTab to known site)
 - `actionRequired`: `{action, domain, message}` — **MUST be handled immediately** before continuing (see Site Profiles)
 - `context`: `{url, title, scroll: {y, percent}, viewport: {width, height}, activeElement?, modal?}`
 - `screenshot`: path to after-screenshot (auto-captured on every visual action)
 - `fullSnapshot`: path to full-page accessibility snapshot file
-- `viewportSnapshot`: inline viewport-only snapshot YAML
+- `viewportSnapshot`: path to viewport-only accessibility snapshot file
 - `changes`: `{summary, added[], removed[], changed[]}` — viewport diff on same-page interactions
 - `navigated`: true when URL pathname changed
 - `console`: `{errors, warnings, messages[]}` — captured errors/warnings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-skill",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Browser automation skill using Chrome DevTools Protocol for Claude Code and AI agents",
   "type": "module",
   "main": "scripts/index.js",

package/scripts/cdp-skill.js

@@ -785,15 +785,15 @@ async function main() {
       truncated: result.truncated
     };
 
-    // Remove null/undefined fields for compactness
+    // Remove null/undefined/false-y fields for compactness
     if (!output.siteProfile) delete output.siteProfile;
     if (!output.actionRequired) delete output.actionRequired;
-    if (output.navigated === undefined) delete output.navigated;
+    if (!output.navigated) delete output.navigated;
     if (!output.fullSnapshot) delete output.fullSnapshot;
     if (!output.context) delete output.context;
     if (!output.changes) delete output.changes;
     if (!output.viewportSnapshot) delete output.viewportSnapshot;
-    if (output.truncated === undefined) delete output.truncated;
+    if (!output.truncated) delete output.truncated;
     if (!output.screenshot) delete output.screenshot;
     if (!output.console) delete output.console;
     if (output.errors.length === 0) delete output.errors;

package/scripts/runner/execute-browser.js

@@ -96,8 +96,14 @@ export async function executeEval(pageController, params) {
         reject(new Error(`Eval timed out after ${evalTimeout}ms`));
       }, evalTimeout);
     });
-    result = await Promise.race([evalPromise, timeoutPromise]);
-    clearTimeout(evalTimeoutId);
+    try {
+      result = await Promise.race([evalPromise, timeoutPromise]);
+    } catch (err) {
+      evalPromise.catch(() => {}); // suppress dangling rejection if timeout won
+      throw err;
+    } finally {
+      clearTimeout(evalTimeoutId);
+    }
   } else {
     result = await evalPromise;
   }

package/scripts/runner/execute-dynamic.js

@@ -408,13 +408,14 @@ function sanitizeDomain(domain) {
  * Load a site profile for the given domain.
  *
  * @param {string} domain - hostname (e.g. "github.com")
- * @returns {Promise<string|null>} profile markdown or null
+ * @returns {Promise<string|null>} profile file path or null
  */
 export async function loadSiteProfile(domain) {
   const clean = sanitizeDomain(domain);
   const profilePath = path.join(SITES_DIR, `${clean}.md`);
   try {
-    return await fs.readFile(profilePath, 'utf8');
+    await fs.access(profilePath);
+    return profilePath;
   } catch {
     return null;
   }
@@ -452,9 +453,9 @@ export async function executeReadSiteProfile(params) {
     throw new Error('readSiteProfile requires a domain string');
   }
 
-  const content = await loadSiteProfile(domain);
-  if (content) {
-    return { found: true, domain, content };
+  const profilePath = await loadSiteProfile(domain);
+  if (profilePath) {
+    return { found: true, domain, path: profilePath };
   }
   return { found: false, domain };
 }

package/scripts/runner/execute-query.js

@@ -119,7 +119,7 @@ export async function executeGetDom(pageController, params) {
   const expression = selector
     ? `(function() {
         const el = document.querySelector(${JSON.stringify(selector)});
-        if (!el) return { error: 'Element not found: ${selector}' };
+        if (!el) return { error: 'Element not found: ' + ${JSON.stringify(selector)} };
         return {
           html: ${outer} ? el.outerHTML : el.innerHTML,
           tagName: el.tagName.toLowerCase(),
@@ -228,10 +228,11 @@ export async function executeGetBox(ariaSnapshot, params) {
  * @returns {Promise<Object>} Result with filled element info
  */
 
-export async function executeRefAt(session, params) {
+export async function executeRefAt(pageController, params) {
+  const session = pageController.session;
   const { x, y } = params;
 
-  const result = await session.send('Runtime.evaluate', {
+  const evalArgs = {
     expression: `(function() {
       const x = ${x};
       const y = ${y};
@@ -352,7 +353,10 @@ export async function executeRefAt(session, params) {
       };
     })()`,
     returnByValue: true
-  });
+  };
+  const contextId = pageController.getFrameContext();
+  if (contextId) evalArgs.contextId = contextId;
+  const result = await session.send('Runtime.evaluate', evalArgs);
 
   if (result.exceptionDetails) {
     throw new Error(`refAt error: ${result.exceptionDetails.text}`);
@@ -370,8 +374,9 @@ export async function executeRefAt(session, params) {
  * Execute an elementsAt step - get refs for elements at multiple coordinates
  */
 
-export async function executeElementsAt(session, coords) {
-  const result = await session.send('Runtime.evaluate', {
+export async function executeElementsAt(pageController, coords) {
+  const session = pageController.session;
+  const evalArgs = {
     expression: `(function() {
       const coords = ${JSON.stringify(coords)};
 
@@ -499,7 +504,10 @@ export async function executeElementsAt(session, coords) {
       return { elements: results, count: results.filter(r => !r.error).length };
     })()`,
     returnByValue: true
-  });
+  };
+  const contextId = pageController.getFrameContext();
+  if (contextId) evalArgs.contextId = contextId;
+  const result = await session.send('Runtime.evaluate', evalArgs);
 
   if (result.exceptionDetails) {
     throw new Error(`elementsAt error: ${result.exceptionDetails.text}`);
@@ -512,10 +520,11 @@ export async function executeElementsAt(session, coords) {
  * Execute an elementsNear step - get refs for all elements near a coordinate
  */
 
-export async function executeElementsNear(session, params) {
+export async function executeElementsNear(pageController, params) {
+  const session = pageController.session;
   const { x, y, radius = 50, limit = 20 } = params;
 
-  const result = await session.send('Runtime.evaluate', {
+  const evalArgs = {
     expression: `(function() {
       const centerX = ${x};
       const centerY = ${y};
@@ -665,7 +674,10 @@ export async function executeElementsNear(session, params) {
       };
     })()`,
     returnByValue: true
-  });
+  };
+  const contextId = pageController.getFrameContext();
+  if (contextId) evalArgs.contextId = contextId;
+  const result = await session.send('Runtime.evaluate', evalArgs);
 
   if (result.exceptionDetails) {
     throw new Error(`elementsNear error: ${result.exceptionDetails.text}`);
@@ -829,10 +841,7 @@ export async function executeQueryAll(elementLocator, params) {
   const results = {};
 
   for (const [name, selectorOrConfig] of Object.entries(params)) {
-    // Support both string selectors and query config objects
-    const queryParams = typeof selectorOrConfig === 'string'
-      ? selectorOrConfig
-      : selectorOrConfig;
+    const queryParams = selectorOrConfig;
 
     try {
       results[name] = await executeQuery(elementLocator, queryParams);

package/scripts/runner/step-executors.js

@@ -457,13 +457,13 @@ export async function executeStep(deps, step, options = {}) {
       const eaParams = step.elementsAt;
       if (Array.isArray(eaParams)) {
         // Batch mode (array of coordinates)
-        stepResult.output = await executeElementsAt(pageController.session, eaParams);
+        stepResult.output = await executeElementsAt(pageController, eaParams);
       } else if (eaParams && typeof eaParams === 'object' && eaParams.radius !== undefined) {
         // Nearby mode (has radius)
-        stepResult.output = await executeElementsNear(pageController.session, eaParams);
+        stepResult.output = await executeElementsNear(pageController, eaParams);
       } else {
         // Single point mode (was refAt)
-        stepResult.output = await executeRefAt(pageController.session, eaParams);
+        stepResult.output = await executeRefAt(pageController, eaParams);
       }
     } else if (step.pageFunction !== undefined) {
       stepResult.action = 'pageFunction';
@@ -576,7 +576,10 @@ export async function executeStep(deps, step, options = {}) {
 
     if (isOptional) {
       stepResult.status = 'skipped';
-      stepResult.error = `${error.message} (timeout: ${stepTimeout}ms)`;
+      const isTimeout = error.code === 'TIMEOUT' || error.name === 'TimeoutError' || error.message?.includes('timed out');
+      stepResult.error = isTimeout
+        ? `${error.message} (timeout: ${stepTimeout}ms)`
+        : error.message;
     } else {
       stepResult.status = 'error';
       stepResult.error = error.message;
@@ -668,7 +671,11 @@ export async function runSteps(deps, steps, options = {}) {
       result.navigated = navigated;
       result.fullSnapshot = fullSnapshotPath;
       result.context = afterContext;
-      result.viewportSnapshot = afterViewport.yaml;
+
+      // Write viewport snapshot to file to keep response concise
+      const viewportPath = await resolveTempPath(`${options.tabAlias || 'command'}.viewport.yaml`, '.yaml');
+      await fs.writeFile(viewportPath, afterViewport.yaml || '', 'utf8');
+      result.viewportSnapshot = viewportPath;
       result.truncated = afterViewport.truncated || false;
 
       if (!navigated && beforeViewport?.yaml) {

package/scripts/tests/ExecuteDynamic.test.js

@@ -680,7 +680,7 @@ describe('step-executors goto profile integration', () => {
     assert.strictEqual(result.action, 'goto');
     assert.strictEqual(result.status, 'ok');
     assert.ok(result.siteProfile);
-    assert.ok(result.siteProfile.includes('Pre-existing profile'));
+    assert.ok(result.siteProfile.endsWith('.md'), 'siteProfile should be a file path');
   });
 
   it('should return profileAvailable false on goto for unknown domain', async () => {

package/scripts/tests/ExecuteQuery.test.js

@@ -501,8 +501,8 @@ describe('executeGetBox', () => {
 
 describe('executeRefAt', () => {
   it('should get element ref at coordinates', async () => {
-    const session = createMockPageController({ refAt: true }).session;
-    const result = await executeRefAt(session, { x: 100, y: 200 });
+    const pageController = createMockPageController({ refAt: true });
+    const result = await executeRefAt(pageController, { x: 100, y: 200 });
 
     assert.strictEqual(result.ref, 'f0s1e1');
     assert.strictEqual(result.tag, 'BUTTON');
@@ -511,8 +511,8 @@ describe('executeRefAt', () => {
   });
 
   it('should return element info with box', async () => {
-    const session = createMockPageController({ refAt: true }).session;
-    const result = await executeRefAt(session, { x: 100, y: 200 });
+    const pageController = createMockPageController({ refAt: true });
+    const result = await executeRefAt(pageController, { x: 100, y: 200 });
 
     assert.ok(result.box);
     assert.strictEqual(result.box.x, 100);
@@ -522,17 +522,17 @@ describe('executeRefAt', () => {
   });
 
   it('should throw if no element at coordinates', async () => {
-    const session = createMockPageController({ refAtNoElement: true }).session;
+    const pageController = createMockPageController({ refAtNoElement: true });
     await assert.rejects(
-      async () => executeRefAt(session, { x: 999, y: 999 }),
+      async () => executeRefAt(pageController, { x: 999, y: 999 }),
       /No element at coordinates/
     );
   });
 
   it('should throw on evaluation error', async () => {
-    const session = createMockPageController({ evalError: true }).session;
+    const pageController = createMockPageController({ evalError: true });
     await assert.rejects(
-      async () => executeRefAt(session, { x: 100, y: 100 }),
+      async () => executeRefAt(pageController, { x: 100, y: 100 }),
       /Evaluation error/
     );
   });
@@ -544,12 +544,12 @@ describe('executeRefAt', () => {
 
 describe('executeElementsAt', () => {
   it('should get elements at multiple coordinates', async () => {
-    const session = createMockPageController({ elementsAt: true }).session;
+    const pageController = createMockPageController({ elementsAt: true });
     const coords = [
       { x: 100, y: 100 },
       { x: 200, y: 200 }
     ];
-    const result = await executeElementsAt(session, coords);
+    const result = await executeElementsAt(pageController, coords);
 
     assert.ok(result.results);
     assert.strictEqual(result.results.length, 2);
@@ -558,16 +558,16 @@ describe('executeElementsAt', () => {
   });
 
   it('should handle empty coordinates array', async () => {
-    const session = createMockPageController({ elementsAt: true }).session;
-    const result = await executeElementsAt(session, []);
+    const pageController = createMockPageController({ elementsAt: true });
+    const result = await executeElementsAt(pageController, []);
 
     assert.ok(result.results || Array.isArray(result));
   });
 
   it('should throw on evaluation error', async () => {
-    const session = createMockPageController({ evalError: true }).session;
+    const pageController = createMockPageController({ evalError: true });
     await assert.rejects(
-      async () => executeElementsAt(session, [{ x: 100, y: 100 }]),
+      async () => executeElementsAt(pageController, [{ x: 100, y: 100 }]),
       /Evaluation error/
     );
   });
@@ -579,9 +579,9 @@ describe('executeElementsAt', () => {
 
 describe('executeElementsNear', () => {
   it('should get elements near coordinates', async () => {
-    const session = createMockPageController({ elementsNear: true }).session;
+    const pageController = createMockPageController({ elementsNear: true });
     const params = { x: 100, y: 100, radius: 50 };
-    const result = await executeElementsNear(session, params);
+    const result = await executeElementsNear(pageController, params);
 
     assert.ok(result.elements);
     assert.strictEqual(result.elements.length, 2);
@@ -590,18 +590,18 @@ describe('executeElementsNear', () => {
   });
 
   it('should default radius to 100 if not provided', async () => {
-    const session = createMockPageController({ elementsNear: true }).session;
+    const pageController = createMockPageController({ elementsNear: true });
     const params = { x: 100, y: 100 };
-    const result = await executeElementsNear(session, params);
+    const result = await executeElementsNear(pageController, params);
 
     // Should still work with default radius
     assert.ok(result.elements || result.searchRadius);
   });
 
   it('should throw on evaluation error', async () => {
-    const session = createMockPageController({ evalError: true }).session;
+    const pageController = createMockPageController({ evalError: true });
     await assert.rejects(
-      async () => executeElementsNear(session, { x: 100, y: 100 }),
+      async () => executeElementsNear(pageController, { x: 100, y: 100 }),
       /Evaluation error/
     );
   });