@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/target-errors.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { TargetError } from './target-errors.js';
+describe('TargetError', () => {
+    it('creates not_found error with code and hint', () => {
+        const err = new TargetError({
+            code: 'not_found',
+            message: 'ref=99 not found in DOM',
+            hint: 'Re-run `webcmd browser state` to get a fresh snapshot.',
+        });
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe('TargetError');
+        expect(err.code).toBe('not_found');
+        expect(err.message).toBe('ref=99 not found in DOM');
+        expect(err.hint).toContain('fresh snapshot');
+        expect(err.candidates).toBeUndefined();
+    });
+    it('creates selector_ambiguous error with candidates + matches_n', () => {
+        const err = new TargetError({
+            code: 'selector_ambiguous',
+            message: 'CSS selector ".btn" matched 3 elements',
+            hint: 'Use a more specific selector, or pass --nth.',
+            candidates: ['<button> "Login"', '<button> "Sign Up"', '<button> "Cancel"'],
+            matches_n: 3,
+        });
+        expect(err.code).toBe('selector_ambiguous');
+        expect(err.candidates).toHaveLength(3);
+        expect(err.candidates[0]).toContain('Login');
+        expect(err.matches_n).toBe(3);
+    });
+    it('creates invalid_selector error', () => {
+        const err = new TargetError({
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: >>> (unexpected token)',
+            hint: 'Check the selector syntax.',
+        });
+        expect(err.code).toBe('invalid_selector');
+        expect(err.message).toContain('Invalid CSS selector');
+    });
+    it('creates selector_not_found error with matches_n=0', () => {
+        const err = new TargetError({
+            code: 'selector_not_found',
+            message: 'CSS selector ".missing" matched 0 elements',
+            hint: 'Check the page or use browser find.',
+            matches_n: 0,
+        });
+        expect(err.code).toBe('selector_not_found');
+        expect(err.matches_n).toBe(0);
+    });
+    it('creates selector_nth_out_of_range error', () => {
+        const err = new TargetError({
+            code: 'selector_nth_out_of_range',
+            message: 'matched 3 elements, but --nth=5 is out of range',
+            hint: 'Use --nth between 0 and 2.',
+            matches_n: 3,
+        });
+        expect(err.code).toBe('selector_nth_out_of_range');
+        expect(err.matches_n).toBe(3);
+    });
+    it('creates stale_ref error', () => {
+        const err = new TargetError({
+            code: 'stale_ref',
+            message: 'ref=12 was <button>"Login" but now points to <div>"Header"',
+            hint: 'Re-run `webcmd browser state` to refresh.',
+        });
+        expect(err.code).toBe('stale_ref');
+        expect(err.message).toContain('was <button>');
+    });
+    it('serializes to JSON for structured output', () => {
+        const err = new TargetError({
+            code: 'selector_ambiguous',
+            message: 'matched 3',
+            hint: 'be specific',
+            candidates: ['a', 'b'],
+            matches_n: 3,
+        });
+        const json = err.toJSON();
+        expect(json).toEqual({
+            code: 'selector_ambiguous',
+            message: 'matched 3',
+            hint: 'be specific',
+            candidates: ['a', 'b'],
+            matches_n: 3,
+        });
+    });
+    it('omits candidates from JSON when not present', () => {
+        const err = new TargetError({
+            code: 'not_found',
+            message: 'gone',
+            hint: 'refresh',
+        });
+        const json = err.toJSON();
+        expect(json).not.toHaveProperty('candidates');
+    });
+});

package/dist/src/browser/target-resolver.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Unified target resolver for browser actions.
+ *
+ * Resolution pipeline:
+ *
+ * 1. Input classification: all-digit → numeric ref path, otherwise → CSS path.
+ *    The CSS path passes the raw string to `querySelectorAll` and lets the
+ *    browser parser decide what's valid. No frontend regex whitelist — the
+ *    goal is that any selector accepted by `browser find --css` is accepted
+ *    by the same selector on `get/click/type/select`.
+ * 2. Ref path: cascading match levels (see below), using data-webcmd-ref
+ *    plus the fingerprint map populated by snapshot + find.
+ * 3. CSS path: querySelectorAll + match-count policy (see ResolveOptions)
+ * 4. Structured errors:
+ *    - numeric: not_found / stale_ref
+ *    - CSS:     invalid_selector / selector_not_found / selector_ambiguous
+ *               / selector_nth_out_of_range
+ *
+ * All JS is generated as strings for page.evaluate() — runs in the browser.
+ *
+ * ── Cascading stale-ref (browser-use style) ──────────────────────────
+ * Strict equality on the fingerprint rejected too many live pages — SPA
+ * re-renders swap text / role while keeping id + testId. The resolver
+ * now walks three tiers before giving up:
+ *
+ *   1. EXACT        — tag + strong id (id or testId) agree, ≤1 soft mismatch
+ *   2. STABLE       — tag + strong id agree, soft signals drifted (aria-label,
+ *                     role, text) — agent gets a warning but the action
+ *                     proceeds so dynamic pages don't stall
+ *   3. REIDENTIFIED — original ref either missing from the DOM or fully
+ *                     mismatched, but the fingerprint uniquely identifies
+ *                     a single other live element via id / testId /
+ *                     aria-label. Re-tag that element with the old ref and
+ *                     surface match_level so the caller knows we swapped.
+ *
+ * Only when all three fail do we emit `stale_ref`. Every success envelope
+ * carries `match_level` so downstream CLIs can surface the weakest tier
+ * a caller actually traversed.
+ */
+export interface ResolveOptions {
+    /**
+     * When CSS matches multiple elements, pick the element at this 0-based
+     * index instead of raising `selector_ambiguous`. Raises
+     * `selector_nth_out_of_range` if `nth >= matches.length`.
+     */
+    nth?: number;
+    /**
+     * When CSS matches multiple elements, pick the first match instead of
+     * raising `selector_ambiguous`. Used by read commands (get text / value /
+     * attributes) to deliver a best-effort answer + matches_n in the envelope.
+     * Ignored when `nth` is also set (nth wins).
+     */
+    firstOnMulti?: boolean;
+}
+/** Tier the resolver traversed to land the target. Callers may surface this to agents. */
+export type TargetMatchLevel = 'exact' | 'stable' | 'reidentified';
+/**
+ * Generate JS that resolves a target to a single DOM element.
+ *
+ * Returns a JS expression that evaluates to:
+ *   { ok: true, matches_n, match_level }            — success (el stored in `__resolved`)
+ *   { ok: false, code, message, hint, candidates, matches_n? }  — structured error
+ *
+ * `match_level` is always set on success:
+ *   - CSS path → 'exact'
+ *   - numeric ref path → whichever tier matched ('exact' / 'stable' / 'reidentified')
+ *
+ * The resolved element is stored in `window.__resolved` for downstream helpers.
+ */
+export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): string;
+/**
+ * Generate JS that scrolls + measures `__resolved` without clicking.
+ *
+ * Generic click prefers CDP `Input.dispatchMouseEvent`, which fires the full
+ * pointer/mouse chain that Radix/MUI/shadcn dropdowns rely on. Keep measurement
+ * separate so the CDP-primary path does not call DOM `el.click()` first.
+ */
+export declare function boundingRectResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
+/**
+ * Generate JS for click that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ *
+ * This is the JS fallback path. BasePage.click uses boundingRectResolvedJs for
+ * the CDP-primary path and only reaches this when native click is unavailable
+ * or the target has no usable rect.
+ */
+export declare function clickResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
+/**
+ * Generate JS for type that uses the unified resolver.
+ */
+export declare function typeResolvedJs(text: string): string;
+export type FillResolvedResult = {
+    ok: true;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    reason: string;
+    tag?: string;
+    type?: string;
+    role?: string;
+};
+/**
+ * Prepare the resolved element for native CDP Input.insertText.
+ *
+ * This preserves `browser type`'s existing "replace current text" semantics:
+ * focus the editable target, select its current contents, then let CDP insert
+ * real browser text input so rich editors can update their internal state.
+ */
+export declare function prepareNativeTypeResolvedJs(opts?: {
+    skipScroll?: boolean;
+    skipFocus?: boolean;
+}): string;
+/**
+ * Verify the exact value/text currently held by the resolved editable target.
+ * Assumes resolveTargetJs and prepareNativeTypeResolvedJs have already set
+ * `window.__resolved` to the normalized editable host.
+ */
+export declare function verifyFilledResolvedJs(expected: string): string;
+/**
+ * Generate JS for scrollTo that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ */
+export declare function scrollResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
+/**
+ * Generate JS to get text content of resolved element.
+ */
+export declare function getTextResolvedJs(): string;
+/**
+ * Generate JS to get value of resolved input/textarea element.
+ */
+export declare function getValueResolvedJs(): string;
+/**
+ * Generate JS to get all attributes of resolved element.
+ */
+export declare function getAttributesResolvedJs(): string;
+/**
+ * Generate JS to select an option on a resolved <select> element.
+ */
+export declare function selectResolvedJs(option: string): string;
+/**
+ * Generate JS to check if resolved element is an autocomplete/combobox field.
+ */
+export declare function isAutocompleteResolvedJs(): string;