@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/browser/extract.js

@@ -0,0 +1,132 @@
+/**
+ * `browser extract` — agent-native article/content reading channel.
+ *
+ * Pipeline (from first principles — agents want the *content*, not the DOM):
+ *   1. Scope:    select `--selector` (default: document.body or <main>/<article>)
+ *   2. Denoise:  strip script/style/nav/header/footer/aside/iframe/svg/form, inline noise
+ *   3. Convert:  HTML → Markdown via shared `htmlToMarkdown` (turndown)
+ *   4. Chunk:    paragraph-boundary-aware slicing with `next_start_char` cursor
+ *
+ * Why a separate command:
+ * - `get html --as json` returns tree structure; useless for "read the article".
+ * - `get text` flattens everything; loses headings, lists, links.
+ * - Markdown is the agent-readable middle ground: structure preserved, noise gone.
+ *
+ * Continuation contract: the envelope always carries `start`, `end`,
+ * `total_chars`, and `next_start_char` (null when the last chunk was emitted).
+ * Agents pass `--start <next>` to continue. No session state required.
+ */
+import { htmlToMarkdown } from '../utils.js';
+const DEFAULT_CHUNK_SIZE = 20000;
+const MIN_CHUNK_SIZE = 100;
+const MAX_CHUNK_SIZE = 200000;
+const BOUNDARY_WINDOW_RATIO = 0.15;
+/**
+ * Returns the JS expression string used with `page.evaluate` to produce the
+ * cleaned HTML subtree that we then hand to `htmlToMarkdown`. We do the
+ * denoise/clone inside the page so we can use DOM APIs (querySelectorAll,
+ * cloneNode) rather than regex on serialized HTML.
+ */
+export function buildExtractHtmlJs(selector) {
+    const selectorLiteral = selector ? JSON.stringify(selector) : 'null';
+    return `(() => {
+  const sel = ${selectorLiteral};
+  let root = null;
+  if (sel) {
+    try { root = document.querySelector(sel); }
+    catch (e) {
+      return { invalidSelector: true, reason: (e && e.message) || String(e) };
+    }
+    if (!root) return { notFound: true };
+  } else {
+    root = document.querySelector('main') || document.querySelector('article') || document.body || document.documentElement;
+  }
+  if (!root) return { notFound: true };
+  const clone = root.cloneNode(true);
+  const drop = [
+    'script', 'style', 'noscript', 'template',
+    'nav', 'header', 'footer', 'aside',
+    'iframe', 'svg', 'canvas',
+    'form', 'button', 'input', 'select', 'textarea',
+    '[role="navigation"]', '[role="banner"]', '[role="contentinfo"]', '[role="complementary"]',
+    '[aria-hidden="true"]',
+  ];
+  for (const q of drop) {
+    for (const n of clone.querySelectorAll(q)) n.remove();
+  }
+  // Also strip event-handler and style attributes that bloat markdown output.
+  const walker = document.createTreeWalker(clone, NodeFilter.SHOW_ELEMENT);
+  let n = walker.currentNode;
+  while (n) {
+    if (n.nodeType === 1) {
+      const el = n;
+      for (const a of [...el.attributes]) {
+        if (a.name.startsWith('on') || a.name === 'style' || a.name.startsWith('data-')) el.removeAttribute(a.name);
+      }
+    }
+    n = walker.nextNode();
+  }
+  return { ok: true, url: location.href, title: document.title || '', html: clone.outerHTML || '' };
+})()`;
+}
+/**
+ * Slice `content` into one chunk starting at `start` with target size
+ * `chunkSize`. When the chunk would land mid-paragraph, we pull the break
+ * back to the nearest `\n\n` (or `\n`) within a small window to keep the
+ * output readable. If no boundary is found, we hard-cut at `start+chunkSize`.
+ */
+export function chunkMarkdown(opts) {
+    const { content, start } = opts;
+    const chunkSize = Math.max(MIN_CHUNK_SIZE, Math.min(MAX_CHUNK_SIZE, opts.chunkSize));
+    if (start >= content.length) {
+        return { content: '', start, end: start, nextStartChar: null };
+    }
+    const hardEnd = Math.min(content.length, start + chunkSize);
+    if (hardEnd === content.length) {
+        return { content: content.slice(start, hardEnd), start, end: hardEnd, nextStartChar: null };
+    }
+    const windowSize = Math.max(1, Math.floor(chunkSize * BOUNDARY_WINDOW_RATIO));
+    const windowStart = Math.max(start + 1, hardEnd - windowSize);
+    const slice = content.slice(windowStart, hardEnd);
+    const paraBreak = slice.lastIndexOf('\n\n');
+    let cut = hardEnd;
+    if (paraBreak >= 0) {
+        cut = windowStart + paraBreak + 2;
+    }
+    else {
+        const lineBreak = slice.lastIndexOf('\n');
+        if (lineBreak >= 0)
+            cut = windowStart + lineBreak + 1;
+    }
+    return {
+        content: content.slice(start, cut),
+        start,
+        end: cut,
+        nextStartChar: cut,
+    };
+}
+/** End-to-end host-side pipeline: HTML → markdown → chunked envelope. */
+export function runExtractFromHtml(opts) {
+    const md = htmlToMarkdown(opts.html);
+    const chunk = chunkMarkdown({
+        content: md,
+        start: Math.max(0, opts.start),
+        chunkSize: opts.chunkSize || DEFAULT_CHUNK_SIZE,
+    });
+    return {
+        url: opts.url,
+        title: opts.title,
+        selector: opts.selector,
+        total_chars: md.length,
+        chunk_size: chunk.end - chunk.start,
+        start: chunk.start,
+        end: chunk.end,
+        next_start_char: chunk.nextStartChar,
+        content: chunk.content,
+    };
+}
+export const __extractInternals = {
+    DEFAULT_CHUNK_SIZE,
+    MIN_CHUNK_SIZE,
+    MAX_CHUNK_SIZE,
+};

package/dist/src/browser/extract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/extract.test.js

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import { buildExtractHtmlJs, chunkMarkdown, runExtractFromHtml } from './extract.js';
+describe('chunkMarkdown', () => {
+    it('returns the full content when it fits in one chunk', () => {
+        const content = 'short body';
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 20000 });
+        expect(r.content).toBe(content);
+        expect(r.start).toBe(0);
+        expect(r.end).toBe(content.length);
+        expect(r.nextStartChar).toBeNull();
+    });
+    it('emits next_start_char when more content remains', () => {
+        // Build content long enough that chunkSize cuts it mid-stream.
+        const para = 'p'.repeat(400);
+        const content = [para, para, para].join('\n\n');
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.nextStartChar).not.toBeNull();
+        expect(r.nextStartChar).toBeGreaterThan(0);
+        expect(r.nextStartChar).toBeLessThan(content.length);
+    });
+    it('prefers to break at a paragraph boundary inside the boundary window', () => {
+        // chunkSize=500, window=15% → [425, 500). Place `\n\n` at 450 so it lands
+        // inside the window; the chunker should snap the cut back to it.
+        const a = 'a'.repeat(450);
+        const b = 'b'.repeat(400);
+        const content = `${a}\n\n${b}`;
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.content.endsWith('\n\n')).toBe(true);
+        expect(r.nextStartChar).toBe(r.end);
+        expect(content.slice(r.end).startsWith('b')).toBe(true);
+    });
+    it('falls back to a single newline when no paragraph boundary is in window', () => {
+        // 6 lines × 90 chars joined by `\n` → `\n` at 90, 181, 272, 363, 454.
+        // chunkSize=500 with window [425, 500) catches the `\n` at 454.
+        const line = 'l'.repeat(90);
+        const content = Array.from({ length: 6 }, () => line).join('\n');
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.content.endsWith('\n')).toBe(true);
+        expect(content.slice(r.end).startsWith('l')).toBe(true);
+    });
+    it('hard-cuts when no boundary is found within the window', () => {
+        const content = 'x'.repeat(5000);
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 500 });
+        expect(r.end).toBe(500);
+        expect(r.content).toHaveLength(500);
+        expect(r.nextStartChar).toBe(500);
+    });
+    it('handles start >= content.length with an empty final chunk', () => {
+        const content = 'hello';
+        const r = chunkMarkdown({ content, start: 5, chunkSize: 100 });
+        expect(r.content).toBe('');
+        expect(r.nextStartChar).toBeNull();
+    });
+    it('resumes from a provided start cursor until the stream terminates', () => {
+        const content = `${'a'.repeat(100)}\n\n${'b'.repeat(100)}\n\n${'c'.repeat(100)}`;
+        const first = chunkMarkdown({ content, start: 0, chunkSize: 110 });
+        expect(first.nextStartChar).not.toBeNull();
+        const second = chunkMarkdown({ content, start: first.nextStartChar, chunkSize: 110 });
+        expect(second.start).toBe(first.nextStartChar);
+        expect(second.content.length).toBeGreaterThan(0);
+        let cursor = second.nextStartChar;
+        let safety = 20;
+        while (cursor !== null && safety-- > 0) {
+            const step = chunkMarkdown({ content, start: cursor, chunkSize: 110 });
+            cursor = step.nextStartChar;
+        }
+        expect(cursor).toBeNull();
+    });
+    it('clamps chunk size to the configured minimum', () => {
+        const content = 'a'.repeat(2000);
+        const r = chunkMarkdown({ content, start: 0, chunkSize: 1 });
+        // MIN_CHUNK_SIZE is 100 — requesting 1 should still produce >= 100 chars.
+        expect(r.end).toBeGreaterThanOrEqual(100);
+    });
+});
+describe('runExtractFromHtml', () => {
+    it('converts HTML to markdown and wraps it in the chunking envelope', () => {
+        const html = '<article><h1>Title</h1><p>Hello <strong>world</strong>.</p></article>';
+        const r = runExtractFromHtml({
+            html,
+            url: 'https://example.com/a',
+            title: 'Example',
+            selector: 'article',
+            start: 0,
+            chunkSize: 20000,
+        });
+        expect(r.url).toBe('https://example.com/a');
+        expect(r.title).toBe('Example');
+        expect(r.selector).toBe('article');
+        expect(r.content).toContain('# Title');
+        expect(r.content).toContain('**world**');
+        expect(r.start).toBe(0);
+        expect(r.end).toBe(r.content.length);
+        expect(r.total_chars).toBe(r.content.length);
+        expect(r.next_start_char).toBeNull();
+    });
+    it('reports total_chars and chunk_size against the final markdown', () => {
+        const body = Array.from({ length: 30 }, (_, i) => `<p>paragraph ${i} ${'x'.repeat(200)}</p>`).join('');
+        const r = runExtractFromHtml({
+            html: `<main>${body}</main>`,
+            url: 'https://example.com/b',
+            title: 't',
+            selector: 'main',
+            start: 0,
+            chunkSize: 500,
+        });
+        expect(r.total_chars).toBeGreaterThan(r.end);
+        expect(r.chunk_size).toBe(r.end - r.start);
+        expect(r.next_start_char).toBe(r.end);
+    });
+});
+describe('buildExtractHtmlJs', () => {
+    it('embeds the selector as a JSON literal', () => {
+        const js = buildExtractHtmlJs('main.article');
+        expect(js).toContain('"main.article"');
+    });
+    it('uses null when no selector given', () => {
+        const js = buildExtractHtmlJs(null);
+        // The expression references `sel` and compares to null.
+        expect(js).toContain('const sel = null;');
+    });
+    it('includes the denoise selector list', () => {
+        const js = buildExtractHtmlJs(null);
+        expect(js).toContain("'script'");
+        expect(js).toContain("'nav'");
+        expect(js).toContain("'iframe'");
+        expect(js).toContain("'[aria-hidden=\"true\"]'");
+    });
+});

package/dist/src/browser/find.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `browser find --css <sel>` — structured CSS query.
+ *
+ * Returns every match of a selector as a JSON envelope agents can read
+ * without parsing free-text snapshot output. Each entry carries two
+ * identifiers — a numeric `ref` (matching the snapshot contract) and a
+ * stable 0-based `nth` — so the agent can act on a specific result via
+ * either path:
+ *
+ *   browser click <ref>              // when ref is numeric
+ *   browser click "<sel>" --nth <n>  // always works
+ *
+ * Refs are *allocated on the spot* for matched elements that were not
+ * tagged by a prior snapshot: `data-webcmd-ref` is set on the element
+ * and a fingerprint is written into `window.__webcmd_ref_identity`
+ * (same shape the snapshot uses). That makes `find` a first-class entry
+ * point to the ref system — agents can skip running `browser state`
+ * when they already know the selector.
+ *
+ * Attributes are whitelisted to keep output small and high-signal.
+ * Invisible elements are still returned so agents can reason about
+ * offscreen vs truly-missing targets.
+ *
+ * When a matched element is a compound form control (date-like input,
+ * select, file input), the entry gains a `compound` field with the
+ * rich view from `compound.ts`. This is what kills the three biggest
+ * agent-fail modes on form pages (wrong date format, guessed options,
+ * re-uploaded files) without forcing agents to probe further.
+ */
+import { type CompoundInfo } from './compound.js';
+/** Whitelist of attributes surfaced per entry. Keep small; agents do not need full DOM dumps. */
+export declare const FIND_ATTR_WHITELIST: readonly ["id", "class", "name", "type", "placeholder", "aria-label", "title", "href", "value", "role", "data-testid"];
+export interface FindEntry {
+    /** Zero-based position within the match set — pair with `--nth` on downstream commands. */
+    nth: number;
+    /**
+     * Numeric data-webcmd-ref. Find assigns one if the element was not
+     * tagged by a prior snapshot, so downstream `browser click <ref>` works
+     * directly off the find output without requiring `browser state` first.
+     */
+    ref: number;
+    tag: string;
+    role: string;
+    text: string;
+    attrs: Record<string, string>;
+    visible: boolean;
+    /**
+     * Rich view for date / time / datetime-local / month / week / select /
+     * file inputs. Omitted (undefined) for all other element types. See
+     * `compound.ts` for the shape.
+     */
+    compound?: CompoundInfo;
+}
+export interface FindResult {
+    matches_n: number;
+    entries: FindEntry[];
+}
+export interface FindError {
+    error: {
+        code: 'invalid_selector' | 'selector_not_found' | 'semantic_not_found';
+        message: string;
+        hint?: string;
+    };
+}
+export interface FindOptions {
+    /** Max entries returned. Default 50 — enough to pick from without flooding context. */
+    limit?: number;
+    /** Max chars of trimmed text per entry. Default 120. */
+    textMax?: number;
+}
+export interface SemanticFindOptions extends FindOptions {
+    role?: string;
+    name?: string;
+    label?: string;
+    text?: string;
+    testid?: string;
+}
+/**
+ * Build the browser-side JS that performs the CSS query and emits the
+ * FindResult (or FindError) envelope. Evaluated inside `page.evaluate`.
+ */
+export declare function buildFindJs(selector: string, opts?: FindOptions): string;
+export declare function buildSemanticFindJs(opts: SemanticFindOptions): string;
+export declare function isFindError(result: unknown): result is FindError;