chrome-cdp-cli 1.7.8 → 1.8.0

package/dist/cli/CLIInterface.js

@@ -373,6 +373,9 @@ class CLIInterface {
         }
         if (result.data && typeof result.data === 'object') {
             const data = result.data;
+            if (data.snapshot && typeof data.snapshot === 'string') {
+                return data.snapshot;
+            }
             if (data.messages && Array.isArray(data.messages)) {
                 output += dataSourceInfo;
                 if (data.messages.length === 0) {

package/dist/handlers/TakeSnapshotHandler.js

@@ -47,6 +47,20 @@ class TakeSnapshotHandler {
                 }
             };
         }
+        if (snapshotArgs.format !== 'html' && typeof processedSnapshot === 'object' && processedSnapshot !== null) {
+            const snapshotObj = processedSnapshot;
+            if (snapshotObj.snapshot && typeof snapshotObj.snapshot === 'string') {
+                return {
+                    success: true,
+                    data: {
+                        snapshot: snapshotObj.snapshot,
+                        format: 'text',
+                        documentsCount: response.documents.length,
+                        nodesCount: response.documents[0]?.nodes?.nodeName?.length || 0
+                    }
+                };
+            }
+        }
         return {
             success: true,
             data: {
@@ -62,29 +76,24 @@ class TakeSnapshotHandler {
         if (!docResponse || !docResponse.root) {
             throw new Error('Failed to get document root');
         }
-        const htmlResponse = await client.send('DOM.getOuterHTML', {
-            nodeId: docResponse.root.nodeId
-        });
-        if (!htmlResponse || !htmlResponse.outerHTML) {
-            throw new Error('Failed to get document HTML');
-        }
+        const url = await this.getCurrentURL(client);
+        const title = await this.getCurrentTitle(client);
         let processedSnapshot;
         if (snapshotArgs.format === 'html') {
+            const htmlResponse = await client.send('DOM.getOuterHTML', {
+                nodeId: docResponse.root.nodeId
+            });
+            if (!htmlResponse || !htmlResponse.outerHTML) {
+                throw new Error('Failed to get document HTML');
+            }
             processedSnapshot = htmlResponse.outerHTML;
         }
         else {
+            const textSnapshot = this.buildTextFromDOMNode(docResponse.root, url, title);
             processedSnapshot = {
-                metadata: {
-                    captureTime: new Date().toISOString(),
-                    method: 'DOM.getOuterHTML',
-                    documentsCount: 1
-                },
-                documents: [{
-                        url: await this.getCurrentURL(client),
-                        title: await this.getCurrentTitle(client),
-                        html: htmlResponse.outerHTML,
-                        domTree: docResponse.root
-                    }]
+                url,
+                title,
+                snapshot: textSnapshot
             };
         }
         if (snapshotArgs.filename) {
@@ -98,6 +107,18 @@ class TakeSnapshotHandler {
                 }
             };
         }
+        if (snapshotArgs.format !== 'html' && typeof processedSnapshot === 'object' && processedSnapshot !== null) {
+            const snapshotObj = processedSnapshot;
+            if (snapshotObj.snapshot && typeof snapshotObj.snapshot === 'string') {
+                return {
+                    success: true,
+                    data: {
+                        snapshot: snapshotObj.snapshot,
+                        format: 'text'
+                    }
+                };
+            }
+        }
         return {
             success: true,
             data: {
@@ -141,25 +162,418 @@ class TakeSnapshotHandler {
         if (args.format === 'html') {
             return this.convertToHTML(response);
         }
-        return {
-            metadata: {
-                captureTime: new Date().toISOString(),
-                documentsCount: response.documents.length,
-                stringsCount: response.strings.length
-            },
-            documents: response.documents.map(doc => ({
-                url: doc.documentURL,
-                title: doc.title,
-                baseURL: doc.baseURL,
-                language: doc.contentLanguage,
-                encoding: doc.encodingName,
-                frameId: doc.frameId,
-                domTree: this.buildDOMTree(doc, response.strings),
-                layout: this.processLayoutInfo(doc.layout, response.strings),
-                textBoxes: doc.textBoxes
-            })),
-            strings: response.strings
+        const doc = response.documents[0];
+        if (!doc) {
+            return {
+                error: 'No documents found'
+            };
+        }
+        const textSnapshot = this.createTextSnapshot(doc, response.strings);
+        const result = {
+            url: doc.documentURL,
+            title: doc.title,
+            snapshot: textSnapshot
+        };
+        return result;
+    }
+    createTextSnapshot(doc, strings) {
+        const nodes = doc.nodes;
+        if (!nodes.nodeName || !nodes.nodeType) {
+            return 'Empty document';
+        }
+        const nodeTree = this.buildNodeTree(doc, strings);
+        let output = `PAGE: ${doc.title || 'Untitled'}\n`;
+        const bodyNode = this.findBodyNode(nodeTree);
+        if (bodyNode) {
+            output += this.renderNodeAsText(bodyNode, 0);
+        }
+        else {
+            for (const node of nodeTree) {
+                if (this.shouldIncludeNode(node)) {
+                    output += this.renderNodeAsText(node, 0);
+                }
+            }
+        }
+        return output;
+    }
+    buildNodeTree(doc, strings) {
+        const nodes = doc.nodes;
+        const nodeCount = nodes.nodeName.length;
+        const nodeMap = new Map();
+        for (let i = 0; i < nodeCount; i++) {
+            const node = {
+                index: i,
+                nodeType: nodes.nodeType[i],
+                nodeName: nodes.nodeName[i].toLowerCase(),
+                children: [],
+                textContent: '',
+                attributes: {}
+            };
+            if (nodes.nodeValue?.[i]) {
+                node.textContent = nodes.nodeValue[i].trim();
+            }
+            if (nodes.textValue?.index.includes(i)) {
+                const textIndex = nodes.textValue.index.indexOf(i);
+                const stringIndex = nodes.textValue.value[textIndex];
+                if (typeof stringIndex === 'number' && strings[stringIndex]) {
+                    node.textContent = strings[stringIndex].trim();
+                }
+            }
+            if (nodes.attributes?.[i]) {
+                const attrs = nodes.attributes[i];
+                for (let j = 0; j < attrs.length; j += 2) {
+                    const name = strings[parseInt(attrs[j])];
+                    const value = strings[parseInt(attrs[j + 1])];
+                    if (['id', 'class', 'type', 'name', 'href', 'src', 'alt', 'placeholder', 'value', 'title'].includes(name)) {
+                        node.attributes[name] = value;
+                    }
+                }
+            }
+            if (nodes.inputValue?.index.includes(i)) {
+                const inputIndex = nodes.inputValue.index.indexOf(i);
+                const stringIndex = nodes.inputValue.value[inputIndex];
+                if (typeof stringIndex === 'number') {
+                    node.inputValue = strings[stringIndex];
+                }
+            }
+            if (nodes.inputChecked?.index.includes(i)) {
+                node.checked = true;
+            }
+            if (nodes.optionSelected?.index.includes(i)) {
+                node.selected = true;
+            }
+            if (nodes.isClickable?.index.includes(i)) {
+                node.clickable = true;
+            }
+            nodeMap.set(i, node);
+        }
+        const tree = [];
+        for (let i = 0; i < nodeCount; i++) {
+            const parentIndex = nodes.parentIndex?.[i];
+            const node = nodeMap.get(i);
+            if (parentIndex !== undefined && parentIndex >= 0) {
+                const parent = nodeMap.get(parentIndex);
+                if (parent) {
+                    parent.children.push(node);
+                }
+            }
+            else {
+                tree.push(node);
+            }
+        }
+        return tree;
+    }
+    findBodyNode(nodeTree) {
+        const findNode = (nodes, tagName) => {
+            for (const node of nodes) {
+                if (node.nodeName === tagName) {
+                    return node;
+                }
+                const found = findNode(node.children, tagName);
+                if (found)
+                    return found;
+            }
+            return null;
         };
+        return findNode(nodeTree, 'body') || findNode(nodeTree, 'main') || null;
+    }
+    shouldIncludeNode(node) {
+        const skipTags = ['script', 'style', 'meta', 'link', 'head', 'noscript'];
+        if (skipTags.includes(node.nodeName)) {
+            return false;
+        }
+        if (node.nodeType === 3) {
+            const text = (node.textContent || '').trim();
+            return text.length > 0;
+        }
+        return true;
+    }
+    renderNodeAsText(node, depth, isLast = false, parentIsLast = []) {
+        if (!this.shouldIncludeNode(node)) {
+            return '';
+        }
+        let indent = '';
+        for (let i = 0; i < parentIsLast.length; i++) {
+            indent += parentIsLast[i] ? '    ' : '│   ';
+        }
+        const prefix = depth > 0 ? (isLast ? '└── ' : '├── ') : '';
+        let output = '';
+        if (node.nodeType === 3) {
+            if (node.textContent) {
+                const truncatedText = this.truncateText(node.textContent.trim(), 40);
+                output += `${indent}${prefix}"${truncatedText}"\n`;
+            }
+        }
+        else if (node.nodeType === 1) {
+            const tag = node.nodeName.toUpperCase();
+            let description = tag;
+            const attrs = [];
+            if (node.attributes.id)
+                attrs.push(`#${node.attributes.id}`);
+            if (node.attributes.class) {
+                const classes = node.attributes.class.split(/\s+/).filter((c) => c.trim().length > 0);
+                classes.forEach((cls) => {
+                    attrs.push(`.${cls.trim()}`);
+                });
+            }
+            if (node.attributes.type)
+                attrs.push(`[${node.attributes.type}]`);
+            if (node.attributes.name)
+                attrs.push(`name="${node.attributes.name}"`);
+            if (attrs.length > 0) {
+                description += `(${attrs.join(' ')})`;
+            }
+            if (node.nodeName === 'img' && node.attributes.alt) {
+                const altText = this.truncateText(node.attributes.alt, 40);
+                description += `: "${altText}"`;
+            }
+            else if (node.nodeName === 'a' && node.attributes.href) {
+                description += `: "${node.attributes.href}"`;
+            }
+            else if (['input', 'textarea'].includes(node.nodeName)) {
+                if (node.attributes.placeholder) {
+                    const placeholderText = this.truncateText(node.attributes.placeholder, 40);
+                    description += `: "${placeholderText}"`;
+                }
+                else if (node.inputValue) {
+                    const inputText = this.truncateText(node.inputValue, 40);
+                    description += `: "${inputText}"`;
+                }
+                else if (node.nodeName === 'textarea') {
+                    const textContent = this.extractTextContent(node);
+                    if (textContent) {
+                        const truncatedText = this.truncateText(textContent, 40);
+                        description += `: "${truncatedText}"`;
+                    }
+                }
+                if (node.checked)
+                    description += ' [checked]';
+            }
+            else if (node.nodeName === 'button' || ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(node.nodeName)) {
+                const textContent = this.extractTextContent(node);
+                if (textContent) {
+                    const truncatedText = this.truncateText(textContent, 40);
+                    description += `: "${truncatedText}"`;
+                }
+            }
+            output += `${indent}${prefix}${description}\n`;
+            if (node.nodeName === 'textarea') {
+                return output;
+            }
+            const meaningfulChildren = node.children.filter((child) => this.shouldIncludeNode(child));
+            if (meaningfulChildren.length === 0) {
+                const textContent = this.extractTextContent(node);
+                if (textContent && textContent.trim().length > 0) {
+                    const truncatedText = this.truncateText(textContent.trim(), 40);
+                    output += `${indent}│   └── "${truncatedText}"\n`;
+                    return output;
+                }
+                return output;
+            }
+            else {
+                const newParentIsLast = [...parentIsLast, isLast];
+                for (let i = 0; i < meaningfulChildren.length; i++) {
+                    const child = meaningfulChildren[i];
+                    const childIsLast = i === meaningfulChildren.length - 1;
+                    output += this.renderNodeAsText(child, depth + 1, childIsLast, newParentIsLast);
+                }
+            }
+        }
+        return output;
+    }
+    extractTextContent(node) {
+        let text = '';
+        if (node.nodeType === 3) {
+            return node.textContent || '';
+        }
+        if (node.textContent) {
+            text += node.textContent + ' ';
+        }
+        for (const child of node.children) {
+            text += this.extractTextContent(child) + ' ';
+        }
+        return text.trim().replace(/\s+/g, ' ');
+    }
+    truncateText(text, maxLength) {
+        if (!text)
+            return '';
+        if (text.length <= maxLength)
+            return text;
+        return text.substring(0, maxLength) + '...';
+    }
+    buildTextFromDOMNode(root, _url, title) {
+        let output = `PAGE: ${title || 'Untitled'}\n`;
+        const bodyNode = this.findBodyInDOMTree(root);
+        if (bodyNode) {
+            output += this.renderDOMNodeAsText(bodyNode, 0);
+        }
+        else {
+            if (root.children) {
+                for (const child of root.children) {
+                    if (this.shouldIncludeDOMNode(child)) {
+                        output += this.renderDOMNodeAsText(child, 0);
+                    }
+                }
+            }
+        }
+        return output;
+    }
+    findBodyInDOMTree(node) {
+        if (node.nodeName && node.nodeName.toLowerCase() === 'body') {
+            return node;
+        }
+        if (node.nodeName && node.nodeName.toLowerCase() === 'main') {
+            return node;
+        }
+        if (node.children) {
+            for (const child of node.children) {
+                const found = this.findBodyInDOMTree(child);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    shouldIncludeDOMNode(node) {
+        if (!node)
+            return false;
+        const nodeName = node.nodeName ? node.nodeName.toLowerCase() : '';
+        const skipTags = ['script', 'style', 'meta', 'link', 'head', 'noscript'];
+        if (skipTags.includes(nodeName)) {
+            return false;
+        }
+        if (node.nodeType === 3) {
+            const text = node.nodeValue || '';
+            return text.trim().length > 0;
+        }
+        return true;
+    }
+    renderDOMNodeAsText(node, depth, isLast = false, parentIsLast = []) {
+        if (!this.shouldIncludeDOMNode(node)) {
+            return '';
+        }
+        let indent = '';
+        for (let i = 0; i < parentIsLast.length; i++) {
+            indent += parentIsLast[i] ? '    ' : '│   ';
+        }
+        const prefix = depth > 0 ? (isLast ? '└── ' : '├── ') : '';
+        let output = '';
+        if (node.nodeType === 3) {
+            const text = (node.nodeValue || '').trim();
+            if (text) {
+                const truncatedText = this.truncateText(text, 40);
+                output += `${indent}${prefix}"${truncatedText}"\n`;
+            }
+        }
+        else if (node.nodeType === 1) {
+            const tag = (node.nodeName || '').toUpperCase();
+            let description = tag;
+            const attrs = [];
+            if (node.attributes) {
+                for (let i = 0; i < node.attributes.length; i += 2) {
+                    const name = node.attributes[i];
+                    const value = node.attributes[i + 1];
+                    if (['id', 'class', 'type', 'name', 'href', 'src', 'alt', 'placeholder', 'value', 'title'].includes(name)) {
+                        if (name === 'id')
+                            attrs.push(`#${value}`);
+                        else if (name === 'class') {
+                            const classes = value.split(/\s+/).filter((c) => c.trim().length > 0);
+                            classes.forEach((cls) => {
+                                attrs.push(`.${cls.trim()}`);
+                            });
+                        }
+                        else if (name === 'type')
+                            attrs.push(`[${value}]`);
+                        else
+                            attrs.push(`${name}="${value}"`);
+                    }
+                }
+            }
+            if (attrs.length > 0) {
+                description += `(${attrs.join(' ')})`;
+            }
+            const nodeName = (node.nodeName || '').toLowerCase();
+            if (nodeName === 'img' && node.attributes) {
+                const altIndex = node.attributes.indexOf('alt');
+                if (altIndex >= 0 && altIndex + 1 < node.attributes.length) {
+                    const altText = this.truncateText(node.attributes[altIndex + 1], 40);
+                    description += `: "${altText}"`;
+                }
+            }
+            else if (nodeName === 'a' && node.attributes) {
+                const hrefIndex = node.attributes.indexOf('href');
+                if (hrefIndex >= 0 && hrefIndex + 1 < node.attributes.length) {
+                    description += `: "${node.attributes[hrefIndex + 1]}"`;
+                }
+            }
+            else if (['input', 'textarea'].includes(nodeName)) {
+                if (node.attributes) {
+                    const placeholderIndex = node.attributes.indexOf('placeholder');
+                    if (placeholderIndex >= 0 && placeholderIndex + 1 < node.attributes.length) {
+                        const placeholderText = this.truncateText(node.attributes[placeholderIndex + 1], 40);
+                        description += `: "${placeholderText}"`;
+                    }
+                }
+                if (nodeName === 'textarea') {
+                    const textContent = this.extractTextFromDOMNode(node);
+                    if (textContent) {
+                        const truncatedText = this.truncateText(textContent, 40);
+                        description += `: "${truncatedText}"`;
+                    }
+                }
+            }
+            else if (nodeName === 'button' || ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(nodeName)) {
+                const textContent = this.extractTextFromDOMNode(node);
+                if (textContent) {
+                    const truncatedText = this.truncateText(textContent, 40);
+                    description += `: "${truncatedText}"`;
+                }
+            }
+            output += `${indent}${prefix}${description}\n`;
+            if (nodeName === 'textarea') {
+                return output;
+            }
+            if (node.children) {
+                const meaningfulChildren = node.children.filter((child) => this.shouldIncludeDOMNode(child));
+                if (meaningfulChildren.length === 0) {
+                    const textContent = this.extractTextFromDOMNode(node);
+                    if (textContent && textContent.trim().length > 0) {
+                        const truncatedText = this.truncateText(textContent.trim(), 40);
+                        output += `${indent}│   └── "${truncatedText}"\n`;
+                        return output;
+                    }
+                    return output;
+                }
+                else {
+                    const newParentIsLast = [...parentIsLast, isLast];
+                    for (let i = 0; i < meaningfulChildren.length; i++) {
+                        const child = meaningfulChildren[i];
+                        const childIsLast = i === meaningfulChildren.length - 1;
+                        output += this.renderDOMNodeAsText(child, depth + 1, childIsLast, newParentIsLast);
+                    }
+                }
+            }
+        }
+        return output;
+    }
+    extractTextFromDOMNode(node) {
+        if (node.nodeType === 3) {
+            return (node.nodeValue || '').trim();
+        }
+        let text = '';
+        if (node.children) {
+            for (const child of node.children) {
+                text += this.extractTextFromDOMNode(child) + ' ';
+            }
+        }
+        return text.trim().replace(/\s+/g, ' ');
+    }
+    convertToHTML(response) {
+        const doc = response.documents[0];
+        if (!doc)
+            return '';
+        const tree = this.buildDOMTree(doc, response.strings);
+        return this.renderNodeAsHTML(tree[0], 0);
     }
     buildDOMTree(doc, strings) {
         const nodes = doc.nodes;
@@ -227,27 +641,6 @@ class TakeSnapshotHandler {
         }
         return tree;
     }
-    processLayoutInfo(layout, strings) {
-        return {
-            nodeCount: layout.nodeIndex.length,
-            styles: layout.styles.map(styleArray => styleArray.map(styleIndex => strings[parseInt(styleIndex)])),
-            bounds: layout.bounds,
-            text: layout.text,
-            paintOrders: layout.paintOrders,
-            offsetRects: layout.offsetRects,
-            scrollRects: layout.scrollRects,
-            clientRects: layout.clientRects,
-            blendedBackgroundColors: layout.blendedBackgroundColors,
-            textColorOpacities: layout.textColorOpacities
-        };
-    }
-    convertToHTML(response) {
-        const doc = response.documents[0];
-        if (!doc)
-            return '';
-        const tree = this.buildDOMTree(doc, response.strings);
-        return this.renderNodeAsHTML(tree[0], 0);
-    }
     renderNodeAsHTML(node, depth) {
         if (!node)
             return '';
@@ -312,7 +705,7 @@ class TakeSnapshotHandler {
         if (snapshotArgs.filename !== undefined && typeof snapshotArgs.filename !== 'string') {
             return false;
         }
-        if (snapshotArgs.format !== undefined && !['json', 'html'].includes(snapshotArgs.format)) {
+        if (snapshotArgs.format !== undefined && !['json', 'html', 'text'].includes(snapshotArgs.format)) {
             return false;
         }
         if (snapshotArgs.includeStyles !== undefined && typeof snapshotArgs.includeStyles !== 'boolean') {
@@ -331,47 +724,58 @@ class TakeSnapshotHandler {
     }
     getHelp() {
         return `
-snapshot - Capture a DOM snapshot including DOM tree structure, computed styles, and layout information
+snapshot - Capture a text-based DOM representation optimized for LLM understanding
 
 Usage:
   snapshot
-  snapshot --filename dom-snapshot.json
+  snapshot --filename page-structure.txt
   snapshot --format html --filename page-structure.html
-  snapshot --include-paint-order --filename detailed-snapshot.json
 
 Arguments:
   --filename <path>           Output filename (if not provided, returns data directly)
-  --format <json|html>        Output format (default: json)
+  --format <json|html>        Output format (default: json with text snapshot)
   --include-styles            Include computed styles (default: true)
   --include-attributes        Include DOM attributes (default: true)
   --include-paint-order       Include paint order information (default: false)
-  --include-text-index        Include text node indices (default: false)
+  --include-text-index        Include additional DOM tree data (default: false)
+
+Output Format:
+  The default JSON output contains a text-based representation of the page structure
+  that LLMs can easily understand, showing:
+  - Page hierarchy with indentation
+  - Element types and key attributes
+  - Text content and form values
+  - Interactive elements (buttons, links, forms)
+  - Semantic structure (headings, lists, etc.)
 
-Output Formats:
-  json: Structured JSON with DOM tree, layout info, and computed styles
-  html: Reconstructed HTML representation of the DOM
+Example Output:
+  PAGE: Example Site (https://example.com)
+  ├── HEADER
+  │   ├── IMG(#logo): "Company Logo"
+  │   └── NAV
+  │       ├── A: "https://example.com/home"
+  │       └── "Home"
+  ├── MAIN
+  │   ├── H1: "Welcome to Our Site"
+  │   ├── P
+  │   │   └── "This is the main content..."
+  │   └── FORM
+  │       ├── INPUT[email](name="email"): "Enter your email"
+  │       └── BUTTON: "Submit"
 
 Examples:
-  # Basic DOM snapshot as JSON
-  snapshot --filename dom-snapshot.json
+  # Get text-based page structure
+  snapshot
+
+  # Save to file
+  snapshot --filename page-structure.json
 
   # HTML representation
   snapshot --format html --filename page-structure.html
 
-  # Detailed snapshot with paint order
-  snapshot --include-paint-order --filename detailed-snapshot.json
-
-  # Return data directly (no file)
-  snapshot --format json
-
 Note:
-  DOM snapshots capture the complete DOM tree structure including:
-  - Element hierarchy and attributes
-  - Computed CSS styles for each element
-  - Layout information (bounds, positioning)
-  - Text content and form values
-  - Visibility and clickability information
-  - Paint order and rendering details (optional)
+  This format provides a "text screenshot" that LLMs can easily parse to understand
+  page layout, content, and interactive elements without overwhelming detail.
 `;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-cdp-cli",
-  "version": "1.7.8",
+  "version": "1.8.0",
   "description": "Browser automation CLI via Chrome DevTools Protocol. Designed for developers and AI assistants - combines dedicated commands for common tasks with flexible JavaScript execution for complex scenarios. Features: element interaction, screenshots, DOM snapshots, console/network monitoring. Built-in IDE integration for Cursor and Claude.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",