agentmb 0.1.0 → 0.1.1

package/dist/browser/actions.js

@@ -10,6 +10,7 @@ exports.fill = fill;
 exports.evaluate = evaluate;
 exports.extract = extract;
 exports.screenshot = screenshot;
+exports.annotatedScreenshot = annotatedScreenshot;
 exports.typeText = typeText;
 exports.press = press;
 exports.selectOption = selectOption;
@@ -18,7 +19,38 @@ exports.waitForSelector = waitForSelector;
 exports.waitForUrl = waitForUrl;
 exports.waitForResponse = waitForResponse;
 exports.uploadFile = uploadFile;
+exports.elementMap = elementMap;
+exports.getProperty = getProperty;
+exports.assertState = assertState;
+exports.waitPageStable = waitPageStable;
+exports.dblclick = dblclick;
+exports.focus = focus;
+exports.check = check;
+exports.uncheck = uncheck;
+exports.scroll = scroll;
+exports.scrollIntoView = scrollIntoView;
+exports.drag = drag;
+exports.mouseMove = mouseMove;
+exports.mouseDown = mouseDown;
+exports.mouseUp = mouseUp;
+exports.keyDown = keyDown;
+exports.keyUp = keyUp;
+exports.back = back;
+exports.forward = forward;
+exports.reload = reload;
+exports.waitForText = waitForText;
+exports.waitForLoadState = waitForLoadState;
+exports.waitForFunction = waitForFunction;
+exports.scrollUntil = scrollUntil;
+exports.loadMoreUntil = loadMoreUntil;
 exports.downloadFile = downloadFile;
+exports.clickAt = clickAt;
+exports.wheelAt = wheelAt;
+exports.insertText = insertText;
+exports.getBbox = getBbox;
+exports.setViewport = setViewport;
+exports.clipboardWrite = clipboardWrite;
+exports.clipboardRead = clipboardRead;
 const crypto_1 = __importDefault(require("crypto"));
 const fs_1 = __importDefault(require("fs"));
 class ActionDiagnosticsError extends Error {
@@ -141,6 +173,57 @@ async function screenshot(page, format = 'png', fullPage = false, logger, sessio
         throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
     }
 }
+async function annotatedScreenshot(page, highlights, format = 'png', fullPage = false, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    const STYLE_ID = '__agentmb_hl__';
+    try {
+        // Build and inject highlight CSS
+        const rules = highlights.map(({ selector, color = 'rgba(255,80,80,0.35)', label }) => {
+            // Sanitize color: strip characters that could break out of a CSS value
+            // (curly braces, semicolons, CSS comment markers).
+            const safeColor = color.replace(/[{};]|\/\*|\*\//g, '');
+            // Escape label for use inside a single-quoted CSS content string:
+            // backslash must be escaped first, then quote, then control chars.
+            const safeLabel = label
+                ? label
+                    .replace(/\\/g, '\\\\') // backslash → \\
+                    .replace(/'/g, "\\'") // single-quote → \'
+                    .replace(/\n/g, '\\A ') // newline → CSS unicode escape
+                    .replace(/\r/g, '') // carriage return → strip
+                : '';
+            return [
+                `${selector} { outline: 3px solid ${safeColor} !important; background-color: ${safeColor} !important; position: relative !important; }`,
+                safeLabel
+                    ? `${selector}::before { content: '${safeLabel}'; position: absolute; top: 0; left: 0; background: ${safeColor}; color: #000; font-size: 11px; padding: 1px 3px; z-index: 99999; pointer-events: none; }`
+                    : '',
+            ].join('\n');
+        }).join('\n');
+        await page.evaluate(({ styleId, css }) => {
+            const el = globalThis.document.createElement('style');
+            el.id = styleId;
+            el.textContent = css;
+            globalThis.document.head.appendChild(el);
+        }, { styleId: STYLE_ID, css: rules });
+        const buffer = await page.screenshot({ type: format, fullPage });
+        const duration_ms = Date.now() - t0;
+        const data = buffer.toString('base64');
+        // Remove injected style
+        await page.evaluate((styleId) => {
+            globalThis.document.getElementById(styleId)?.remove();
+        }, STYLE_ID).catch(() => { });
+        const result = { status: 'ok', data, format, highlight_count: highlights.length, duration_ms };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'annotated_screenshot', url: page.url(), params: { format, full_page: fullPage, highlights: highlights.length }, result: { status: 'ok', size_bytes: buffer.length, duration_ms }, purpose, operator });
+        return result;
+    }
+    catch (err) {
+        // Clean up injected style on error too
+        await page.evaluate((styleId) => {
+            globalThis.document.getElementById(styleId)?.remove();
+        }, STYLE_ID).catch(() => { });
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
 // ---------------------------------------------------------------------------
 // R05 actions
 // ---------------------------------------------------------------------------
@@ -262,6 +345,564 @@ async function uploadFile(page, selector, fileContent, filename, mimeType = 'app
         throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
     }
 }
+/**
+ * Scan the page for interactive/visible elements, inject `data-agentmb-eid`
+ * attributes for stable re-targeting, and return an ordered map.
+ * Subsequent actions may use element_id instead of a CSS selector.
+ */
+async function elementMap(page, opts = {}, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        const { scope, limit = 500 } = opts;
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        const elements = await page.evaluate(([scopeSelector, maxElements]) => {
+            const doc = globalThis.document;
+            const win = globalThis.window;
+            const root = scopeSelector ? (doc.querySelector(scopeSelector) ?? doc.body) : doc.body;
+            // Remove previous scan IDs
+            root.querySelectorAll('[data-agentmb-eid]').forEach((el) => el.removeAttribute('data-agentmb-eid'));
+            const SELECTORS = [
+                'a[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea',
+                '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]',
+                '[role="menuitem"]', '[role="tab"]', '[role="option"]', '[role="combobox"]',
+                '[role="switch"]', '[role="spinbutton"]', '[role="slider"]',
+                '[tabindex]:not([tabindex="-1"])', 'label[for]',
+            ].join(',');
+            const candidates = Array.from(root.querySelectorAll(SELECTORS));
+            let counter = 0;
+            const results = [];
+            for (const el of candidates) {
+                if (counter >= maxElements)
+                    break;
+                const style = win.getComputedStyle(el);
+                if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0)
+                    continue;
+                const rect = el.getBoundingClientRect();
+                if (rect.width === 0 && rect.height === 0)
+                    continue;
+                counter++;
+                const eid = `e${counter}`;
+                el.setAttribute('data-agentmb-eid', eid);
+                const cx = rect.left + rect.width / 2;
+                const cy = rect.top + rect.height / 2;
+                const topEl = doc.elementFromPoint(cx, cy);
+                const overlayBlocked = topEl ? (!el.contains(topEl) && !topEl.contains(el) && topEl !== el) : false;
+                results.push({
+                    element_id: eid,
+                    tag: el.tagName.toLowerCase(),
+                    role: el.getAttribute('role') ?? el.tagName.toLowerCase(),
+                    text: (el.innerText ?? el.textContent ?? '').trim().slice(0, 200),
+                    name: el.getAttribute('name') ?? el.getAttribute('aria-label') ?? '',
+                    placeholder: el.getAttribute('placeholder') ?? '',
+                    href: el.getAttribute('href') ?? '',
+                    type: el.getAttribute('type') ?? '',
+                    overlay_blocked: overlayBlocked,
+                    rect: {
+                        x: Math.round(rect.x), y: Math.round(rect.y),
+                        width: Math.round(rect.width), height: Math.round(rect.height),
+                    },
+                });
+            }
+            return results;
+        }, [scope, limit]);
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+        const duration_ms = Date.now() - t0;
+        const result = { status: 'ok', url: page.url(), elements, count: elements.length, duration_ms };
+        logger?.write({
+            session_id: sessionId, action_id: id, type: 'action', action: 'element_map',
+            url: page.url(), params: { scope: scope ?? null, limit },
+            result: { status: 'ok', count: elements.length, duration_ms }, purpose, operator,
+        });
+        return result;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function getProperty(page, selector, property, attrName, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        let value;
+        switch (property) {
+            case 'text':
+                value = await page.locator(selector).first().innerText({ timeout: 5000 });
+                break;
+            case 'html':
+                value = await page.locator(selector).first().innerHTML({ timeout: 5000 });
+                break;
+            case 'value':
+                value = await page.locator(selector).first().inputValue({ timeout: 5000 });
+                break;
+            case 'attr':
+                if (!attrName)
+                    throw new Error('attr_name is required when property=attr');
+                value = await page.locator(selector).first().getAttribute(attrName, { timeout: 5000 });
+                break;
+            case 'count':
+                value = await page.locator(selector).count();
+                break;
+            case 'box':
+                value = await page.locator(selector).first().boundingBox({ timeout: 5000 });
+                break;
+        }
+        const duration_ms = Date.now() - t0;
+        const result = { status: 'ok', selector, property, value, duration_ms };
+        logger?.write({
+            session_id: sessionId, action_id: id, type: 'action', action: 'get',
+            url: page.url(), selector, params: { property, attr_name: attrName ?? null },
+            result: { status: 'ok', duration_ms }, purpose, operator,
+        });
+        return result;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function assertState(page, selector, property, expected = true, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        let actual;
+        const loc = page.locator(selector).first();
+        switch (property) {
+            case 'visible':
+                actual = await loc.isVisible({ timeout: 5000 });
+                break;
+            case 'enabled':
+                actual = await loc.isEnabled({ timeout: 5000 });
+                break;
+            case 'checked':
+                actual = await loc.isChecked({ timeout: 5000 });
+                break;
+        }
+        const passed = actual === expected;
+        const duration_ms = Date.now() - t0;
+        const result = { status: 'ok', selector, property, actual, expected, passed, duration_ms };
+        logger?.write({
+            session_id: sessionId, action_id: id, type: 'action', action: 'assert',
+            url: page.url(), selector, params: { property, expected },
+            result: { status: 'ok', passed, duration_ms }, purpose, operator,
+        });
+        return result;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+// ---------------------------------------------------------------------------
+// R07-T07: wait_page_stable — network idle + DOM quiescence + overlay check
+// ---------------------------------------------------------------------------
+async function waitPageStable(page, opts = {}, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    const { timeout_ms = 10000, dom_stable_ms = 300, overlay_selector } = opts;
+    try {
+        // 1. Network idle
+        await page.waitForLoadState('networkidle', { timeout: timeout_ms });
+        // 2. DOM mutation quiescence — MutationObserver waits for `dom_stable_ms` of silence
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        await page.evaluate(([stabilityMs, timeoutMs]) => new Promise((resolve, reject) => {
+            const doc = globalThis.document;
+            let timer;
+            const settle = () => {
+                clearTimeout(timer);
+                timer = setTimeout(() => {
+                    observer.disconnect();
+                    resolve();
+                }, stabilityMs);
+            };
+            const observer = new globalThis.MutationObserver(settle);
+            observer.observe(doc.documentElement, { childList: true, subtree: true, attributes: false });
+            settle();
+            setTimeout(() => {
+                observer.disconnect();
+                clearTimeout(timer);
+                reject(new Error('DOM stability timeout'));
+            }, Math.max(0, timeoutMs));
+        }), [dom_stable_ms, Math.max(500, timeout_ms - (Date.now() - t0))]);
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+        // 3. Overlay check — wait until overlay_selector matches no elements
+        if (overlay_selector) {
+            const deadline = t0 + timeout_ms;
+            while (Date.now() < deadline) {
+                const count = await page.locator(overlay_selector).count();
+                if (count === 0)
+                    break;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+            const remaining = await page.locator(overlay_selector).count();
+            if (remaining > 0) {
+                throw new Error(`Overlay '${overlay_selector}' still present after ${timeout_ms}ms`);
+            }
+        }
+        const duration_ms = Date.now() - t0;
+        const result = { status: 'ok', url: page.url(), waited_ms: duration_ms, duration_ms };
+        logger?.write({
+            session_id: sessionId, action_id: id, type: 'action', action: 'wait_page_stable',
+            url: page.url(), params: { timeout_ms, dom_stable_ms, overlay_selector: overlay_selector ?? null },
+            result: { status: 'ok', duration_ms }, purpose, operator,
+        });
+        return result;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+// ---------------------------------------------------------------------------
+// R07-T03: Interaction primitives — dblclick / focus / check / uncheck /
+//          scroll / scroll_into_view / drag + low-level mouse/keyboard
+// ---------------------------------------------------------------------------
+async function dblclick(page, selector, timeoutMs = 5000, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.locator(selector).first().dblclick({ timeout: timeoutMs });
+        const r = { status: 'ok', selector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'dblclick', url: page.url?.(), selector, params: { timeout_ms: timeoutMs }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function focus(page, selector, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.locator(selector).first().focus();
+        const r = { status: 'ok', selector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'focus', url: page.url?.(), selector, params: {}, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function check(page, selector, timeoutMs = 5000, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.locator(selector).first().check({ timeout: timeoutMs });
+        const r = { status: 'ok', selector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'check', url: page.url?.(), selector, params: { timeout_ms: timeoutMs }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function uncheck(page, selector, timeoutMs = 5000, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.locator(selector).first().uncheck({ timeout: timeoutMs });
+        const r = { status: 'ok', selector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'uncheck', url: page.url?.(), selector, params: { timeout_ms: timeoutMs }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function scroll(page, selector, opts = {}, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    const { delta_x = 0, delta_y = 300 } = opts;
+    try {
+        // Hover over the element, then use mouse wheel (works for both scroll containers and page)
+        const box = await page.locator(selector).first().boundingBox();
+        if (box) {
+            const cx = box.x + box.width / 2;
+            const cy = box.y + box.height / 2;
+            await page.mouse?.move(cx, cy);
+            await page.mouse?.wheel(delta_x, delta_y);
+        }
+        else {
+            // Fallback: scroll the element itself via evaluate
+            /* eslint-disable @typescript-eslint/no-explicit-any */
+            await page.locator(selector).first().evaluate((el, args) => el.scrollBy(args[0], args[1]), [delta_x, delta_y]);
+            /* eslint-enable @typescript-eslint/no-explicit-any */
+        }
+        const r = { status: 'ok', selector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'scroll', url: page.url?.(), selector, params: { delta_x, delta_y }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function scrollIntoView(page, selector, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.locator(selector).first().scrollIntoViewIfNeeded();
+        const r = { status: 'ok', selector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'scroll_into_view', url: page.url?.(), selector, params: {}, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function drag(page, sourceSelector, targetSelector, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.dragAndDrop(sourceSelector, targetSelector);
+        const r = { status: 'ok', source: sourceSelector, target: targetSelector, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'drag', url: page.url(), params: { source: sourceSelector, target: targetSelector }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function mouseMove(page, x, y, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.mouse.move(x, y);
+        const r = { status: 'ok', x, y, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'mouse_move', url: page.url(), params: { x, y }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function mouseDown(page, opts = {}, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        if (opts.x !== undefined && opts.y !== undefined) {
+            await page.mouse.move(opts.x, opts.y);
+        }
+        await page.mouse.down({ button: opts.button ?? 'left' });
+        const r = { status: 'ok', duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'mouse_down', url: page.url(), params: opts, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function mouseUp(page, button = 'left', logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.mouse.up({ button });
+        const r = { status: 'ok', duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'mouse_up', url: page.url(), params: { button }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function keyDown(page, key, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.keyboard.down(key);
+        const r = { status: 'ok', key, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'key_down', url: page.url(), params: { key }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function keyUp(page, key, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.keyboard.up(key);
+        const r = { status: 'ok', key, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'key_up', url: page.url(), params: { key }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+// ---------------------------------------------------------------------------
+// R07-T04: Wait / navigation control — back / forward / reload / wait_text /
+//          wait_load_state / wait_function
+// ---------------------------------------------------------------------------
+async function back(page, timeoutMs = 5000, waitUntil = 'load', logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.goBack({ timeout: timeoutMs, waitUntil });
+        const r = { status: 'ok', url: page.url(), duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'back', url: page.url(), params: { timeout_ms: timeoutMs, wait_until: waitUntil }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function forward(page, timeoutMs = 5000, waitUntil = 'load', logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.goForward({ timeout: timeoutMs, waitUntil });
+        const r = { status: 'ok', url: page.url(), duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'forward', url: page.url(), params: { timeout_ms: timeoutMs, wait_until: waitUntil }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function reload(page, timeoutMs = 10000, waitUntil = 'load', logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.reload({ timeout: timeoutMs, waitUntil });
+        const r = { status: 'ok', url: page.url(), duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'reload', url: page.url(), params: { timeout_ms: timeoutMs, wait_until: waitUntil }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function waitForText(page, text, timeoutMs = 5000, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.getByText(text).first().waitFor({ state: 'visible', timeout: timeoutMs });
+        const r = { status: 'ok', text, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'wait_text', url: page.url?.(), params: { text, timeout_ms: timeoutMs }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function waitForLoadState(page, state = 'load', timeoutMs = 10000, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.waitForLoadState(state, { timeout: timeoutMs });
+        const r = { status: 'ok', state, url: page.url(), duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'wait_load_state', url: page.url(), params: { state, timeout_ms: timeoutMs }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function waitForFunction(page, expression, timeoutMs = 5000, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.waitForFunction(expression, undefined, { timeout: timeoutMs });
+        const r = { status: 'ok', url: page.url(), duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'wait_function', url: page.url(), params: { expression, timeout_ms: timeoutMs }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+// ---------------------------------------------------------------------------
+// R07-T08: Generic scroll primitives — scroll_until / load_more_until
+// ---------------------------------------------------------------------------
+async function scrollUntil(page, opts = {}, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    const { direction = 'down', scroll_selector, stop_selector, stop_text, max_scrolls = 20, scroll_delta = 400, stall_ms = 500, } = opts;
+    const dx = direction === 'right' ? scroll_delta : direction === 'left' ? -scroll_delta : 0;
+    const dy = direction === 'down' ? scroll_delta : direction === 'up' ? -scroll_delta : 0;
+    let scrolls = 0;
+    let stop_reason = 'max_scrolls';
+    try {
+        for (let i = 0; i < max_scrolls; i++) {
+            // Check stop conditions before scrolling
+            if (stop_selector) {
+                const count = await page.locator(stop_selector).count();
+                if (count > 0) {
+                    stop_reason = 'selector_found';
+                    break;
+                }
+            }
+            if (stop_text) {
+                const found = await page.evaluate((t) => globalThis.document?.body?.innerText?.includes(t) ?? false, stop_text);
+                if (found) {
+                    stop_reason = 'text_found';
+                    break;
+                }
+            }
+            // Perform scroll
+            if (scroll_selector) {
+                const box = await page.locator(scroll_selector).first().boundingBox();
+                if (box) {
+                    await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+                }
+            }
+            await page.mouse.wheel(dx, dy);
+            scrolls++;
+            await new Promise((r) => setTimeout(r, stall_ms));
+        }
+        const r = { status: 'ok', scrolls_performed: scrolls, stop_reason, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'scroll_until', url: page.url(), params: opts, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+async function loadMoreUntil(page, opts, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    const { load_more_selector, content_selector, item_count, stop_text, max_loads = 10, stall_ms = 800 } = opts;
+    let loads = 0;
+    let stop_reason = 'max_loads';
+    let prev_count = -1;
+    try {
+        for (let i = 0; i < max_loads; i++) {
+            const current = await page.locator(content_selector).count();
+            // Check stop conditions
+            if (item_count !== undefined && current >= item_count) {
+                stop_reason = 'item_count_reached';
+                break;
+            }
+            if (stop_text) {
+                const found = await page.evaluate((t) => globalThis.document?.body?.innerText?.includes(t) ?? false, stop_text);
+                if (found) {
+                    stop_reason = 'text_found';
+                    break;
+                }
+            }
+            // Stall detection: no new items
+            if (current === prev_count) {
+                stop_reason = 'stalled';
+                break;
+            }
+            prev_count = current;
+            // Check load-more button exists
+            const btnCount = await page.locator(load_more_selector).count();
+            if (btnCount === 0) {
+                stop_reason = 'load_more_gone';
+                break;
+            }
+            await page.click(load_more_selector);
+            loads++;
+            await new Promise((r) => setTimeout(r, stall_ms));
+        }
+        const final_count = await page.locator(content_selector).count();
+        const r = { status: 'ok', loads_performed: loads, final_count, stop_reason, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'load_more_until', url: page.url(), params: opts, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
 async function downloadFile(page, selector, timeoutMs = 30000, maxBytes = 50 * 1024 * 1024, logger, sessionId, purpose, operator) {
     const id = actionId();
     const t0 = Date.now();
@@ -288,4 +929,160 @@ async function downloadFile(page, selector, timeoutMs = 30000, maxBytes = 50 * 1
         throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
     }
 }
+// ---------------------------------------------------------------------------
+// R07-C04: T19 — coordinate-based primitives (click_at / wheel / insert_text)
+// ---------------------------------------------------------------------------
+/** Click at an absolute page coordinate. */
+async function clickAt(page, x, y, opts = {}, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.mouse.click(x, y, {
+            button: opts.button ?? 'left',
+            clickCount: opts.click_count ?? 1,
+            delay: opts.delay_ms ?? 0,
+        });
+        const r = { status: 'ok', x, y, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'click_at', url: page.url(), params: { x, y, ...opts }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+/** Dispatch a mouse wheel event at the current cursor position. */
+async function wheelAt(page, dx, dy, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.mouse.wheel(dx, dy);
+        const r = { status: 'ok', dx, dy, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'wheel_at', url: page.url(), params: { dx, dy }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+/**
+ * Insert text directly into the focused element, bypassing key events.
+ * Useful for emoji, CJK characters, or any input that would be mangled
+ * by synthesised keydown/keyup sequences.
+ */
+async function insertText(page, text, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.keyboard.insertText(text);
+        const r = { status: 'ok', length: text.length, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'insert_text', url: page.url(), params: { length: text.length }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+/** Return the bounding box of the first element matching *selector*. */
+async function getBbox(page, selector, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        // Use a short timeout so non-existent selectors return found:false immediately
+        // instead of waiting for the default 30s Playwright timeout.
+        let box = null;
+        try {
+            box = await page.locator(selector).first().boundingBox({ timeout: 2000 });
+        }
+        catch (_te) {
+            box = null; // element not found within timeout → treat as not-found
+        }
+        const duration_ms = Date.now() - t0;
+        if (!box) {
+            const r = { status: 'ok', selector, found: false, x: 0, y: 0, width: 0, height: 0, center_x: 0, center_y: 0, duration_ms };
+            logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'bbox', url: page.url(), params: { selector }, result: r, purpose, operator });
+            return r;
+        }
+        const r = {
+            status: 'ok', selector, found: true,
+            x: box.x, y: box.y, width: box.width, height: box.height,
+            center_x: box.x + box.width / 2, center_y: box.y + box.height / 2,
+            duration_ms,
+        };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'bbox', url: page.url(), params: { selector }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+// ---------------------------------------------------------------------------
+// R07-C04: T24 — viewport emulation
+// ---------------------------------------------------------------------------
+async function setViewport(page, width, height, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.setViewportSize({ width, height });
+        const r = { status: 'ok', width, height, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'set_viewport', url: page.url(), params: { width, height }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+// ---------------------------------------------------------------------------
+// R07-C04: T23 — clipboard read/write
+// ---------------------------------------------------------------------------
+/** Write *text* to the system clipboard via the Clipboard API. */
+async function clipboardWrite(page, text, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        await page.evaluate(async (t) => {
+            if (navigator.clipboard?.writeText) {
+                await navigator.clipboard.writeText(t);
+            }
+            else {
+                // execCommand fallback (deprecated but reliable in Chromium)
+                // Use globalThis to avoid TypeScript node-lib "document not found" error
+                const doc = globalThis.document;
+                const el = doc.createElement('textarea');
+                el.value = t;
+                el.style.position = 'fixed';
+                el.style.opacity = '0';
+                doc.body.appendChild(el);
+                el.select();
+                doc.execCommand('copy');
+                el.remove();
+            }
+        }, text);
+        const r = { status: 'ok', length: text.length, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'clipboard_write', url: page.url(), params: { length: text.length }, result: r, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
+/**
+ * Read text from the system clipboard.
+ * Requires the `clipboard-read` permission; may fail in restricted headless
+ * environments.  Grant via `context.grantPermissions(['clipboard-read'])`.
+ */
+async function clipboardRead(page, logger, sessionId, purpose, operator) {
+    const id = actionId();
+    const t0 = Date.now();
+    try {
+        const text = await page.evaluate(async () => {
+            return await navigator.clipboard.readText();
+        });
+        const r = { status: 'ok', text, duration_ms: Date.now() - t0 };
+        logger?.write({ session_id: sessionId, action_id: id, type: 'action', action: 'clipboard_read', url: page.url(), params: {}, result: { status: 'ok', length: text.length, duration_ms: r.duration_ms }, purpose, operator });
+        return r;
+    }
+    catch (err) {
+        throw new ActionDiagnosticsError(await collectDiagnostics(page, t0, err));
+    }
+}
 //# sourceMappingURL=actions.js.map