@bubstack/moe-glass 0.1.0

package/skills/browsing/lib/evaluation.js

@@ -0,0 +1,85 @@
+/**
+ * Runtime.evaluate wrappers — three flavors, for three return-value
+ * shapes. The differences matter (see JRV-126):
+ *
+ * - `evaluate`: legacy `returnByValue: true`. Returns `result.result.value`.
+ *   Loses type information for complex objects (DOM nodes come back as
+ *   `[object Object]`-style descriptions). Awaits Promises.
+ *
+ * - `evaluateJson`: wraps the expression so the page-side code stringifies
+ *   complex returns into a tagged shape (`{__type: 'Element', ...}`,
+ *   `{__type: 'undefined'}`, etc.). Use when you want to inspect DOM
+ *   nodes or distinguish undefined/null/error in the result.
+ *
+ * - `evaluateRaw`: `returnByValue: false`. Returns `result.result` (the
+ *   full RemoteObject including `objectId`). For callers that need the
+ *   raw CDP shape.
+ *
+ * `attachEvaluation({ getPageSession })` binds them to a session via the
+ * pageSession resolver.
+ */
+const { throwIfExceptionDetails } = require('./cdp-utils');
+
+function attachEvaluation({ getPageSession }) {
+  async function evaluate(tabIndexOrWsUrl, expression) {
+    const pageSession = await getPageSession(tabIndexOrWsUrl);
+    const result = await pageSession.send('Runtime.evaluate', {
+      expression,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    throwIfExceptionDetails(result);
+    return result.result.value;
+  }
+
+  async function evaluateJson(tabIndexOrWsUrl, expression) {
+    const pageSession = await getPageSession(tabIndexOrWsUrl);
+
+    const wrappedExpression = `
+      (() => {
+        try {
+          const result = ${expression};
+          if (result === undefined) return { __type: 'undefined' };
+          if (result === null) return null;
+          if (result instanceof Element) {
+            return {
+              __type: 'Element',
+              tagName: result.tagName,
+              id: result.id,
+              className: result.className,
+              textContent: result.textContent?.slice(0, 100)
+            };
+          }
+          if (typeof result === 'function') {
+            return { __type: 'function', name: result.name || 'anonymous' };
+          }
+          return result;
+        } catch (e) {
+          return { __type: 'error', message: e.message };
+        }
+      })()
+    `;
+
+    const result = await pageSession.send('Runtime.evaluate', {
+      expression: wrappedExpression,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    throwIfExceptionDetails(result);
+    return result.result.value;
+  }
+
+  async function evaluateRaw(tabIndexOrWsUrl, expression) {
+    const pageSession = await getPageSession(tabIndexOrWsUrl);
+    const result = await pageSession.send('Runtime.evaluate', {
+      expression,
+      returnByValue: false
+    });
+    throwIfExceptionDetails(result);
+    return result.result;
+  }
+
+  return { evaluate, evaluateJson, evaluateRaw };
+}
+
+module.exports = { attachEvaluation };

package/skills/browsing/lib/extraction.js

@@ -0,0 +1,55 @@
+const { getElementSelector } = require('./element-selector');
+const { throwIfExceptionDetails } = require('./cdp-utils');
+
+/**
+ * Single-element extraction primitives — text content, HTML, attributes.
+ *
+ * Each is a thin wrapper around `Runtime.evaluate` that uses optional
+ * chaining to return `null`/`undefined` when the selector misses, so the
+ * caller doesn't have to distinguish "element not found" from "element
+ * found but empty." The page-content / DOM-summary / markdown extractors
+ * (the heavyweight ones used by auto-capture) live in `lib/capture.js`.
+ *
+ * `attachExtraction({ getPageSession })` returns the bound methods — no
+ * session state needed.
+ */
+function attachExtraction({ getPageSession }) {
+  async function extractText(tabIndexOrWsUrl, selector) {
+    const ps = await getPageSession(tabIndexOrWsUrl);
+    const js = `${getElementSelector(selector)}?.textContent`;
+    const result = await ps.send('Runtime.evaluate', {
+      expression: js,
+      returnByValue: true
+    });
+    throwIfExceptionDetails(result);
+    return result.result.value;
+  }
+
+  async function getHtml(tabIndexOrWsUrl, selector = null) {
+    const ps = await getPageSession(tabIndexOrWsUrl);
+    const js = selector
+      ? `${getElementSelector(selector)}?.innerHTML`
+      : 'document.documentElement.outerHTML';
+    const result = await ps.send('Runtime.evaluate', {
+      expression: js,
+      returnByValue: true
+    });
+    throwIfExceptionDetails(result);
+    return result.result.value;
+  }
+
+  async function getAttribute(tabIndexOrWsUrl, selector, attrName) {
+    const ps = await getPageSession(tabIndexOrWsUrl);
+    const js = `${getElementSelector(selector)}?.getAttribute(${JSON.stringify(attrName)})`;
+    const result = await ps.send('Runtime.evaluate', {
+      expression: js,
+      returnByValue: true
+    });
+    throwIfExceptionDetails(result);
+    return result.result.value;
+  }
+
+  return { extractText, getHtml, getAttribute };
+}
+
+module.exports = { attachExtraction };

package/skills/browsing/lib/file-upload.js

@@ -0,0 +1,56 @@
+/**
+ * Programmatic file upload via `DOM.setFileInputFiles` — the only way to
+ * set files on an `<input type="file">` from outside the page, since JS
+ * security restrictions block synthetic file assignment.
+ *
+ * Resolves the input element via `DOM.querySelector` for CSS selectors
+ * or `DOM.performSearch` + `DOM.getSearchResults` for XPath, then attaches
+ * the absolute file paths to the input.
+ *
+ * `attachFileUpload({ getPageSession })` returns the bound action.
+ */
+function attachFileUpload({ getPageSession }) {
+  async function fileUpload(tabIndexOrWsUrl, selector, filePaths) {
+    const pageSession = await getPageSession(tabIndexOrWsUrl);
+
+    const docResult = await pageSession.send('DOM.getDocument', {});
+    const rootNodeId = docResult.root.nodeId;
+
+    let nodeId;
+    if (selector.startsWith('/') || selector.startsWith('//')) {
+      const searchResult = await pageSession.send('DOM.performSearch', {
+        query: selector
+      });
+      if (searchResult.resultCount === 0) {
+        throw new Error(`File input not found: ${selector}`);
+      }
+      const nodesResult = await pageSession.send('DOM.getSearchResults', {
+        searchId: searchResult.searchId,
+        fromIndex: 0,
+        toIndex: 1
+      });
+      nodeId = nodesResult.nodeIds[0];
+    } else {
+      const queryResult = await pageSession.send('DOM.querySelector', {
+        nodeId: rootNodeId,
+        selector: selector
+      });
+      nodeId = queryResult.nodeId;
+    }
+
+    if (!nodeId) {
+      throw new Error(`File input not found: ${selector}`);
+    }
+
+    await pageSession.send('DOM.setFileInputFiles', {
+      files: filePaths,
+      nodeId: nodeId
+    });
+
+    return { uploaded: true, files: filePaths.length };
+  }
+
+  return { fileUpload };
+}
+
+module.exports = { attachFileUpload };

package/skills/browsing/lib/html-diff.js

@@ -0,0 +1,122 @@
+/**
+ * Line-based diff between two HTML strings using Myers' algorithm.
+ * Returns a human-readable summary with REMOVED and ADDED sections,
+ * capped at 50 lines per side with "and N more" footer. Used by
+ * capturePageArtifacts to attach a diff to the captured page state.
+ *
+ * Myers (not set-based) so reordered identical lines are correctly
+ * detected as a remove + add pair, not "no changes."
+ *
+ * Pure function. Hand-rolled — no npm dependency.
+ */
+
+const MAX_LINES_PER_SIDE = 50;
+const MAX_LINE_LENGTH = 200;
+
+// Myers' O((N+M)D) shortest-edit-script. Returns an array of
+// { type: 'eq'|'del'|'add', value: string } operations in order.
+function myersDiff(a, b) {
+  const N = a.length;
+  const M = b.length;
+  const max = N + M;
+  const v = new Array(2 * max + 1);
+  const trace = [];
+
+  v[max + 1] = 0;
+  for (let d = 0; d <= max; d++) {
+    trace.push(v.slice());
+    for (let k = -d; k <= d; k += 2) {
+      let x;
+      if (k === -d || (k !== d && v[max + k - 1] < v[max + k + 1])) {
+        x = v[max + k + 1];
+      } else {
+        x = v[max + k - 1] + 1;
+      }
+      let y = x - k;
+      while (x < N && y < M && a[x] === b[y]) {
+        x++; y++;
+      }
+      v[max + k] = x;
+      if (x >= N && y >= M) {
+        // Backtrack through the trace to build the edit script.
+        return backtrack(trace, a, b, N, M, max);
+      }
+    }
+  }
+  return [];
+}
+
+function backtrack(trace, a, b, N, M, max) {
+  const ops = [];
+  let x = N;
+  let y = M;
+  for (let d = trace.length - 1; d > 0; d--) {
+    const v = trace[d];
+    const k = x - y;
+    let prevK;
+    if (k === -d || (k !== d && v[max + k - 1] < v[max + k + 1])) {
+      prevK = k + 1;
+    } else {
+      prevK = k - 1;
+    }
+    const prevX = v[max + prevK];
+    const prevY = prevX - prevK;
+    while (x > prevX && y > prevY) {
+      ops.push({ type: 'eq', value: a[x - 1] });
+      x--; y--;
+    }
+    if (d > 0) {
+      if (x === prevX) {
+        ops.push({ type: 'add', value: b[y - 1] });
+        y--;
+      } else {
+        ops.push({ type: 'del', value: a[x - 1] });
+        x--;
+      }
+    }
+  }
+  while (x > 0 && y > 0) {
+    ops.push({ type: 'eq', value: a[x - 1] });
+    x--; y--;
+  }
+  return ops.reverse();
+}
+
+function generateHtmlDiff(beforeHtml, afterHtml) {
+  const beforeLines = (beforeHtml || '').split('\n');
+  const afterLines = (afterHtml || '').split('\n');
+
+  const ops = myersDiff(beforeLines, afterLines);
+
+  const removed = ops.filter(o => o.type === 'del' && o.value.trim()).map(o => o.value);
+  const added = ops.filter(o => o.type === 'add' && o.value.trim()).map(o => o.value);
+
+  let diff = '';
+  if (removed.length > 0) {
+    diff += '=== REMOVED ===\n';
+    diff += removed.slice(0, MAX_LINES_PER_SIDE)
+      .map(l => '- ' + l.slice(0, MAX_LINE_LENGTH))
+      .join('\n');
+    if (removed.length > MAX_LINES_PER_SIDE) {
+      diff += `\n... and ${removed.length - MAX_LINES_PER_SIDE} more removed lines`;
+    }
+    diff += '\n\n';
+  }
+  if (added.length > 0) {
+    diff += '=== ADDED ===\n';
+    diff += added.slice(0, MAX_LINES_PER_SIDE)
+      .map(l => '+ ' + l.slice(0, MAX_LINE_LENGTH))
+      .join('\n');
+    if (added.length > MAX_LINES_PER_SIDE) {
+      diff += `\n... and ${added.length - MAX_LINES_PER_SIDE} more added lines`;
+    }
+  }
+
+  if (!diff) {
+    diff = '(no changes detected)';
+  }
+
+  return diff;
+}
+
+module.exports = { generateHtmlDiff };

package/skills/browsing/lib/key-definitions.js

@@ -0,0 +1,149 @@
+/**
+ * CDP key definitions for keyboard.press support (JRV-127).
+ *
+ * Maps human-readable key names to the CDP `Input.dispatchKeyEvent` payload
+ * fields. Keys with a `text` property trigger native browser behaviors
+ * (form submit on Enter, focus advance on Tab) — keys without `text` are
+ * dispatched as `rawKeyDown`/`keyUp` only.
+ */
+
+const KEY_DEFINITIONS = {
+  // Navigation keys - text property needed for Enter/Tab to trigger native behaviors
+  'Tab': { key: 'Tab', code: 'Tab', keyCode: 9, text: '\t' },
+  'Enter': { key: 'Enter', code: 'Enter', keyCode: 13, text: '\r' },
+  'Escape': { key: 'Escape', code: 'Escape', keyCode: 27 },
+  'Backspace': { key: 'Backspace', code: 'Backspace', keyCode: 8 },
+  'Delete': { key: 'Delete', code: 'Delete', keyCode: 46 },
+  'Space': { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
+
+  // Arrow keys
+  'ArrowUp': { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+  'ArrowDown': { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+  'ArrowLeft': { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+  'ArrowRight': { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+
+  // Modifier keys
+  'Shift': { key: 'Shift', code: 'ShiftLeft', keyCode: 16 },
+  'Control': { key: 'Control', code: 'ControlLeft', keyCode: 17 },
+  'Alt': { key: 'Alt', code: 'AltLeft', keyCode: 18 },
+  'Meta': { key: 'Meta', code: 'MetaLeft', keyCode: 91 },
+
+  // Function keys
+  'F1': { key: 'F1', code: 'F1', keyCode: 112 },
+  'F2': { key: 'F2', code: 'F2', keyCode: 113 },
+  'F3': { key: 'F3', code: 'F3', keyCode: 114 },
+  'F4': { key: 'F4', code: 'F4', keyCode: 115 },
+  'F5': { key: 'F5', code: 'F5', keyCode: 116 },
+  'F6': { key: 'F6', code: 'F6', keyCode: 117 },
+  'F7': { key: 'F7', code: 'F7', keyCode: 118 },
+  'F8': { key: 'F8', code: 'F8', keyCode: 119 },
+  'F9': { key: 'F9', code: 'F9', keyCode: 120 },
+  'F10': { key: 'F10', code: 'F10', keyCode: 121 },
+  'F11': { key: 'F11', code: 'F11', keyCode: 122 },
+  'F12': { key: 'F12', code: 'F12', keyCode: 123 },
+
+  // Other
+  'Home': { key: 'Home', code: 'Home', keyCode: 36 },
+  'End': { key: 'End', code: 'End', keyCode: 35 },
+  'PageUp': { key: 'PageUp', code: 'PageUp', keyCode: 33 },
+  'PageDown': { key: 'PageDown', code: 'PageDown', keyCode: 34 },
+  'Insert': { key: 'Insert', code: 'Insert', keyCode: 45 },
+};
+
+// Map shifted symbols to their unshifted base character — used by charToKeyDef
+// to figure out the underlying physical key and that Shift must be held.
+const SHIFT_SYMBOLS = {
+  '!': '1', '@': '2', '#': '3', '$': '4', '%': '5',
+  '^': '6', '&': '7', '*': '8', '(': '9', ')': '0',
+  '_': '-', '+': '=', '{': '[', '}': ']', '|': '\\',
+  ':': ';', '"': "'", '<': ',', '>': '.', '?': '/',
+  '~': '`',
+};
+
+// Punctuation key codes — physical key names for non-letter, non-digit keys.
+const PUNCT_CODES = {
+  '-': 'Minus', '=': 'Equal', '[': 'BracketLeft', ']': 'BracketRight',
+  '\\': 'Backslash', ';': 'Semicolon', "'": 'Quote',
+  ',': 'Comma', '.': 'Period', '/': 'Slash', '`': 'Backquote',
+};
+
+/**
+ * Map a single character to its CDP key-event payload (key/code/keyCode/text/shift).
+ * Pure function — no Chrome session dependency. Returns `{ special: 'Enter'|'Tab' }`
+ * for characters that should be dispatched via the named-key path instead.
+ */
+function charToKeyDef(char) {
+  if (char === '\n') return { special: 'Enter' };
+  if (char === '\t') return { special: 'Tab' };
+
+  if (char === ' ') {
+    return { key: ' ', code: 'Space', keyCode: 32, text: ' ', shift: false };
+  }
+
+  if (char >= 'A' && char <= 'Z') {
+    return {
+      key: char,
+      code: 'Key' + char,
+      keyCode: char.charCodeAt(0),
+      text: char,
+      shift: true
+    };
+  }
+
+  if (char >= 'a' && char <= 'z') {
+    return {
+      key: char,
+      code: 'Key' + char.toUpperCase(),
+      keyCode: char.toUpperCase().charCodeAt(0),
+      text: char,
+      shift: false
+    };
+  }
+
+  if (char >= '0' && char <= '9') {
+    return {
+      key: char,
+      code: 'Digit' + char,
+      keyCode: char.charCodeAt(0),
+      text: char,
+      shift: false
+    };
+  }
+
+  if (SHIFT_SYMBOLS[char]) {
+    const baseChar = SHIFT_SYMBOLS[char];
+    let code;
+    if (baseChar >= '0' && baseChar <= '9') {
+      code = 'Digit' + baseChar;
+    } else {
+      code = PUNCT_CODES[baseChar] || 'Unidentified';
+    }
+    return {
+      key: char,
+      code,
+      keyCode: baseChar.charCodeAt(0),
+      text: char,
+      shift: true
+    };
+  }
+
+  if (PUNCT_CODES[char]) {
+    return {
+      key: char,
+      code: PUNCT_CODES[char],
+      keyCode: char.charCodeAt(0),
+      text: char,
+      shift: false
+    };
+  }
+
+  return {
+    key: char,
+    code: 'Unidentified',
+    keyCode: char.charCodeAt(0),
+    text: char,
+    shift: false
+  };
+}
+
+module.exports = { KEY_DEFINITIONS, SHIFT_SYMBOLS, charToKeyDef };