ttp-agent-sdk 2.33.4 → 2.34.0

package/README.md

@@ -410,6 +410,227 @@ The tool uses `html2canvas` to render the DOM:
 - **Cross-Origin**: The tool handles cross-origin images when possible (`useCORS: true`).
 - **Browser Compatibility**: Requires modern browsers with Canvas API support (Chrome 66+, Firefox 60+, Safari 11.1+, Edge 79+).
 
+## Scroll Tool (`scroll_to_element`)
+
+The `scroll_to_element` tool allows AI agents to scroll the page in three different ways: scrolling to a specific element, relative scrolling (up/down), or scrolling to an absolute position.
+
+### Scroll Modes
+
+The tool supports three scroll modes with the following priority order:
+
+1. **Element Scrolling** (highest priority) - Scroll to a specific element by CSS selector
+2. **Relative Scrolling** - Scroll up or down by a specified number of pixels
+3. **Absolute Position Scrolling** - Scroll to specific x/y coordinates
+
+### 1. Scroll to Element
+
+Scroll to a specific element on the page using a CSS selector.
+
+**Example: Scroll to element**
+```javascript
+// The agent can call this tool with:
+{
+  tool: "scroll_to_element",
+  params: {
+    selector: "#contact-section",  // CSS selector
+    position: "center",              // 'center', 'top', or 'bottom'
+    behavior: "smooth"               // 'smooth' or 'instant'
+  }
+}
+```
+
+**Example: Scroll element to top**
+```javascript
+{
+  tool: "scroll_to_element",
+  params: {
+    selector: ".header",
+    position: "top",    // Scrolls element to top of viewport
+    behavior: "smooth"
+  }
+}
+```
+
+### 2. Relative Scrolling (Scroll Up/Down)
+
+Scroll the page up or down by a specified number of pixels. This is useful for incremental scrolling or scrolling by viewport height.
+
+**Example: Scroll down (default 500px)**
+```javascript
+{
+  tool: "scroll_to_element",
+  params: {
+    direction: "down",
+    amount: 500,        // Pixels to scroll (default: 500)
+    behavior: "smooth"
+  }
+}
+```
+
+**Example: Scroll up (custom amount)**
+```javascript
+{
+  tool: "scroll_to_element",
+  params: {
+    direction: "up",
+    amount: 500,        // Scroll up 500 pixels
+    behavior: "smooth"
+  }
+}
+```
+
+**Example: Scroll down by viewport height**
+```javascript
+{
+  tool: "scroll_to_element",
+  params: {
+    direction: "down",
+    amount: window.innerHeight,  // Scroll one viewport height
+    behavior: "smooth"
+  }
+}
+```
+
+**Features:**
+- Automatically prevents scrolling beyond page boundaries (won't scroll below 0 or above max scroll)
+- Returns `atTop` and `atBottom` flags to indicate if scroll limits were reached
+- Respects smooth/instant scrolling behavior
+
+### 3. Absolute Position Scrolling
+
+Scroll to specific x/y coordinates on the page.
+
+**Example: Scroll to absolute position**
+```javascript
+{
+  tool: "scroll_to_element",
+  params: {
+    x: 0,              // Horizontal position (optional)
+    y: 1000,           // Vertical position
+    behavior: "smooth"
+  }
+}
+```
+
+**Example: Scroll to top of page**
+```javascript
+{
+  tool: "scroll_to_element",
+  params: {
+    x: 0,
+    y: 0,
+    behavior: "instant"  // Instant scroll to top
+  }
+}
+```
+
+### Tool Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `selector` | string | No* | - | CSS selector for element to scroll to. Takes highest priority if provided. |
+| `position` | string | No | `'center'` | Position for element scrolling: `'center'`, `'top'`, or `'bottom'`. Only used with `selector`. |
+| `direction` | string | No* | - | Direction for relative scrolling: `'up'` or `'down'`. Only used if no `selector` provided. |
+| `amount` | number | No | `500` | Pixels to scroll for relative scrolling. Only used with `direction`. |
+| `x` | number | No* | - | Horizontal scroll position. Only used if no `selector` or `direction` provided. |
+| `y` | number | No* | - | Vertical scroll position. Only used if no `selector` or `direction` provided. |
+| `behavior` | string | No | `'smooth'` | Scroll behavior: `'smooth'` or `'instant'`. |
+
+\* At least one of `selector`, `direction`, or `x`/`y` must be provided.
+
+### Return Values
+
+The tool returns different result objects depending on the scroll mode:
+
+**Element Scrolling Result:**
+```javascript
+{
+  success: true,
+  scrollType: "element",
+  selector: "#contact-section",
+  elementPosition: {
+    top: 1200,    // Element's position after scroll
+    left: 0
+  }
+}
+```
+
+**Relative Scrolling Result:**
+```javascript
+{
+  success: true,
+  scrollType: "relative",
+  direction: "down",
+  amount: 300,
+  scrolledFrom: { y: 500 },      // Starting scroll position
+  scrolledTo: { y: 800 },         // Final scroll position
+  atTop: false,                   // True if scrolled to top
+  atBottom: false                 // True if scrolled to bottom
+}
+```
+
+**Absolute Position Scrolling Result:**
+```javascript
+{
+  success: true,
+  scrollType: "position",
+  scrolledTo: {
+    x: 0,
+    y: 1000
+  }
+}
+```
+
+**Error Result:**
+```javascript
+{
+  success: false,
+  error: "Element not found: #missing-element"
+}
+```
+
+### Priority Order
+
+The tool checks parameters in this order:
+
+1. **`selector`** - If provided, scrolls to element (ignores `direction` and `x`/`y`)
+2. **`direction`** - If no `selector`, checks for `direction: 'up'` or `'down'` (ignores `x`/`y`)
+3. **`x`/`y`** - If no `selector` or `direction`, uses absolute position scrolling
+
+### Use Cases
+
+**Scroll to specific section:**
+```javascript
+{ selector: "#pricing", position: "top" }
+```
+
+**Scroll down to see more content:**
+```javascript
+{ direction: "down", amount: 500 }
+```
+
+**Scroll up to previous content:**
+```javascript
+{ direction: "up", amount: 300 }
+```
+
+**Scroll to top of page:**
+```javascript
+{ y: 0, behavior: "instant" }
+```
+
+**Scroll to bottom of page:**
+```javascript
+{ y: document.documentElement.scrollHeight, behavior: "smooth" }
+```
+
+### Important Notes
+
+- **Boundary Protection**: Relative scrolling automatically prevents scrolling beyond page boundaries
+- **Backward Compatible**: Existing code using `selector` or `x`/`y` continues to work unchanged
+- **Smooth Scrolling**: Default behavior is smooth scrolling (500ms wait time). Use `behavior: "instant"` for immediate scrolling (100ms wait time)
+- **Element Not Found**: If selector doesn't match any element, returns error without scrolling
+
 ## Examples
 
 See the `examples/` directory for complete usage examples: