@rtrvr-ai/rover 2.0.1 → 2.0.2

package/README.md

@@ -1,6 +1,13 @@
 # @rtrvr-ai/rover
 
-Rover is a DOM-native embedded web agent that lives inside your website. Unlike traditional chat widgets that run in iframes, Rover reads the actual DOM and executes actions directly in the user's browser — enabling real task completion, not just conversation.
+**Turn any web interface into an AI agent — with one line of code.**
+
+Rover is an open-source, DOM-native agent SDK that reads the real DOM,
+plans actions, and executes them directly in the browser. Clicks, form fills,
+navigation, data extraction — sub-second, no screenshots, no remote VMs.
+Embed on websites, browser extensions, Electron apps, or any DOM environment.
+
+[GitHub](https://github.com/rtrvr-ai/rover) · [Website](https://www.rtrvr.ai/rover) · [Docs](https://www.rtrvr.ai/rover/docs) · [Discord](https://rtrvr.ai/discord)
 
 ## Prerequisites
 
@@ -104,6 +111,8 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 
 ## Configuration
 
+### Core
+
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `siteId` | `string` | *required* | Site identifier |
@@ -120,45 +129,136 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 | `allowActions` | `boolean` | `true` | Enable or disable action tools |
 | `openOnInit` | `boolean` | `false` | Open panel immediately on boot |
 | `sessionScope` | `'shared_site' \| 'tab'` | `'shared_site'` | Session sharing across tabs |
-| `taskRouting.mode` | `'auto' \| 'act' \| 'planner'` | `'act'` | Task routing strategy |
-| `taskRouting.plannerOnActError` | `boolean` | `true` | In `auto` mode, retry planner only when ACT does not produce a usable outcome |
-| `taskRouting.actHeuristicThreshold` | `number` | `5` (auto mode) | Auto-routing threshold |
+| `workerUrl` | `string` | auto | Custom worker URL for self-hosting |
+| `apiMode` | `boolean` | auto (`true` when `publicKey` or `sessionToken` exists) | Force API execution mode |
+
+### Timing
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `timing.navigationDelayMs` | `number` | `80` | Delay (ms) before same-tab navigation executes, allowing state persistence |
+| `timing.actionTimeoutMs` | `number` | `30000` | Timeout (ms) for bridge RPC calls from the worker |
+| `timing.domSettleDebounceMs` | `number` | `24` | Adaptive DOM settle debounce before a11y tree capture |
+| `timing.domSettleMaxWaitMs` | `number` | `220` | Adaptive DOM settle max wait before a11y tree capture |
+| `timing.domSettleRetries` | `number` | `0` | Adaptive DOM settle bounded retries before capture |
+| `timing.sparseTreeRetryDelayMs` | `number` | `35` | Additional delay before sparse-tree retry capture |
+| `timing.sparseTreeRetryMaxAttempts` | `number` | `1` | Number of sparse-tree retries when roots are too sparse |
+
+### Tab Indicators
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `ui.tabIndicator.titlePrefix` | `boolean` | `true` | Prepend "[Rover] " to document.title during task execution |
+| `ui.tabIndicator.faviconBadge` | `boolean` | `false` | Overlay a colored dot on the favicon (opt-in due to CORS) |
+| `ui.tabIndicator.widgetTabBar` | `boolean` | `true` | Show in-widget tab bar of agent-controlled tabs |
+
+### Tab Policy
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `tabPolicy.observerByDefault` | `boolean` | — | Start tabs in observer mode by default |
+| `tabPolicy.actionLeaseMs` | `number` | — | Action lease duration in milliseconds |
+
+### Task Management
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `task.singleActiveScope` | `'host_session'` | — | Scope for single active task enforcement |
+| `task.tabScope` | `'task_touched_only'` | — | Tab scope strategy |
+| `task.maxConcurrentWorkers` | `number` | `2` | Maximum concurrent Web Workers (max: 3) |
+| `task.maxQueuedTasks` | `number` | `5` | Maximum queued tasks waiting for a worker |
+| `task.maxArchivedTasks` | `number` | `10` | Maximum archived (terminal) tasks to keep |
+| `task.resume.mode` | `'crash_only'` | — | Resume behavior mode |
+| `task.resume.ttlMs` | `number` | — | Resume TTL in milliseconds |
+| `task.autoResumePolicy` | `'auto' \| 'confirm' \| 'never'` | `'confirm'` | Pending-run resume behavior: auto-resume immediately, require Resume/Cancel confirmation, or always cancel pending interrupted run. |
 | `task.followup.mode` | `'heuristic_same_window'` | `'heuristic_same_window'` | Heuristic follow-up chat-cue carryover mode |
 | `task.followup.ttlMs` | `number` | `120000` | Max age (ms) of prior completed/ended task eligible for follow-up chat cues |
 | `task.followup.minLexicalOverlap` | `number` | `0.18` | Minimum lexical overlap ratio to attach follow-up chat cues |
-| `task.autoResumePolicy` | `'auto' \| 'confirm' \| 'never'` | `'confirm'` | Pending-run resume behavior: auto-resume immediately, require Resume/Cancel confirmation, or always cancel pending interrupted run. |
+
+### Task Routing
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `taskRouting.mode` | `'auto' \| 'act' \| 'planner'` | `'act'` | Task routing strategy |
+| `taskRouting.plannerOnActError` | `boolean` | `true` | In `auto` mode, retry planner only when ACT does not produce a usable outcome |
+| `taskRouting.actHeuristicThreshold` | `number` | `5` (auto mode) | Auto-routing threshold |
+
+### Checkpointing
+
+| Option | Type | Default | Description |
+|---|---|---|---|
 | `checkpointing.enabled` | `boolean` | `true` | Cloud checkpoint sync is enabled by default in v1. Set to `false` to disable. |
 | `checkpointing.autoVisitorId` | `boolean` | `true` | Auto-generate visitor ID when needed |
 | `checkpointing.ttlHours` | `number` | `1` | Checkpoint TTL in hours |
 | `checkpointing.onStateChange` | `(payload) => void` | — | Checkpoint lifecycle updates (`active`, `paused_auth`) |
 | `checkpointing.onError` | `(payload) => void` | — | Checkpoint request error callback |
+
+### Telemetry
+
+| Option | Type | Default | Description |
+|---|---|---|---|
 | `telemetry.enabled` | `boolean` | `true` | Enable runtime telemetry batching |
 | `telemetry.sampleRate` | `number` | `1` | Sampling ratio (`1` = all events, `0.1` ≈ 10%) |
 | `telemetry.flushIntervalMs` | `number` | `12000` | Flush cadence for buffered telemetry events |
 | `telemetry.maxBatchSize` | `number` | `30` | Maximum number of telemetry events sent per flush request |
 | `telemetry.includePayloads` | `boolean` | `false` | Include richer per-event payload details (debug/tool context). Increases telemetry volume and may include sensitive runtime content. |
-| `apiMode` | `boolean` | auto (`true` when `publicKey` or `sessionToken` exists) | Force API execution mode |
-| `apiToolsConfig.mode` | `'allowlist' \| 'profile' \| 'none'` | `'none'` | API additional tool exposure mode |
-| `tools.web.enableExternalWebContext` | `boolean` | `false` | External tab cloud context fallback |
-| `tools.web.scrapeMode` | `'off' \| 'on_demand'` | `'off'` | On-demand external tab scrape mode |
-| `tools.web.allowDomains` | `string[]` | `[]` | External context allowlist |
-| `tools.web.denyDomains` | `string[]` | `[]` | External context denylist |
-| `tools.client` | `ClientToolDefinition[]` | `[]` | Runtime-registered client tools |
-| `workerUrl` | `string` | auto | Custom worker URL for self-hosting |
+
+### UI
+
+| Option | Type | Default | Description |
+|---|---|---|---|
 | `ui.agent.name` | `string` | `'Rover'` | Custom assistant name |
 | `ui.mascot.disabled` | `boolean` | `false` | Disable mascot video |
 | `ui.mascot.mp4Url` | `string` | default | Custom mascot MP4 URL |
 | `ui.mascot.webmUrl` | `string` | default | Custom mascot WebM URL |
 | `ui.muted` | `boolean` | `true` | Start with audio muted on first load; stored browser preference wins after the user toggles sound |
 | `ui.thoughtStyle` | `'concise_cards' \| 'minimal'` | `'concise_cards'` | Thought rendering style |
-| `ui.panel.resizable` | `boolean` | `true` | Panel resizable preference |
+| `ui.panel.resizable` | `boolean` | `true` | Enables desktop freeform resizing plus phone/tablet snap-height resizing with per-device memory |
 | `ui.showTaskControls` | `boolean` | `true` | Show new/end task controls |
 | `ui.shortcuts` | `RoverShortcut[]` | `[]` | Suggested journeys (max 100 stored, max 12 rendered by default; lower site-key policy caps are enforced) |
 | `ui.greeting` | `{ text?, delay?, duration?, disabled? }` | — | Greeting bubble config (`{name}` token supported) |
+| `ui.voice` | `{ enabled?: boolean; language?: string; autoStopMs?: number }` | — | Browser dictation for supported Chromium browsers. Rover fills the draft live, waits for post-speech silence before stopping, and the user still sends manually. |
+
+### Web Tools
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiToolsConfig.mode` | `'allowlist' \| 'profile' \| 'none'` | `'none'` | API additional tool exposure mode |
+| `tools.web.enableExternalWebContext` | `boolean` | `false` | External tab cloud context fallback |
+| `tools.web.scrapeMode` | `'off' \| 'on_demand'` | `'off'` | On-demand external tab scrape mode |
+| `tools.web.allowDomains` | `string[]` | `[]` | External context allowlist |
+| `tools.web.denyDomains` | `string[]` | `[]` | External context denylist |
+| `tools.client` | `ClientToolDefinition[]` | `[]` | Runtime-registered client tools |
 | `pageConfig` | `RoverPageCaptureConfig` | — | Optional per-site page-capture overrides such as `disableAutoScroll`, settle timing, and sparse-tree retry settings |
 
-When a site key or session token is used, Rover fetches cloud site config via `/v2/rover/session/open` (shortcuts + greeting + pageConfig).  
+### AI-Callable URLs (Deep Links)
+
+Rover can be triggered via URL query parameters, turning any page into an AI-callable endpoint.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `deepLink.enabled` | `boolean` | `false` | Enable URL-triggered Rover |
+| `deepLink.promptParam` | `string` | `'rover'` | Query parameter for natural-language prompts |
+| `deepLink.shortcutParam` | `string` | `'rover_shortcut'` | Query parameter for shortcut IDs |
+| `deepLink.consume` | `boolean` | `true` | Strip deep link params from URL after reading |
+
+**Prompt deep link** — pass a natural-language instruction:
+
+```
+https://example.com?rover=book%20a%20flight
+```
+
+**Shortcut deep link** — invoke a pre-defined flow by ID:
+
+```
+https://example.com?rover_shortcut=checkout_flow
+```
+
+For AI or CLI-triggered entrypoints, prefer exact shortcut IDs for repeatable flows.
+
+When a site key or session token is used, Rover fetches cloud site config via `/v2/rover/session/open` (shortcuts + greeting + voice + pageConfig).
 If the same field exists in both cloud config and boot config, boot config wins.
+`deepLink` is boot/runtime only and is not persisted in cloud site config.
 
 If you enable `tools.web.scrapeMode: 'on_demand'`, use a site key capability profile that includes cloud scrape support.
 
@@ -301,6 +401,9 @@ Load your self-hosted `embed.js` instead of the CDN version:
 
 ## Links
 
+- [GitHub](https://github.com/rtrvr-ai/rover)
 - [Integration Guide](https://github.com/rtrvr-ai/rover/blob/main/docs/INTEGRATION.md)
 - [Rover Workspace](https://rover.rtrvr.ai/workspace) — generate site keys and install snippets
 - [Website](https://www.rtrvr.ai/rover)
+- [Documentation](https://www.rtrvr.ai/rover/docs)
+- [Discord](https://rtrvr.ai/discord)