Cue

A powerful Node.js library for extracting and interacting with web pages using the Chrome DevTools Protocol via Playwright.

Features

• 🎯 Smart Element Detection - Automatically identifies interactive elements
• 🔍 Advanced Filtering - Paint order and bounding box filtering for accurate representation
• 🤖 LLM-Optimized - Clean, indexed output perfect for AI consumption
• ⚡ Fast & Efficient - Built-in caching support
• 🎨 Realistic Interactions - Click, fill, and type with human-like behavior
• 🌐 Cross-Platform - Works on macOS, Windows, and Linux

Installation

pnpm add playwright
# Add this package to your project

Quick Start

const { chromium } = require('playwright');
const { readPage, clickElement, PageContentCache } = require('cue');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  const cache = new PageContentCache();
  
  await page.goto('https://example.com');
  const content = await readPage(page, cache);
  
  console.log(content.llmRepresentation);
  console.log(`Found ${content.selectorMap.size} interactive elements`);
  
  const selectorMap = cache.getSelectorMap(page);
  await clickElement(page, 5, selectorMap);
  
  await browser.close();
})();

Documentation

• Full Documentation
• API Reference
• Examples

API Overview

Core Functions

• readPage(page, cache?) - Extract page content
• clickElement(page, index, selectorMap) - Click an element
• fillElement(page, index, text, selectorMap, options?) - Fill form fields
• search(page, query) - Search on DuckDuckGo
• type(page, text) - Type text into focused element

Classes

• PageContentCache - Cache for extracted content
• ElementInteractor - Low-level element interaction
• AdvancedContentExtractor - Low-level content extraction

Example Output

[1]<a href="/login" />
  Login
[2]<button class="submit" />
  Submit Form
[3]<input name="email" type="text" placeholder="Enter email" />
|SCROLL|<div class="content" /> (scroll: 0.0↑ 2.5↓ 0%)

How It Works

1. Capture - Uses CDP to get DOM snapshot, accessibility tree, and layout metrics
2. Build - Constructs enhanced DOM tree with visibility and position data
3. Filter - Removes hidden and occluded elements
4. Detect - Identifies interactive elements using multiple heuristics
5. Serialize - Generates clean, indexed representation

Demo

Run the comprehensive demo:

pnpm run build
node demo/comprehensive.js

License

MIT