@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/core/observe.js

@@ -0,0 +1,395 @@
+/**
+ * WebPeel Observe — Give agents structured "eyes" on a web page.
+ *
+ * Returns a machine-readable map of interactive elements (links, buttons,
+ * inputs, forms, selects, media) so agents can decide what to do next
+ * without needing a vision model.
+ *
+ * This bridges the gap between:
+ *   - `peel()` / `webpeel_read` → markdown content (strips interaction cues)
+ *   - `webpeel_act` → requires knowing selectors already
+ *
+ * With `observe()`, the loop becomes:
+ *   1. observe(url) → see what's on the page
+ *   2. decide which element to interact with
+ *   3. act(url, actions) → do it
+ *   4. observe again → see the result
+ */
+// ── Serializable extraction logic (runs inside page.evaluate) ─────────────
+/**
+ * This function runs inside the browser context via page.evaluate().
+ * It must be fully self-contained — no closures over Node variables.
+ */
+function extractInteractiveElements(args) {
+    const { scopeSelector, maxPerCategory } = args;
+    const root = scopeSelector
+        ? document.querySelector(scopeSelector) || document
+        : document;
+    const vpW = window.innerWidth;
+    const vpH = window.innerHeight;
+    function isVisible(el) {
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0')
+            return false;
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+    }
+    function isInViewport(el) {
+        const rect = el.getBoundingClientRect();
+        return rect.top < vpH && rect.bottom > 0 && rect.left < vpW && rect.right > 0;
+    }
+    function getBbox(el) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            return null;
+        return {
+            x: Math.round(rect.x),
+            y: Math.round(rect.y),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+        };
+    }
+    function getText(el) {
+        // Prefer aria-label, then textContent, then value, then placeholder
+        const ariaLabel = el.getAttribute('aria-label');
+        if (ariaLabel)
+            return ariaLabel.trim().slice(0, 120);
+        const text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+        if (text && text.length <= 120)
+            return text;
+        if (text)
+            return text.slice(0, 117) + '...';
+        if (el instanceof HTMLInputElement) {
+            return el.value || el.placeholder || '';
+        }
+        return el.getAttribute('title') || el.getAttribute('alt') || '';
+    }
+    function buildSelector(el) {
+        // Best effort: id > unique class > nth-child path
+        if (el.id)
+            return `#${CSS.escape(el.id)}`;
+        // data-testid is very reliable
+        const testId = el.getAttribute('data-testid');
+        if (testId)
+            return `[data-testid="${CSS.escape(testId)}"]`;
+        // aria-label is good for buttons
+        const ariaLabel = el.getAttribute('aria-label');
+        if (ariaLabel)
+            return `${el.tagName.toLowerCase()}[aria-label="${CSS.escape(ariaLabel)}"]`;
+        // name attribute for form elements
+        const name = el.getAttribute('name');
+        if (name)
+            return `${el.tagName.toLowerCase()}[name="${CSS.escape(name)}"]`;
+        // href for links
+        if (el.tagName === 'A') {
+            const href = el.getAttribute('href');
+            if (href && href.length < 100)
+                return `a[href="${CSS.escape(href)}"]`;
+        }
+        // class-based with tag
+        if (el.className && typeof el.className === 'string') {
+            const cls = el.className.trim().split(/\s+/)[0];
+            if (cls) {
+                const candidate = `${el.tagName.toLowerCase()}.${CSS.escape(cls)}`;
+                // Check uniqueness
+                if (document.querySelectorAll(candidate).length === 1)
+                    return candidate;
+            }
+        }
+        // Fallback: nth-child path (2 levels max for readability)
+        const tag = el.tagName.toLowerCase();
+        const parent = el.parentElement;
+        if (parent) {
+            const siblings = Array.from(parent.children).filter(c => c.tagName === el.tagName);
+            if (siblings.length === 1) {
+                const parentTag = parent.tagName.toLowerCase();
+                if (parent.id)
+                    return `#${CSS.escape(parent.id)} > ${tag}`;
+                return `${parentTag} > ${tag}`;
+            }
+            const idx = siblings.indexOf(el) + 1;
+            if (parent.id)
+                return `#${CSS.escape(parent.id)} > ${tag}:nth-of-type(${idx})`;
+        }
+        return tag;
+    }
+    function getRole(el) {
+        const explicit = el.getAttribute('role');
+        if (explicit)
+            return explicit;
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'a')
+            return 'link';
+        if (tag === 'button')
+            return 'button';
+        if (tag === 'input') {
+            const type = el.type || 'text';
+            if (type === 'submit')
+                return 'submit';
+            if (type === 'checkbox')
+                return 'checkbox';
+            if (type === 'radio')
+                return 'radio';
+            if (type === 'file')
+                return 'file-upload';
+            if (type === 'search')
+                return 'search';
+            return 'textbox';
+        }
+        if (tag === 'textarea')
+            return 'textbox';
+        if (tag === 'select')
+            return 'listbox';
+        if (tag === 'form')
+            return 'form';
+        if (tag === 'img')
+            return 'image';
+        if (tag === 'video')
+            return 'video';
+        if (tag === 'audio')
+            return 'audio';
+        return tag;
+    }
+    function getAttributes(el) {
+        const attrs = {};
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'a') {
+            const href = el.getAttribute('href');
+            if (href)
+                attrs.href = href.slice(0, 200);
+            if (el.getAttribute('target') === '_blank')
+                attrs.target = '_blank';
+        }
+        if (tag === 'input') {
+            const inp = el;
+            attrs.type = inp.type || 'text';
+            if (inp.placeholder)
+                attrs.placeholder = inp.placeholder;
+            if (inp.name)
+                attrs.name = inp.name;
+            if (inp.required)
+                attrs.required = 'true';
+            if (inp.disabled)
+                attrs.disabled = 'true';
+            if (inp.value)
+                attrs.value = inp.value.slice(0, 50);
+        }
+        if (tag === 'select') {
+            const sel = el;
+            const options = Array.from(sel.options).slice(0, 5).map(o => o.text.trim());
+            if (options.length > 0)
+                attrs.options = options.join(' | ');
+            if (sel.name)
+                attrs.name = sel.name;
+        }
+        if (tag === 'textarea') {
+            const ta = el;
+            if (ta.placeholder)
+                attrs.placeholder = ta.placeholder;
+            if (ta.name)
+                attrs.name = ta.name;
+        }
+        if (tag === 'form') {
+            const form = el;
+            if (form.action)
+                attrs.action = form.action.slice(0, 200);
+            if (form.method)
+                attrs.method = form.method;
+            attrs.fields = String(form.elements.length);
+        }
+        if (tag === 'img') {
+            const img = el;
+            if (img.alt)
+                attrs.alt = img.alt.slice(0, 120);
+            if (img.src)
+                attrs.src = img.src.slice(0, 200);
+        }
+        if (tag === 'video' || tag === 'audio') {
+            const media = el;
+            if (media.src)
+                attrs.src = media.src.slice(0, 200);
+            if (media.duration)
+                attrs.duration = String(Math.round(media.duration));
+        }
+        return attrs;
+    }
+    function serialize(el) {
+        return {
+            tag: el.tagName.toLowerCase(),
+            selector: buildSelector(el),
+            text: getText(el),
+            role: getRole(el),
+            attributes: getAttributes(el),
+            inViewport: isInViewport(el),
+            bbox: getBbox(el),
+        };
+    }
+    function collect(selector) {
+        const els = root instanceof Document
+            ? Array.from(root.querySelectorAll(selector))
+            : Array.from(root.querySelectorAll(selector));
+        return els
+            .filter(isVisible)
+            .slice(0, maxPerCategory)
+            .map(serialize);
+    }
+    return {
+        links: collect('a[href]'),
+        buttons: collect('button, [role="button"], input[type="submit"], input[type="button"]'),
+        inputs: collect('input:not([type="hidden"]):not([type="submit"]):not([type="button"]), textarea'),
+        selects: collect('select'),
+        forms: collect('form'),
+        media: collect('img[src], video, audio, iframe[src]'),
+    };
+}
+// ── Main observe function ─────────────────────────────────────────────────────
+/**
+ * Observe a web page and return a structured map of interactive elements.
+ *
+ * @example
+ * ```typescript
+ * import { observe } from 'webpeel';
+ *
+ * const result = await observe({ url: 'https://news.ycombinator.com' });
+ * console.log(result.elements.links.length); // e.g. 30
+ * console.log(result.elements.links[0].ref); // "link-0"
+ * console.log(result.elements.links[0].text); // "Show HN: ..."
+ * console.log(result.elements.links[0].selector); // "a[href='item?id=12345']"
+ * console.log(result.summary);
+ * // "30 links, 2 buttons, 1 input, 1 form. Key actions: ..."
+ * ```
+ */
+export async function observe(options) {
+    const { url, selector = null, viewport = 'desktop', screenshot: wantScreenshot = false, screenshotFullPage = false, maxElements = 50, timeout = 30000, stealth = false, } = options;
+    if (!url)
+        throw new Error('observe() requires a url');
+    const startTime = Date.now();
+    // Resolve viewport dimensions
+    let vpWidth = 1280;
+    let vpHeight = 800;
+    let deviceLabel = 'desktop';
+    if (viewport === 'mobile') {
+        vpWidth = 390;
+        vpHeight = 844;
+        deviceLabel = 'mobile';
+    }
+    else if (viewport === 'tablet') {
+        vpWidth = 768;
+        vpHeight = 1024;
+        deviceLabel = 'tablet';
+    }
+    else if (typeof viewport === 'object') {
+        vpWidth = viewport.width;
+        vpHeight = viewport.height;
+        deviceLabel = `${viewport.width}x${viewport.height}`;
+    }
+    // Use browserFetch with keepPageOpen so we can evaluate in the live page
+    const { browserFetch } = await import('./browser-fetch.js');
+    const fetchResult = await browserFetch(url, {
+        timeoutMs: timeout,
+        stealth,
+        keepPageOpen: true,
+        viewportWidth: vpWidth,
+        viewportHeight: vpHeight,
+        device: deviceLabel === 'mobile' ? 'mobile' : deviceLabel === 'tablet' ? 'tablet' : 'desktop',
+    });
+    const page = fetchResult.page;
+    if (!page) {
+        throw new Error('observe() failed: browser page not available');
+    }
+    try {
+        // Extract interactive elements from the live DOM
+        const raw = await page.evaluate(extractInteractiveElements, { scopeSelector: selector, maxPerCategory: maxElements });
+        // Take optional screenshot
+        let screenshotBase64;
+        if (wantScreenshot) {
+            const buf = await page.screenshot({ type: 'png', fullPage: screenshotFullPage });
+            screenshotBase64 = buf.toString('base64');
+        }
+        const pageTitle = await page.title();
+        const finalUrl = page.url();
+        // Get scroll dimensions
+        const scrollDims = await page.evaluate(() => ({
+            width: document.documentElement.scrollWidth,
+            height: document.documentElement.scrollHeight,
+        }));
+        const elapsed = Date.now() - startTime;
+        // Add refs to elements
+        const addRefs = (items, prefix) => items.map((item, i) => ({
+            ref: `${prefix}-${i}`,
+            tag: item.tag,
+            selector: item.selector,
+            text: item.text,
+            role: item.role,
+            attributes: item.attributes,
+            inViewport: item.inViewport,
+            bbox: item.bbox ?? undefined,
+        }));
+        const elements = {
+            links: addRefs(raw.links, 'link'),
+            buttons: addRefs(raw.buttons, 'button'),
+            inputs: addRefs(raw.inputs, 'input'),
+            selects: addRefs(raw.selects, 'select'),
+            forms: addRefs(raw.forms, 'form'),
+            media: addRefs(raw.media, 'media'),
+        };
+        const totalElements = elements.links.length +
+            elements.buttons.length +
+            elements.inputs.length +
+            elements.selects.length +
+            elements.forms.length +
+            elements.media.length;
+        // Build summary
+        const parts = [];
+        if (elements.links.length > 0)
+            parts.push(`${elements.links.length} links`);
+        if (elements.buttons.length > 0)
+            parts.push(`${elements.buttons.length} buttons`);
+        if (elements.inputs.length > 0)
+            parts.push(`${elements.inputs.length} inputs`);
+        if (elements.selects.length > 0)
+            parts.push(`${elements.selects.length} selects`);
+        if (elements.forms.length > 0)
+            parts.push(`${elements.forms.length} forms`);
+        if (elements.media.length > 0)
+            parts.push(`${elements.media.length} media`);
+        // Highlight key actionable items
+        const keyActions = [];
+        for (const btn of elements.buttons.slice(0, 3)) {
+            if (btn.text)
+                keyActions.push(`[${btn.ref}] "${btn.text}"`);
+        }
+        for (const inp of elements.inputs.slice(0, 2)) {
+            const label = inp.text || inp.attributes.placeholder || inp.attributes.name || 'text field';
+            keyActions.push(`[${inp.ref}] ${label} (${inp.attributes.type || 'text'})`);
+        }
+        let summary = `Page: "${pageTitle}" — ${parts.join(', ')}`;
+        if (keyActions.length > 0) {
+            summary += `. Key actions: ${keyActions.join(', ')}`;
+        }
+        summary += `. ${elapsed}ms.`;
+        return {
+            url: finalUrl,
+            title: pageTitle,
+            viewport: { width: vpWidth, height: vpHeight },
+            scroll: scrollDims,
+            elements,
+            totalElements,
+            summary,
+            screenshot: screenshotBase64,
+            elapsed,
+        };
+    }
+    finally {
+        // Clean up: close the page and its browser
+        try {
+            const browser = page.context().browser();
+            await page.close().catch(() => { });
+            if (browser)
+                await browser.close().catch(() => { });
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+}

package/dist/core/ocr.d.ts

@@ -0,0 +1,12 @@
+export declare const IMAGE_CONTENT_TYPES: string[];
+/**
+ * Returns true if the given content-type string is a supported image type.
+ */
+export declare function isImageContentType(contentType: string): boolean;
+/**
+ * Extract text from an image buffer using Tesseract OCR.
+ * @param imageBuffer - Raw image bytes
+ * @param language    - Tesseract language code (default: 'eng')
+ * @returns Extracted text, trimmed. Empty string when no text found.
+ */
+export declare function extractTextFromImage(imageBuffer: Buffer, language?: string): Promise<string>;

package/dist/core/ocr.js

@@ -0,0 +1,33 @@
+/**
+ * OCR module — extract text from images using Tesseract.js (pure JS, no native deps).
+ */
+import Tesseract from 'tesseract.js';
+export const IMAGE_CONTENT_TYPES = [
+    'image/png',
+    'image/jpeg',
+    'image/jpg',
+    'image/gif',
+    'image/webp',
+    'image/tiff',
+    'image/bmp',
+];
+/**
+ * Returns true if the given content-type string is a supported image type.
+ */
+export function isImageContentType(contentType) {
+    const ct = contentType.toLowerCase();
+    return IMAGE_CONTENT_TYPES.some(t => ct.includes(t));
+}
+/**
+ * Extract text from an image buffer using Tesseract OCR.
+ * @param imageBuffer - Raw image bytes
+ * @param language    - Tesseract language code (default: 'eng')
+ * @returns Extracted text, trimmed. Empty string when no text found.
+ */
+export async function extractTextFromImage(imageBuffer, language = 'eng') {
+    const { data: { text } } = await Tesseract.recognize(imageBuffer, language, {
+        // Suppress verbose Tesseract logging
+        logger: () => { },
+    });
+    return text.trim();
+}

package/dist/core/paginate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pagination link discovery.
+ *
+ * Given a page's HTML, finds the "Next" page URL by matching common
+ * pagination patterns (link text, ARIA labels, rel attributes, CSS classes).
+ *
+ * @module paginate
+ */
+/**
+ * Attempt to find the URL of the "next" page in a paginated result set.
+ *
+ * Checks, in priority order:
+ *  1. `<a rel="next">`  or  `<link rel="next">`
+ *  2. `<a aria-label="...next...">`
+ *  3. `<a class="...next...">` (if the link text also looks "nexty")
+ *  4. `<a>` whose visible text matches a known next-page pattern
+ *
+ * @param html       - Raw HTML of the current page.
+ * @param currentUrl - Absolute URL of the current page (used to resolve
+ *                     relative `href` values).
+ * @returns          Absolute URL of the next page, or `null` if none found.
+ *
+ * @example
+ * ```typescript
+ * const next = findNextPageUrl(html, 'https://example.com/results?page=1');
+ * if (next) {
+ *   // fetch next page
+ * }
+ * ```
+ */
+export declare function findNextPageUrl(html: string, currentUrl: string): string | null;

package/dist/core/paginate.js

@@ -0,0 +1,106 @@
+/**
+ * Pagination link discovery.
+ *
+ * Given a page's HTML, finds the "Next" page URL by matching common
+ * pagination patterns (link text, ARIA labels, rel attributes, CSS classes).
+ *
+ * @module paginate
+ */
+import { load } from 'cheerio';
+/* ------------------------------------------------------------------ */
+/*  Next-page heuristics                                              */
+/* ------------------------------------------------------------------ */
+/** Exact and partial text patterns for "Next" links (case-insensitive). */
+const NEXT_TEXT_EXACT = new Set(['next', 'next page', '›', '»', '>', '>>', 'next ›', 'next »', 'next >', 'suivant', 'weiter', 'siguiente', '次へ']);
+/** Substrings to look for in aria-label / class attributes. */
+const NEXT_ATTR_SUBSTRINGS = ['next'];
+/* ------------------------------------------------------------------ */
+/*  Public API                                                        */
+/* ------------------------------------------------------------------ */
+/**
+ * Attempt to find the URL of the "next" page in a paginated result set.
+ *
+ * Checks, in priority order:
+ *  1. `<a rel="next">`  or  `<link rel="next">`
+ *  2. `<a aria-label="...next...">`
+ *  3. `<a class="...next...">` (if the link text also looks "nexty")
+ *  4. `<a>` whose visible text matches a known next-page pattern
+ *
+ * @param html       - Raw HTML of the current page.
+ * @param currentUrl - Absolute URL of the current page (used to resolve
+ *                     relative `href` values).
+ * @returns          Absolute URL of the next page, or `null` if none found.
+ *
+ * @example
+ * ```typescript
+ * const next = findNextPageUrl(html, 'https://example.com/results?page=1');
+ * if (next) {
+ *   // fetch next page
+ * }
+ * ```
+ */
+export function findNextPageUrl(html, currentUrl) {
+    if (!html)
+        return null;
+    const $ = load(html);
+    // 1. rel="next" (strongest signal)
+    const relNext = $('a[rel="next"], link[rel="next"]').first();
+    if (relNext.length) {
+        const href = relNext.attr('href');
+        const resolved = resolve(href, currentUrl);
+        if (resolved && resolved !== currentUrl)
+            return resolved;
+    }
+    // 2. aria-label containing "next"
+    const ariaNext = $('a[aria-label]').filter((_, el) => {
+        const label = $(el).attr('aria-label')?.toLowerCase() ?? '';
+        return NEXT_ATTR_SUBSTRINGS.some(sub => label.includes(sub));
+    }).first();
+    if (ariaNext.length) {
+        const href = ariaNext.attr('href');
+        const resolved = resolve(href, currentUrl);
+        if (resolved && resolved !== currentUrl)
+            return resolved;
+    }
+    // 3. class containing "next" + plausible link text
+    const classNext = $('a[class*="next"], a[class*="Next"]').filter((_, el) => {
+        const text = $(el).text().trim().toLowerCase();
+        // Avoid "previous" or "prev" links that happen to also have "next" in class
+        return !text.includes('prev');
+    }).first();
+    if (classNext.length) {
+        const href = classNext.attr('href');
+        const resolved = resolve(href, currentUrl);
+        if (resolved && resolved !== currentUrl)
+            return resolved;
+    }
+    // 4. Text-based match on all <a> tags
+    const allLinks = $('a');
+    for (let i = 0; i < allLinks.length; i++) {
+        const el = allLinks.eq(i);
+        const text = el.text().trim().toLowerCase();
+        if (NEXT_TEXT_EXACT.has(text)) {
+            const href = el.attr('href');
+            const resolved = resolve(href, currentUrl);
+            if (resolved && resolved !== currentUrl)
+                return resolved;
+        }
+    }
+    return null;
+}
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * Resolve `href` against `base`. Returns `null` for unresolvable / empty hrefs.
+ */
+function resolve(href, base) {
+    if (!href || href === '#' || href.startsWith('javascript:'))
+        return null;
+    try {
+        return new URL(href, base).href;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/pdf.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PDF extraction using pdf-parse
+ */
+export declare function extractPdf(buffer: Buffer): Promise<{
+    text: string;
+    metadata: Record<string, any>;
+    pages: number;
+}>;

package/dist/core/pdf.js

@@ -0,0 +1,25 @@
+/**
+ * PDF extraction using pdf-parse
+ */
+export async function extractPdf(buffer) {
+    try {
+        const pdfParse = (await import('pdf-parse')).default;
+        // pdf-parse (pdfjs) requires Uint8Array — passing a Node Buffer causes xref parse errors.
+        // The type definitions say Buffer, but at runtime pdfjs needs a plain Uint8Array.
+        const data = await pdfParse(new Uint8Array(buffer));
+        return {
+            text: data.text,
+            metadata: {
+                title: data.info?.Title || '',
+                author: data.info?.Author || '',
+                creator: data.info?.Creator || '',
+                producer: data.info?.Producer || '',
+                creationDate: data.info?.CreationDate || '',
+            },
+            pages: data.numpages,
+        };
+    }
+    catch (error) {
+        throw new Error(`PDF parsing failed: ${error instanceof Error ? error.message : 'Unknown error'}. Install pdf-parse: npm install pdf-parse`);
+    }
+}

package/dist/core/peel-tls.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PeelTLS — WebPeel's TLS Fingerprint Spoofing Engine
+ * BSD-licensed replacement for CycleTLS (GPL-3).
+ *
+ * Manages a singleton Go binary process that provides TLS fingerprint spoofing
+ * via uTLS (utls library). The binary exposes a local HTTP API that this module
+ * communicates with.
+ */
+import type { FetchResult } from './fetcher.js';
+export interface PeelTLSOptions {
+    timeout?: number;
+    proxy?: string;
+    headers?: Record<string, string>;
+    /** TLS fingerprint preset: 'chrome-133' | 'firefox-120' | 'safari-16' | raw JA3 string */
+    fingerprint?: string;
+}
+export interface PeelTLSResult extends FetchResult {
+    method: 'peeltls';
+}
+/** Check if the PeelTLS binary is available on this platform. */
+export declare function isPeelTLSAvailable(): boolean;
+/** Fetch a URL using PeelTLS TLS fingerprint spoofing. */
+export declare function peelTLSFetch(url: string, options?: PeelTLSOptions): Promise<PeelTLSResult>;
+/** Gracefully shut down the PeelTLS binary process. */
+export declare function shutdownPeelTLS(): Promise<void>;