agex 0.2.7 → 0.2.10

package/README.md

@@ -0,0 +1,206 @@
+# agex
+
+**Let AI agents prove their work — with video.**
+
+AI agents work in the background. They write code, fix bugs, ship features. But how do they prove their work?
+
+No screenshots. No recordings. No proof. You just have to trust the logs — or worse, manually test it yourself. A bottleneck.
+
+agex lets any AI agent (Cursor, Claude, Codex) open a browser, take screenshots, record video, and deliver visual evidence that the work is done. Run it locally. Run it in CI. Ship with proof.
+
+Built on [agent-browser](https://github.com/vercel-labs/agent-browser) by Vercel.
+
+## Quick Start
+
+```bash
+npx agex prove "the homepage has a search bar and a sign up button" --url https://github.com
+```
+
+On your PR CI
+```
+npx agex prove-pr --url http://localhost:3000 # your local dev URL, start your app in the CI
+```
+
+## Install
+
+
+```bash
+npm install -g agex
+```
+
+## Commands
+
+### `agex prove` - Visual assertion testing
+
+Prove visual assertions on any URL with screenshots and video evidence.
+
+```bash
+# Is there a dog in Google's logo? (spoiler: no — and the agent catches it)
+agex prove "google home page has a dog in the logo" \
+  --url "https://www.google.com/?hl=en&gl=us" --agent codex
+
+# Verify GitHub's Code dropdown has HTTPS/SSH/GitHub CLI tabs
+agex prove "clicking the Code dropdown opens a panel with HTTPS/SSH/GitHub CLI tabs" \
+  --url https://github.com/facebook/react
+
+# Multi-element verification
+agex prove "github.com homepage has a search bar, a sign up button, and at least 3 navigation links" \
+  --url https://github.com --agent claude
+
+# Complex page structure
+agex prove "the wikipedia page for JavaScript has a History section, a Syntax section, and an infobox sidebar" \
+  --url https://en.wikipedia.org/wiki/JavaScript --agent claude
+
+# E-commerce flow
+agex prove "search for 'mechanical keyboard', filter by 4+ stars, verify the first result shows product image, price, and rating" \
+  --url https://amazon.com --agent claude
+
+# Video content
+agex prove "youtube homepage shows at least 6 video thumbnails with titles and view counts" \
+  --url https://www.youtube.com --agent codex
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--agent, -a` | Agent to use: `cursor`, `claude`, `codex` | `cursor` |
+| `--url, -u` | URL to navigate to | - |
+| `--output, -o` | Output directory | `./prove-results` |
+| `--video` | Enable video recording | `true` |
+| `--screenshots` | Enable screenshots | `true` |
+| `--model, -m` | Model to use | - |
+| `--timeout, -t` | Timeout in ms | `300000` |
+| `--viewport` | Viewport size (WxH) | `1920x1080` |
+| `--headless` | Run headless | `true` |
+| `--browser, -b` | Browser mode: `mcp` or `cli` | `mcp` |
+
+---
+
+### `agex demo` - Record demo videos
+
+Record a narrated browser walkthrough as a video. The agent opens a URL, performs the task, and captures the session.
+
+```bash
+# Record a demo of selecting a brand design from a menu
+agex demo "how to select a brand design from the menu" --url https://example.com
+
+# With subtitles and custom colors (via task text)
+agex demo "how to create a new project. use subtitles with white text on red background" \
+  --url https://app.example.com --agent cursor
+
+# Non-headless for debugging
+agex demo "sign up for a free trial" --url https://example.com --no-headless
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--agent, -a` | Agent to use: `cursor`, `claude`, `codex` | auto-detected |
+| `--url, -u` | URL to navigate to | - |
+| `--output, -o` | Output directory | `./demo-results` |
+| `--video` | Enable video recording | `true` |
+| `--screenshots` | Enable screenshots | `true` |
+| `--model, -m` | Model to use | - |
+| `--timeout, -t` | Timeout in ms | `300000` |
+| `--viewport` | Viewport size (WxH) | `1920x1080` |
+| `--headless` | Run headless | `true` |
+
+---
+
+### `agex prove-pr` - PR verification in CI
+
+Run it in your CI. It reads the diff, thinks, acts, and reports autonomously.
+
+```bash
+agex prove-pr --base main --url http://localhost:3000
+agex prove-pr --base HEAD~3 --agent claude --hypotheses 10 --hint "focus on mobile layout"
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--base` | Base branch/commit to compare against | auto-detected |
+| `--agent, -a` | Agent to use: `cursor`, `claude`, `codex` | `cursor` |
+| `--url, -u` | Dev server URL for visual testing | - |
+| `--output, -o` | Output directory | `./prove-pr-results` |
+| `--hypotheses` | Number of hypotheses to generate | `5` |
+| `--model, -m` | Model to use | - |
+| `--viewport` | Viewport size (WxH) | `1920x1080` |
+| `--hint` | Additional prompt hint for hypothesis generation | - |
+| `--timeout, -t` | Timeout in ms | `300000` |
+
+---
+
+### `agex review` - AI code review
+
+Review code changes using an AI agent.
+
+```bash
+agex review --base main --agent cursor
+agex review --base HEAD~3 --agent claude --hint "focus on security"
+agex review --agent codex --hypotheses 3 --no-worktree
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--base` | Base branch/commit to compare against | auto-detected |
+| `--agent, -a` | Agent to use: `cursor`, `claude`, `codex` | required |
+| `--model, -m` | Model to use | - |
+| `--worktree` | Include worktree changes | `true` |
+| `--hypotheses` | Number of hypotheses to generate | - |
+| `--hint` | Additional prompt hint | - |
+| `--timeout, -t` | Timeout in ms | `300000` |
+
+---
+
+### `agex run` - Execute AI agent tasks
+
+Run a prompt through any supported AI agent.
+
+```bash
+agex run "build a landing page" --agent cursor
+agex run "refactor this function" --agent claude --mode json
+agex run "fix the bug" --approval on-request --timeout 600000
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--agent, -a` | Agent to use: `cursor`, `claude`, `codex` | auto-detected |
+| `--model, -m` | Model to use | - |
+| `--mode` | Output mode: `text`, `json`, `debug` | `text` |
+| `--approval` | Approval policy: `never`, `on-request`, `on-failure`, `untrusted` | - |
+| `--timeout` | Timeout in ms | `300000` |
+| `--install` | Run install command before agent | `false` |
+| `--install-command` | Custom install command | - |
+| `--stream` | Enable streaming output | `true` |
+| `--browser` | Enable browser | `true` |
+
+---
+
+### `agex browse` - Browser automation
+
+Low-level browser automation via agent-browser.
+
+```bash
+agex browse open https://example.com
+agex browse snapshot -i
+agex browse click @e1
+agex browse fill @e2 "hello@example.com"
+agex browse screenshot page.png
+agex browse close
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--install` | Force reinstall browser | `false` |
+
+---
+
+## Supported Agents
+
+| Agent | Description |
+|-------|-------------|
+| `cursor` | Cursor IDE agent |
+| `claude` | Anthropic Claude CLI |
+| `codex` | OpenAI Codex CLI |
+
+## Ship with proof.
+
+MIT License

package/assets/assets/cursor.js

@@ -3,6 +3,19 @@
   let clickRippleEnabled = true;
   let trailEnabled = false;
   let trailPoints = [];
+  let currentMode = 'default'; // 'default' or 'pointer'
+  let animationLock = false; // when true, mousemove won't update demo cursor position
+
+  const ARROW_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" fill="none">
+  <path d="M8.5 3L8.5 24.2l5-5.6 3.6 7.7 3.5-1.5-3.7-7.6 7.1-.5L8.5 3z" fill="#000" stroke="#fff" stroke-width="1.8" stroke-linejoin="round"></path>
+</svg>`;
+
+  const POINTER_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" fill="none">
+  <g transform="rotate(-20, 16, 16)">
+    <path d="M14 2 C14 2 11.5 2 11.5 4.5 L11.5 15 L10 13.5 C10 13.5 8.5 12 7 12.5 C5.5 13 5.8 14.5 6.5 15.8 L10.5 22.5 C12 25.5 14.5 27.5 18 27.5 L19.5 27.5 C23.5 27.5 26.5 24 26.5 20 L26.5 15.5 C26.5 14 25 13 23.5 13.5 C23 13.7 22.5 14.2 22.5 15 L22.5 14 C22.5 12.5 21 11.5 19.5 12 C19 12.2 18.5 12.7 18.5 13.5 L18.5 12.5 C18.5 11 17 10 15.5 10.5 C15 10.7 14.5 11.3 14.5 12 L14.5 4.5 C14.5 4.5 14.5 2 14 2 Z" fill="#000" stroke="#fff" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round"/>
+    <line x1="18.5" y1="13" x2="18.5" y2="17" stroke="#fff" stroke-width="0.6" opacity="0.3"/><line x1="22.5" y1="14.5" x2="22.5" y2="17" stroke="#fff" stroke-width="0.6" opacity="0.3"/>
+  </g>
+</svg>`;
 
   function createCursor() {
     if (document.getElementById('agex-cursor')) return;
@@ -10,21 +23,36 @@
     const cursor = document.createElement('div');
     cursor.id = 'agex-cursor';
     cursor.style.cssText = `
-      width: 24px;
-      height: 24px;
-      background: rgba(255, 50, 50, 0.85);
-      border: 2px solid white;
-      border-radius: 50%;
       position: fixed;
       pointer-events: none;
       z-index: 2147483647;
-      transform: translate(-50%, -50%);
-      box-shadow: 0 0 8px rgba(0, 0, 0, 0.3);
       left: -100px;
       top: -100px;
       opacity: 0;
-      transition: left 0.08s ease-out, top 0.08s ease-out, opacity 0.15s, transform 0.1s, background 0.1s;
+      transition: opacity 0.15s, transform 0.1s ease-out;
+      transform-origin: 2px 2px;
+      will-change: left, top;
+    `;
+
+    const dot = document.createElement('div');
+    dot.className = 'agex-cursor-dot';
+    dot.style.cssText = `
+      position: absolute;
+      width: 38px;
+      height: 38px;
+      border-radius: 50%;
+      background: rgb(251, 255, 0, 0.45);
+      top: -16px;
+      left: -10px;
+      pointer-events: none;
     `;
+
+    const svg = document.createElement('div');
+    svg.className = 'agex-cursor-svg';
+    svg.innerHTML = ARROW_SVG;
+
+    cursor.appendChild(dot);
+    cursor.appendChild(svg);
     document.body.appendChild(cursor);
 
     const style = document.createElement('style');
@@ -33,20 +61,28 @@
       .agex-cursor-ripple {
         position: fixed;
         border-radius: 50%;
-        background: rgba(255, 50, 50, 0.4);
         pointer-events: none;
         z-index: 2147483646;
         transform: translate(-50%, -50%) scale(0);
-        animation: agex-ripple 0.4s ease-out forwards;
+        animation: agex-ripple 0.5s ease-out forwards;
+      }
+      .agex-cursor-ripple-ring {
+        position: fixed;
+        border-radius: 50%;
+        border: 3px solid rgba(0, 0, 0, 0.4);
+        pointer-events: none;
+        z-index: 2147483646;
+        transform: translate(-50%, -50%) scale(0);
+        animation: agex-ripple 0.6s ease-out forwards;
       }
       @keyframes agex-ripple {
         to { transform: translate(-50%, -50%) scale(1); opacity: 0; }
       }
       .agex-cursor-trail {
         position: fixed;
-        width: 8px;
-        height: 8px;
-        background: rgba(255, 50, 50, 0.3);
+        width: 6px;
+        height: 6px;
+        background: rgba(0, 0, 0, 0.12);
         border-radius: 50%;
         pointer-events: none;
         z-index: 2147483645;
@@ -55,16 +91,29 @@
     `;
     document.head.appendChild(style);
 
+    const CLICKABLE = 'a, button, [role="button"], input[type="submit"], input[type="button"], select, label[for], [onclick], [data-action], summary, [tabindex]';
+
     document.addEventListener('mousemove', (e) => {
       const c = document.getElementById('agex-cursor');
       if (c) {
-        c.style.left = `${e.clientX}px`;
-        c.style.top = `${e.clientY}px`;
-        if (!hasMoved) {
-          hasMoved = true;
-          c.style.opacity = '1';
+        if (!animationLock) {
+          c.style.left = `${e.clientX}px`;
+          c.style.top = `${e.clientY}px`;
+          if (!hasMoved) {
+            hasMoved = true;
+            c.style.opacity = '1';
+          }
+        }
+
+        const hovered = document.elementFromPoint(e.clientX, e.clientY);
+        const isClickable = hovered && hovered.closest(CLICKABLE);
+        const newMode = isClickable ? 'pointer' : 'default';
+        if (newMode !== currentMode) {
+          currentMode = newMode;
+          const svgEl = c.querySelector('.agex-cursor-svg');
+          if (svgEl) svgEl.innerHTML = currentMode === 'pointer' ? POINTER_SVG : ARROW_SVG;
         }
-        
+
         if (trailEnabled) {
           createTrailPoint(e.clientX, e.clientY);
         }
@@ -74,9 +123,8 @@
     document.addEventListener('mousedown', (e) => {
       const c = document.getElementById('agex-cursor');
       if (c) {
-        c.style.transform = 'translate(-50%, -50%) scale(0.8)';
-        c.style.background = 'rgba(255, 200, 50, 1)';
-        
+        c.style.transform = 'scale(0.85)';
+
         if (clickRippleEnabled) {
           createClickRipple(e.clientX, e.clientY);
         }
@@ -86,21 +134,30 @@
     document.addEventListener('mouseup', () => {
       const c = document.getElementById('agex-cursor');
       if (c) {
-        c.style.transform = 'translate(-50%, -50%) scale(1)';
-        c.style.background = 'rgba(255, 50, 50, 0.85)';
+        c.style.transform = 'scale(1)';
       }
     }, true);
   }
 
   function createClickRipple(x, y) {
-    const ripple = document.createElement('div');
-    ripple.className = 'agex-cursor-ripple';
-    ripple.style.left = `${x}px`;
-    ripple.style.top = `${y}px`;
-    ripple.style.width = '60px';
-    ripple.style.height = '60px';
-    document.body.appendChild(ripple);
-    setTimeout(() => ripple.remove(), 400);
+    const fill = document.createElement('div');
+    fill.className = 'agex-cursor-ripple';
+    fill.style.left = `${x}px`;
+    fill.style.top = `${y}px`;
+    fill.style.width = '50px';
+    fill.style.height = '50px';
+    fill.style.background = 'rgba(251, 255, 0, 0.35)';
+    document.body.appendChild(fill);
+    setTimeout(() => fill.remove(), 500);
+
+    const ring = document.createElement('div');
+    ring.className = 'agex-cursor-ripple-ring';
+    ring.style.left = `${x}px`;
+    ring.style.top = `${y}px`;
+    ring.style.width = '70px';
+    ring.style.height = '70px';
+    document.body.appendChild(ring);
+    setTimeout(() => ring.remove(), 600);
   }
 
   function createTrailPoint(x, y) {
@@ -122,15 +179,16 @@
     }, 400);
   }
 
-  // Expose cursor configuration API
   window.__agexCursor = {
+    setAnimationLock(locked) {
+      animationLock = locked;
+    },
     setSize(size) {
       const cursor = document.getElementById('agex-cursor');
       if (!cursor) return;
-      const sizes = { normal: 16, large: 24, 'extra-large': 32 };
-      const s = sizes[size] || sizes.large;
-      cursor.style.width = `${s}px`;
-      cursor.style.height = `${s}px`;
+      const scales = { normal: 0.75, large: 1, 'extra-large': 1.3 };
+      const s = scales[size] || scales.large;
+      cursor.style.transform = `scale(${s})`;
     },
     setClickRipple(enabled) {
       clickRippleEnabled = enabled;
@@ -143,6 +201,26 @@
       if (options.clickRipple !== undefined) this.setClickRipple(options.clickRipple);
       if (options.trail !== undefined) this.setTrail(options.trail);
     },
+    setMode(mode) {
+      const cursor = document.getElementById('agex-cursor');
+      if (!cursor) return;
+      const svgEl = cursor.querySelector('.agex-cursor-svg');
+      if (!svgEl) return;
+      if (mode === 'pointer') {
+        currentMode = 'pointer';
+        svgEl.innerHTML = POINTER_SVG;
+      } else {
+        currentMode = 'default';
+        svgEl.innerHTML = ARROW_SVG;
+      }
+    },
+    showClickRipple() {
+      const cursor = document.getElementById('agex-cursor');
+      if (!cursor) return;
+      const x = parseFloat(cursor.style.left) || 0;
+      const y = parseFloat(cursor.style.top) || 0;
+      createClickRipple(x, y);
+    },
     sync() {
       const cursor = document.getElementById('agex-cursor');
       if (!cursor) return Promise.resolve('no cursor');

package/assets/assets/effects.js

@@ -95,6 +95,18 @@
         0%, 100% { box-shadow: 0 0 20px var(--color, #ff4444), inset 0 0 20px var(--color, #ff4444); }
         50% { box-shadow: 0 0 35px var(--color, #ff4444), inset 0 0 35px var(--color, #ff4444); }
       }
+      .${EFFECTS_ID}-input-focus {
+        position: absolute;
+        pointer-events: none;
+        z-index: 2147483639;
+        border-radius: 6px;
+        box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.5), 0 0 16px rgba(59, 130, 246, 0.3);
+        animation: ${EFFECTS_ID}-input-focus-pulse 1.5s ease-in-out infinite;
+      }
+      @keyframes ${EFFECTS_ID}-input-focus-pulse {
+        0%, 100% { box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.5), 0 0 16px rgba(59, 130, 246, 0.3); }
+        50% { box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.7), 0 0 24px rgba(59, 130, 246, 0.5); }
+      }
       .${EFFECTS_ID}-highlight.pulse {
         animation: ${EFFECTS_ID}-pulse 1s ease-in-out infinite;
         border: 3px solid var(--color, #ff4444);
@@ -150,17 +162,22 @@
         font-family: system-ui, sans-serif;
         transition: all 0.3s ease;
       }
+      @keyframes ${EFFECTS_ID}-subtitle-slide-down {
+        from { opacity: 0; transform: translateX(-50%) translateY(-20px); }
+        to   { opacity: 1; transform: translateX(-50%) translateY(0); }
+      }
       .${EFFECTS_ID}-subtitle {
         position: fixed;
         left: 50%;
         transform: translateX(-50%);
-        background: rgba(0, 0, 0, 0.8);
-        color: white;
+        background: var(--subtitle-bg, rgba(0, 0, 0, 0.8));
+        color: var(--subtitle-fg, white);
         padding: 12px 24px;
         border-radius: 8px;
         font-size: 18px;
         max-width: 80%;
         text-align: center;
+        animation: ${EFFECTS_ID}-subtitle-slide-down 0.35s ease-out;
       }
       .${EFFECTS_ID}-drawing-canvas {
         position: fixed;
@@ -182,6 +199,7 @@
     // HIGHLIGHT
     highlight: {
       add(selector, { color = '#ff4444', style = 'border', duration } = {}) {
+        injectStyles();
         const el = utils.getElement(selector);
         if (!el) return false;
         
@@ -213,6 +231,7 @@
     // ANNOTATION
     annotation: {
       add(selector, { text, position = 'top', color = '#333', arrow = true } = {}) {
+        injectStyles();
         const el = utils.getElement(selector);
         if (!el) return false;
         
@@ -247,6 +266,7 @@
     // SPOTLIGHT
     spotlight: {
       show(selector, { opacity = 0.7, label = '' } = {}) {
+        injectStyles();
         const el = utils.getElement(selector);
         if (!el) return false;
         
@@ -355,10 +375,9 @@
         const cursor = document.getElementById('agex-cursor');
         if (!cursor) return;
         
-        const sizes = { normal: 16, large: 24, 'extra-large': 32 };
-        const s = sizes[size] || 24;
-        cursor.style.width = `${s}px`;
-        cursor.style.height = `${s}px`;
+        const scales = { normal: 0.75, large: 1, 'extra-large': 1.3 };
+        const s = scales[size] || 1;
+        cursor.style.transform = `scale(${s})`;
         
         cursor.dataset.clickRipple = clickRipple;
         cursor.dataset.trail = trail;
@@ -390,7 +409,7 @@
         return true;
       },
       
-      showClick(x, y, color = '#ff4444') {
+      showClick(x, y, color = 'rgba(0, 0, 0, 0.15)') {
         const ripple = utils.createElement('div', {
           position: 'fixed',
           left: `${x}px`,
@@ -457,6 +476,117 @@
           await this.moveTo(points[i + 1].x, points[i + 1].y, segmentDuration);
         }
         return true;
+      },
+
+      _lastPos: null,
+
+      animateToPosition(targetX, targetY) {
+        const c = document.getElementById('agex-cursor');
+        if (!c) return 0;
+
+        // Lock demo cursor so native mousemove won't fight the animation
+        if (window.__agexCursor) window.__agexCursor.setAnimationLock(true);
+
+        const vh = window.innerHeight;
+        const wasHidden = c.style.opacity === '0' || c.style.opacity === '' || c.style.left === '-100px';
+        const startX = wasHidden ? (this._lastPos ? this._lastPos.x : 0) : parseFloat(c.style.left) || 0;
+        const startY = wasHidden ? (this._lastPos ? this._lastPos.y : vh / 2) : parseFloat(c.style.top) || vh / 2;
+
+        c.style.transition = 'none';
+        c.style.left = startX + 'px';
+        c.style.top = startY + 'px';
+        c.style.opacity = '1';
+        c.offsetHeight;
+
+        if (isNaN(targetX) || isNaN(targetY)) {
+          if (window.__agexCursor) window.__agexCursor.setAnimationLock(false);
+          return 0;
+        }
+
+        this._lastPos = { x: targetX, y: targetY };
+
+        const dist = Math.sqrt((targetX - startX) ** 2 + (targetY - startY) ** 2);
+        const duration = Math.max(1200, Math.round(dist / 0.3));
+        const start = performance.now();
+        const self = this;
+
+        const step = (now) => {
+          const elapsed = now - start;
+          const t = Math.min(elapsed / duration, 1);
+          const ease = t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+          c.style.left = (startX + (targetX - startX) * ease) + 'px';
+          c.style.top = (startY + (targetY - startY) * ease) + 'px';
+          if (t < 1) {
+            requestAnimationFrame(step);
+          } else {
+            // Animation done — release lock
+            if (window.__agexCursor) window.__agexCursor.setAnimationLock(false);
+          }
+        };
+        requestAnimationFrame(step);
+        return duration;
+      },
+
+      showInputFocus(selector) {
+        this.clearInputFocus();
+        var el = utils.getElement(selector);
+        if (!el) return;
+        var rect = el.getBoundingClientRect();
+        var overlay = document.createElement('div');
+        overlay.id = EFFECTS_ID + '-input-focus';
+        overlay.className = EFFECTS_ID + '-input-focus';
+        overlay.style.left = (rect.left + window.scrollX - 2) + 'px';
+        overlay.style.top = (rect.top + window.scrollY - 2) + 'px';
+        overlay.style.width = (rect.width + 4) + 'px';
+        overlay.style.height = (rect.height + 4) + 'px';
+        document.body.appendChild(overlay);
+      },
+
+      clearInputFocus() {
+        var el = document.getElementById(EFFECTS_ID + '-input-focus');
+        if (el) el.remove();
+      },
+
+      typeText(selector, text, charDelay) {
+        charDelay = charDelay || 80;
+        var el = utils.getElement(selector);
+        if (!el) return 0;
+        el.focus();
+        var i = 0;
+        var len = text.length;
+        function typeNext() {
+          if (i >= len) return;
+          var ch = text[i];
+          el.dispatchEvent(new KeyboardEvent('keydown', { key: ch, bubbles: true }));
+          el.dispatchEvent(new KeyboardEvent('keypress', { key: ch, bubbles: true }));
+          // For contenteditable elements, insert text differently
+          if (el.isContentEditable) {
+            document.execCommand('insertText', false, ch);
+          } else {
+            // Use InputEvent for proper React/framework compatibility
+            var nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+              Object.getPrototypeOf(el), 'value'
+            );
+            if (nativeInputValueSetter && nativeInputValueSetter.set) {
+              nativeInputValueSetter.set.call(el, el.value + ch);
+            } else {
+              el.value = el.value + ch;
+            }
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+          }
+          el.dispatchEvent(new KeyboardEvent('keyup', { key: ch, bubbles: true }));
+          i++;
+          if (i < len) setTimeout(typeNext, charDelay);
+        }
+        typeNext();
+        return len * charDelay;
+      },
+
+      fadeOut() {
+        const c = document.getElementById('agex-cursor');
+        if (!c) return;
+        c.style.transition = 'opacity 0.4s ease-out';
+        c.style.opacity = '0';
       }
     },
 
@@ -1289,12 +1419,15 @@
         });
       },
       
-      showSubtitle(text, duration = 3000, position = 'bottom') {
+      showSubtitle(text, duration = 3000, position = 'bottom', fg = '', bg = '') {
+        injectStyles();
         this.clear();
         const subtitle = utils.createElement('div', {
           [position]: '40px'
         }, `${EFFECTS_ID}-subtitle`);
         subtitle.classList.add(`${EFFECTS_ID}-subtitle`);
+        if (fg) subtitle.style.setProperty('--subtitle-fg', fg);
+        if (bg) subtitle.style.setProperty('--subtitle-bg', bg);
         subtitle.textContent = text;
         document.body.appendChild(subtitle);
         
@@ -1305,6 +1438,7 @@
       
       clear() {
         utils.removeElements(`#${EFFECTS_ID}-subtitle`);
+        utils.removeElements(`.${EFFECTS_ID}-subtitle`);
         if ('speechSynthesis' in window) {
           speechSynthesis.cancel();
         }
@@ -1499,6 +1633,14 @@
       if (el) el.scrollIntoView({ block: 'center', behavior: 'instant' });
     },
 
+    scrollElementToCenter(selector) {
+      var el = typeof selector === 'string' ? document.querySelector(selector) : selector;
+      if (!el) return false;
+      // scrollIntoView with block:'center' handles nested scrollable containers
+      el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'instant' });
+      return true;
+    },
+
     scrollToCoords(y, viewportHeight, elHeight) {
       window.scrollTo({
         top: window.scrollY + y - (viewportHeight / 2) + (elHeight / 2),