@weavetab/mcp 2.5.0-beta.0

package/dist/sensors/actionability.js

@@ -0,0 +1,303 @@
+/**
+ * src/sensors/actionability.ts
+ *
+ * Playwright-Strategy Actionability Engine for WeaveTab
+ * ─────────────────────────────────────────────────────
+ * Implements every correctness principle from playwright-strategy.md:
+ *
+ *  1. RAF-stability gate     — element must not be animating before we touch it
+ *  2. Strict hit-target      — elementsFromPoint at the computed click point must
+ *                              confirm the target is on top (or the target's child).
+ *  3. WeaveTab transparency  — WeaveTab's own UI (data-wt-ignore nodes) is excluded
+ *                              from the hit stack so the tool never blocks itself.
+ *  4. 4-way scroll rotation  — escape sticky headers / overlays by cycling four
+ *                              scrollIntoView alignments before giving up.
+ *  5. Per-action backoff     — [0, 20, 100, 100, 500] ms retry on transient failures.
+ *  6. Rich blocker report    — on permanent occlusion, return the blocking element's
+ *                              description so the model can reason about it.
+ *
+ * Usage:
+ *   import { verifyActionability } from "../sensors/actionability.js";
+ *   const result = await verifyActionability(session, selector);
+ *   if (result.status !== "ACTIONABLE") { ... }
+ */
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Playwright's per-action retry backoff (ms). */
+const BACKOFF = [0, 20, 100, 100, 500];
+/**
+ * 4-way scroll alignment rotation — escape sticky headers.
+ * undefined = browser default (nearest), then progressively more aggressive.
+ */
+const SCROLL_ALIGNMENTS = [
+    undefined,
+    { block: "end", inline: "end" },
+    { block: "center", inline: "center" },
+    { block: "start", inline: "start" },
+];
+/**
+ * Injected expression that does the full Playwright-style actionability check
+ * in the page context. Returns a serialisable result object.
+ *
+ * Parameters injected at build-time via template literals:
+ *   selector        — CSS selector string
+ *   scrollOptionsJSON — JSON string of ScrollIntoViewOptions or "null"
+ *   fingerprintJSON   — JSON string of {tag,role} or "null"
+ *   stabilityMs       — ms to wait for stable rect
+ */
+function buildPageExpression(selector, scrollOptions, fingerprint, stabilityMs) {
+    const selectorLiteral = JSON.stringify(selector);
+    const scrollLiteral = scrollOptions ? JSON.stringify(scrollOptions) : "null";
+    const fingerprintLiteral = fingerprint ? JSON.stringify(fingerprint) : "null";
+    return `(async function() {
+    // ── Helper: is this node owned by WeaveTab? ────────────────────────────
+    function isWtOwned(el) {
+      if (!el) return false;
+      // Attribute-based markers: data-wt-ignore and data-wt-internal both signal
+      // WeaveTab-owned UI that must not block page interactions.
+      if (el.getAttribute && (
+        el.getAttribute('data-wt-ignore') !== null ||
+        el.getAttribute('data-wt-internal') !== null ||
+        el.getAttribute('data-wt-overlay') !== null
+      )) return true;
+      const wtIds = ['Weavetab-hud', '__Weavetab_controlled_indicator', 'wt-main-container', 'wt-system-icon', 'wt-f3-host', 'Weavetab-root'];
+      if (el.id && wtIds.includes(el.id)) return true;
+      if (el.closest) {
+        if (el.closest('[data-wt-ignore],[data-wt-internal],[data-wt-overlay]')) return true;
+        if (wtIds.some(id => el.closest('#' + id))) return true;
+      }
+      return false;
+    }
+
+    // ── Step 1: Resolve element ────────────────────────────────────────────
+    let el = document.querySelector(${selectorLiteral});
+    if (!el && window.__Weavetab_shadowQuery) {
+      el = window.__Weavetab_shadowQuery(${selectorLiteral});
+    }
+    if (!el) return { status: 'NOT_FOUND' };
+
+    // ── Step 2: Fingerprint check ──────────────────────────────────────────
+    const fp = ${fingerprintLiteral};
+    if (fp) {
+      if (fp.tag && el.tagName.toLowerCase() !== fp.tag.toLowerCase())
+        return { status: 'FINGERPRINT_MISMATCH' };
+      if (fp.role && el.getAttribute('role') !== fp.role)
+        return { status: 'FINGERPRINT_MISMATCH' };
+    }
+
+    // ── Step 3: Basic visibility ───────────────────────────────────────────
+    // Use checkVisibility() (Chrome 105+) as the most reliable single check.
+    // Falls back to manual computed-style + rect checks for older runtimes.
+    if (typeof el.checkVisibility === 'function') {
+      if (!el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }))
+        return { status: 'INVISIBLE' };
+    } else {
+      const cs = window.getComputedStyle(el);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0')
+        return { status: 'INVISIBLE' };
+    }
+
+    let rect = el.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return { status: 'INVISIBLE' };
+    // Off-screen by more than 2× viewport dimension in any direction
+    if (rect.right < -window.innerWidth || rect.bottom < -window.innerHeight ||
+        rect.left > 2 * window.innerWidth || rect.top > 2 * window.innerHeight)
+      return { status: 'INVISIBLE' };
+
+    // ── Step 4: Scroll into view (using provided alignment) ────────────────
+    const scrollOpts = ${scrollLiteral};
+    if (scrollOpts) {
+      el.scrollIntoView(scrollOpts);
+      await new Promise(r => setTimeout(r, 120));
+    } else if (rect.top < 0 || rect.bottom > window.innerHeight ||
+               rect.left < 0 || rect.right > window.innerWidth) {
+      el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+      await new Promise(r => setTimeout(r, 120));
+    }
+    rect = el.getBoundingClientRect();
+
+    // ── Step 5: RAF-stability gate ─────────────────────────────────────────
+    const stabilityDeadline = Date.now() + ${stabilityMs};
+    let prevRect = el.getBoundingClientRect();
+    let stable = false;
+    while (Date.now() < stabilityDeadline) {
+      await new Promise(r => requestAnimationFrame(r));
+      await new Promise(r => requestAnimationFrame(r)); // two ticks like Playwright
+      const cur = el.getBoundingClientRect();
+      if (
+        Math.abs(cur.x - prevRect.x) < 0.5 &&
+        Math.abs(cur.y - prevRect.y) < 0.5 &&
+        Math.abs(cur.width - prevRect.width) < 0.5 &&
+        Math.abs(cur.height - prevRect.height) < 0.5
+      ) {
+        stable = true;
+        break;
+      }
+      prevRect = cur;
+    }
+    if (!stable) return { status: 'UNSTABLE' };
+    rect = el.getBoundingClientRect();
+
+    // ── Step 6: Compute click centre (clamped to viewport) ─────────────────
+    const cx = Math.round(Math.min(Math.max(rect.left + rect.width / 2, 0), window.innerWidth - 1));
+    const cy = Math.round(Math.min(Math.max(rect.top + rect.height / 2, 0), window.innerHeight - 1));
+
+    // ── Step 7: Strict hit-target check ───────────────────────────────────
+    // elementsFromPoint returns the full composited stack, topmost first.
+    const stack = document.elementsFromPoint(cx, cy);
+    if (!stack || stack.length === 0) return { status: 'ACTIONABLE', x: cx, y: cy };
+
+    // Walk from the topmost element. Anything that is WeaveTab-owned is
+    // transparent — skip it. The first non-WT element must be el or its descendant.
+    let blocker = null;
+    for (const hit of stack) {
+      if (isWtOwned(hit)) continue;  // WeaveTab transparency
+      blocker = hit;
+      break;
+    }
+
+    if (!blocker || blocker === el || el.contains(blocker)) {
+      return { status: 'ACTIONABLE', x: cx, y: cy };
+    }
+
+    // Check composed tree (shadow DOM + slots)
+    let ancestor = blocker;
+    while (ancestor) {
+      if (ancestor === el) return { status: 'ACTIONABLE', x: cx, y: cy };
+      ancestor = ancestor.assignedSlot || ancestor.parentElement ||
+                 (ancestor.getRootNode && ancestor.getRootNode({ composed: true }) !== ancestor
+                   ? ancestor.getRootNode({ composed: true }).host : null);
+    }
+
+    return {
+      status: 'OCCLUDED',
+      x: cx, y: cy,
+      occludedBy: {
+        tag: blocker.tagName.toLowerCase(),
+        id: blocker.id || '',
+        className: (blocker.className && typeof blocker.className === 'string')
+          ? blocker.className.slice(0, 60) : '',
+        ariaLabel: blocker.getAttribute('aria-label') || blocker.getAttribute('title') || null,
+        isWeavetabOwned: isWtOwned(blocker)
+      }
+    };
+  })()`;
+}
+// ── Main export ───────────────────────────────────────────────────────────────
+/**
+ * Full Playwright-strategy actionability verification.
+ *
+ * Runs up to `BACKOFF.length` attempts with 4-way scroll rotation,
+ * RAF stability gating, WeaveTab-transparent hit-target checking,
+ * and per-attempt retry backoff.
+ *
+ * Returns `status: "ACTIONABLE"` with computed (x, y) when safe to dispatch,
+ * or a failure status with an optional `occludedBy` description.
+ */
+export async function verifyActionability(session, selector, opts = {}) {
+    const stabilityMs = opts.stabilityTimeoutMs ?? 300;
+    const totalDeadline = Date.now() + (opts.totalTimeoutMs ?? 2000);
+    let lastResult = { status: "NOT_FOUND" };
+    let scrollIdx = 0;
+    for (let attempt = 0; attempt < BACKOFF.length; attempt++) {
+        // Honour total time budget
+        if (Date.now() >= totalDeadline)
+            break;
+        // Backoff delay (first attempt is instant)
+        if (BACKOFF[attempt] > 0) {
+            await new Promise((r) => setTimeout(r, BACKOFF[attempt]));
+        }
+        const scrollAlignment = SCROLL_ALIGNMENTS[scrollIdx % SCROLL_ALIGNMENTS.length];
+        const expr = buildPageExpression(selector, scrollAlignment, opts.fingerprint, stabilityMs);
+        let raw;
+        try {
+            const { result } = await session.Runtime.evaluate({
+                expression: expr,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+            raw = result?.value;
+        }
+        catch {
+            // CDP error — element might have been detached; retry
+            continue;
+        }
+        if (!raw)
+            continue;
+        lastResult = raw;
+        switch (lastResult.status) {
+            case "ACTIONABLE":
+                return lastResult;
+            case "NOT_FOUND":
+            case "FINGERPRINT_MISMATCH":
+            case "INVISIBLE":
+                // These are likely permanent; still retry in case of SPA re-render
+                break;
+            case "UNSTABLE":
+                // Give the animation more time on next attempt
+                break;
+            case "OCCLUDED": {
+                const occ = lastResult.occludedBy;
+                // If the only blocker is WeaveTab's own UI, treat as transparent and retry
+                if (occ?.isWeavetabOwned) {
+                    lastResult = { status: "ACTIONABLE", x: lastResult.x, y: lastResult.y };
+                    return lastResult;
+                }
+                // Advance scroll alignment to try to escape the blocker
+                scrollIdx++;
+                break;
+            }
+        }
+    }
+    return lastResult;
+}
+// ── Convenience wrapper ───────────────────────────────────────────────────────
+/**
+ * Quick check: is an element at these coords actually blocked by a non-WT overlay?
+ * Used for lightweight pre-dispatch validation inside click.ts.
+ */
+export async function quickHitCheck(session, x, y, selectorOfTarget) {
+    const expr = `(function() {
+    function isWtOwned(el) {
+      if (!el) return false;
+      if (el.getAttribute && (
+        el.getAttribute('data-wt-ignore') !== null ||
+        el.getAttribute('data-wt-internal') !== null ||
+        el.getAttribute('data-wt-overlay') !== null
+      )) return true;
+      const ids = ['Weavetab-hud','__Weavetab_controlled_indicator','wt-main-container','wt-system-icon','wt-f3-host','Weavetab-root'];
+      if (el.id && ids.includes(el.id)) return true;
+      return !!(el.closest && (el.closest('[data-wt-ignore],[data-wt-internal],[data-wt-overlay]') || ids.some(id => el.closest('#' + id))));
+    }
+    const target = document.querySelector(${JSON.stringify(selectorOfTarget)})
+      || (window.__Weavetab_shadowQuery ? window.__Weavetab_shadowQuery(${JSON.stringify(selectorOfTarget)}) : null);
+    const stack = document.elementsFromPoint(${x}, ${y});
+    if (!stack || !stack.length) return { clear: true };
+    for (const hit of stack) {
+      if (isWtOwned(hit)) continue;
+      if (!target || hit === target || target.contains(hit)) return { clear: true };
+      // Walk composed tree for shadow DOM
+      let ancestor = hit;
+      while (ancestor) {
+        if (ancestor === target) return { clear: true };
+        ancestor = ancestor.assignedSlot || ancestor.parentElement ||
+          (ancestor.getRootNode && ancestor.getRootNode({composed:true}) !== ancestor
+            ? ancestor.getRootNode({composed:true}).host : null);
+      }
+      return {
+        clear: false,
+        blockerDescription: hit.tagName.toLowerCase() +
+          (hit.id ? '#' + hit.id : '') +
+          (hit.className && typeof hit.className === 'string' ? '.' + hit.className.split(' ')[0] : '') +
+          ' intercepts pointer events'
+      };
+    }
+    return { clear: true };
+  })()`;
+    try {
+        const { result } = await session.Runtime.evaluate({ expression: expr, returnByValue: true });
+        return result?.value ?? { clear: true };
+    }
+    catch {
+        return { clear: true }; // non-fatal; proceed optimistically
+    }
+}

package/dist/sensors/guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Weavetab — sensors/guard.ts
+ * guardedAction pipeline: element readiness, DOM stability wait, and navigation await.
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+export interface PollOptions {
+    timeout: number;
+    interval: number;
+}
+export declare function pollUntil(predicate: () => Promise<boolean>, opts: PollOptions): Promise<void>;
+export declare function waitForDOMStable(session: CDP.Client, quietPeriod?: number, // Reduced from 100ms
+timeout?: number, // Reduced from 1500ms
+fast?: boolean): Promise<void>;
+export declare function guardedAction(session: CDP.Client, backendNodeId: number, action: () => Promise<void>, label?: string, postActionPipeline?: () => Promise<void>, fast?: boolean): Promise<void>;
+export interface PageWeight {
+    level: "light" | "medium" | "heavy";
+    elementCount: number;
+    imageCount: number;
+    scriptCount: number;
+    iframeCount: number;
+    suggestedTimeout: number;
+}
+export declare function detectPageWeight(session: CDP.Client): Promise<PageWeight>;
+export declare function awaitNavigation(session: CDP.Client, timeout?: number): Promise<void>;

package/dist/sensors/guard.js

@@ -0,0 +1,168 @@
+export async function pollUntil(predicate, opts) {
+    const deadline = Date.now() + opts.timeout;
+    while (Date.now() < deadline) {
+        if (await predicate())
+            return;
+        await sleep(opts.interval);
+    }
+    throw new Error(`pollUntil: timed out after ${opts.timeout}ms`);
+}
+// sleep is ONLY permitted inside the auto-wait pipeline — never in tool handlers
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// ─── DOM checks (all run inside CDP Runtime.callFunction for speed) ───────────
+import { waitForNetworkIdle } from "./wait.js";
+async function isElementReady(session, backendNodeId) {
+    try {
+        const { nodeIds } = await session.DOM.pushNodesByBackendIdsToFrontend({
+            backendNodeIds: [backendNodeId],
+        });
+        if (!nodeIds[0])
+            return false;
+        const { object } = await session.DOM.resolveNode({ nodeId: nodeIds[0] });
+        if (!object?.objectId)
+            return false;
+        const { result } = await session.Runtime.callFunctionOn({
+            objectId: object.objectId,
+            functionDeclaration: `function() {
+        if (this.disabled || this.getAttribute('aria-disabled') === 'true') return false;
+        const r = this.getBoundingClientRect();
+        const s = window.getComputedStyle(this);
+        if (r.width === 0 || r.height === 0 || s.visibility === 'hidden' || s.display === 'none' || s.opacity === '0') return false;
+        const topEl = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        return topEl !== null && (topEl === this || this.contains(topEl));
+      }`,
+            returnByValue: true,
+        });
+        return result?.value === true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── DOM stability (waits for no mutations for quietPeriod ms) ────────────────
+export async function waitForDOMStable(session, quietPeriod = 50, // Reduced from 100ms
+timeout = 800, // Reduced from 1500ms
+fast = false) {
+    // Fast path: skip stability check entirely when fast=true
+    if (fast)
+        return Promise.resolve();
+    const result = await session.Runtime.evaluate({
+        expression: `(function(quiet, timeout) {
+      return new Promise((resolve) => {
+        let timer;
+        const obs = new MutationObserver(() => {
+          clearTimeout(timer);
+          timer = setTimeout(() => { obs.disconnect(); resolve(true); }, quiet);
+        });
+        obs.observe(document.body, { childList: true, subtree: true, attributes: true });
+        timer = setTimeout(() => { obs.disconnect(); resolve(true); }, quiet);
+        setTimeout(() => { obs.disconnect(); resolve(true); }, timeout);
+      });
+    })(${quietPeriod}, ${timeout})`,
+        awaitPromise: true,
+        returnByValue: true,
+    }).catch(() => ({ result: { value: true } }));
+    return Promise.resolve();
+}
+// ─── guardedAction — the mandatory wrapper for every CDP interaction ──────────
+//
+// Rule 9: Every CDP interaction goes through this pipeline:
+// 1. DOM existence check
+// 2. Visibility check
+// 3. Interactability check
+// 4. DOM stability wait (150ms quiet period for SPA re-renders)
+// Then fires the action.
+//
+// Manual sleeps in tool handlers are BANNED. This is the only place they live.
+export async function guardedAction(session, backendNodeId, action, label = "unknown", postActionPipeline, fast = false) {
+    // Fast path: minimal checks when fast=true
+    if (fast) {
+        // Quick single check (no polling)
+        const ready = await isElementReady(session, backendNodeId);
+        if (!ready) {
+            throw new Error(`guardedAction: element "${label}" not ready (fast mode)`);
+        }
+        await action();
+        if (postActionPipeline)
+            await postActionPipeline();
+        return;
+    }
+    // 1. Single-pass check: existence, visibility, and interactability
+    await pollUntil(() => isElementReady(session, backendNodeId), {
+        timeout: 800, // Reduced from 1500ms
+        interval: 30, // Reduced from 50ms
+    }).catch(() => {
+        throw new Error(`guardedAction: element "${label}" not ready (missing, hidden, or blocked) after 0.8s`);
+    });
+    // 2. DOM stability pre-action
+    await waitForDOMStable(session, 50, 600); // Reduced from 100/1000
+    // 3. Fire
+    await action();
+    // 4. Post-action — DOM stability + network idle (parallel, shorter)
+    await Promise.all([
+        waitForDOMStable(session, 50, 800), // Reduced from 100/1500
+        waitForNetworkIdle(session, 200, 800).catch(() => { }), // Reduced from 300/1500
+        postActionPipeline ? postActionPipeline() : Promise.resolve(),
+    ]);
+}
+export async function detectPageWeight(session) {
+    try {
+        const { result } = await session.Runtime.evaluate({
+            expression: `(function() {
+        const all = document.querySelectorAll('*');
+        const images = document.querySelectorAll('img, picture, svg');
+        const scripts = document.querySelectorAll('script');
+        const iframes = document.querySelectorAll('iframe, frame');
+        return JSON.stringify({
+          elementCount: all.length,
+          imageCount: images.length,
+          scriptCount: scripts.length,
+          iframeCount: iframes.length
+        });
+      })()`,
+            returnByValue: true,
+        });
+        const data = JSON.parse(result.value);
+        const { elementCount, imageCount, scriptCount, iframeCount } = data;
+        // Weight scoring heuristic
+        let score = 0;
+        score += Math.min(elementCount / 500, 10); // 0-10: 0 to 5000+ elements
+        score += Math.min(imageCount / 10, 5); // 0-5:  0 to 50+ images
+        score += Math.min(scriptCount / 5, 3); // 0-3:  0 to 15+ scripts
+        score += Math.min(iframeCount, 2); // 0-2:  0+ iframes
+        const level = score < 5 ? "light" : score < 12 ? "medium" : "heavy";
+        const baseTimeout = 8000;
+        const suggestedTimeout = Math.min(Math.round(baseTimeout + score * 1500), 60000);
+        return { level, elementCount, imageCount, scriptCount, iframeCount, suggestedTimeout };
+    }
+    catch {
+        return {
+            level: "light",
+            elementCount: 0,
+            imageCount: 0,
+            scriptCount: 0,
+            iframeCount: 0,
+            suggestedTimeout: 10000,
+        };
+    }
+}
+// ─── Navigation wait — used after clicks that trigger navigation ──────────────
+export async function awaitNavigation(session, timeout = 6000 // Reduced from 10000ms
+) {
+    // Poll readyState instead of consuming one-shot event
+    await pollUntil(async () => {
+        const { result } = await session.Runtime.evaluate({
+            expression: `document.readyState`,
+            returnByValue: true,
+        }).catch(() => ({ result: { value: 'loading' } }));
+        return result?.value === 'complete' || result?.value === 'interactive';
+    }, { timeout, interval: 50 }).catch(() => {
+        throw new Error(`Navigation timeout after ${timeout}ms`);
+    });
+    // After DOM content fires, detect page weight for post-load stability wait
+    const weight = await detectPageWeight(session);
+    const stabilityTimeout = weight.level === "heavy" ? 3000 : weight.level === "medium" ? 2000 : 1000; // Reduced from 5000/3000/2000
+    await waitForDOMStable(session, 50, stabilityTimeout); // Reduced quiet period from 100ms
+}

package/dist/sensors/mutations.d.ts

@@ -0,0 +1,23 @@
+import CDP from "chrome-remote-interface";
+export type MutationSummary = {
+    newElements: {
+        backendNodeId: number;
+        tag: string;
+        text: string;
+        role?: string;
+    }[];
+    removedElements: {
+        backendNodeId: number;
+        tag: string;
+        text: string;
+    }[];
+    attributeChanges: {
+        backendNodeId: number;
+        element: string;
+        attribute: string;
+        oldValue: string | null;
+        newValue: string;
+    }[];
+    significantChange: boolean;
+};
+export declare function watchMutations(session: CDP.Client, durationMs: number): Promise<MutationSummary>;

package/dist/sensors/mutations.js

@@ -0,0 +1,93 @@
+// Heuristics for "significant" changes
+const SIGNIFICANT_TAGS = new Set(['button', 'a', 'input', 'textarea', 'select', 'h1', 'h2', 'h3', '[role="button"]', '[role="link"]']);
+const MAX_TEXT_LEN = 150;
+export async function watchMutations(session, durationMs) {
+    const { DOM } = session;
+    const summary = {
+        newElements: [],
+        removedElements: [],
+        attributeChanges: [],
+        significantChange: false,
+    };
+    let timeoutId = null;
+    let documentUpdated = false;
+    const onDocumentUpdated = () => {
+        documentUpdated = true;
+        summary.significantChange = true; // Full page load is always significant
+    };
+    const onAttributeModified = (params) => {
+        const { nodeId, name, value } = params;
+        // For simplicity, we can't get the old value here without more complex tracking.
+        // Let's just record the change.
+        summary.attributeChanges.push({
+            backendNodeId: nodeId,
+            element: `nodeId: ${nodeId}`,
+            attribute: name,
+            oldValue: "not_tracked", // The protocol doesn't provide the old value directly
+            newValue: value,
+        });
+        summary.significantChange = true; // Assume attribute changes can be significant
+    };
+    const onChildNodeInserted = async (params) => {
+        const { parentNodeId, previousNodeId, node } = params;
+        // We only care about element nodes
+        if (node.nodeType !== 1)
+            return; // 1 = Element Node
+        // nodeValue is always null for element nodes (nodeType === 1).
+        // For elements, approximate text from nodeValue of first text child.
+        // CDP Node type doesn't have textContent, so we fall back to nodeValue.
+        const textContent = node.nodeValue || '';
+        // CDP DOM attributes are a flattened string array: [name1, value1, name2, value2, ...]
+        // Find 'role' by iterating in pairs.
+        let role = '';
+        const attrs = node.attributes || [];
+        for (let ai = 0; ai < attrs.length - 1; ai += 2) {
+            if (attrs[ai] === 'role') {
+                role = attrs[ai + 1] || '';
+                break;
+            }
+        }
+        summary.newElements.push({
+            backendNodeId: node.backendNodeId,
+            tag: node.localName,
+            text: textContent.substring(0, MAX_TEXT_LEN),
+            role,
+        });
+        if (SIGNIFICANT_TAGS.has(node.localName) || (role && SIGNIFICANT_TAGS.has(`[role="${role}"]`))) {
+            summary.significantChange = true;
+        }
+    };
+    const onChildNodeRemoved = (params) => {
+        const { parentNodeId, nodeId } = params;
+        // We don't have info about the removed node other than its ID.
+        // A more complex implementation would cache node info.
+        summary.removedElements.push({
+            backendNodeId: nodeId,
+            tag: 'unknown',
+            text: 'unknown'
+        });
+    };
+    // --- Main Logic ---
+    const promise = new Promise(resolve => {
+        timeoutId = setTimeout(resolve, durationMs);
+    });
+    try {
+        // Enable DOM notifications
+        await DOM.enable();
+        const listeners = [
+            DOM.on("documentUpdated", onDocumentUpdated),
+            DOM.on("attributeModified", onAttributeModified),
+            DOM.on("childNodeInserted", onChildNodeInserted),
+            DOM.on("childNodeRemoved", onChildNodeRemoved)
+        ];
+        await DOM.getDocument({ depth: -1, pierce: true });
+        await promise;
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        // Disabling the DOM agent automatically removes all listeners.
+        await DOM.disable();
+    }
+    return summary;
+}

package/dist/sensors/network.d.ts

@@ -0,0 +1,67 @@
+import CDP from "chrome-remote-interface";
+export type NetworkSecurityDetails = {
+    protocol?: string;
+    issuer?: string;
+    subjectName?: string;
+    validFrom?: number;
+    validTo?: number;
+    cipher?: string;
+    keyExchange?: string;
+    sanList?: string[];
+    certificateId?: number;
+};
+export type NetworkTimingBreakdown = {
+    dnsMs?: number;
+    connectMs?: number;
+    sslMs?: number;
+    sendMs?: number;
+    waitMs?: number;
+    downloadMs?: number;
+    totalMs?: number;
+};
+export type NetworkFailureDetails = {
+    errorText: string;
+    canceled?: boolean;
+    blockedReason?: string;
+};
+export type CapturedRequest = {
+    url: string;
+    method: string;
+    status?: number;
+    isApi: boolean;
+    timestamp?: number;
+    securityDetails?: NetworkSecurityDetails;
+    timing?: NetworkTimingBreakdown;
+    failure?: NetworkFailureDetails;
+    _startTimeMonotonic?: number;
+    _responseHeadersMonotonic?: number;
+};
+export type TelemetryReport = {
+    networkRequests: CapturedRequest[];
+    domMutations: string[];
+    navigationOccurred: boolean;
+    newUrl?: string;
+    toastMessages: string[];
+    pageTitle?: string;
+    errors: string[];
+};
+export declare class TelemetryCapture {
+    private session;
+    private requests;
+    private toastMessages;
+    private errors;
+    private navigationOccurred;
+    private newUrl?;
+    private active;
+    private _onRequestWillBeSent;
+    private _onResponseReceived;
+    private _onLoadingFinished;
+    private _onLoadingFailed;
+    private _onFrameNavigated;
+    private _onChildNodeInserted;
+    private _onConsoleAPICalled;
+    constructor(session: CDP.Client);
+    private setupListeners;
+    start(): Promise<void>;
+    stop(): Promise<TelemetryReport>;
+}