@rtrvr-ai/rover 3.0.0 → 3.0.1

package/README.md

@@ -13,6 +13,8 @@ Embed on websites, browser extensions, Electron apps, or any DOM environment.
 
 You need an rtrvr.ai account with available credits. Free accounts get 250 credits/month. [Sign up or manage your plan](https://www.rtrvr.ai/cloud?view=pricing).
 
+Before you test Rover on arbitrary websites, get your site config from Workspace first. Hosted Preview is the only path that does not require Workspace config.
+
 ## Quick Start (Script Tag)
 
 Add this snippet before `</body>` on any page:
@@ -59,6 +61,7 @@ Or use the single-tag shorthand with data attributes:
 <script src="https://rover.rtrvr.ai/embed.js"
   data-site-id="YOUR_SITE_ID"
   data-public-key="pk_site_YOUR_PUBLIC_KEY"
+  data-session-token="rvrsess_YOUR_SHORT_LIVED_SESSION_TOKEN"
   data-allowed-domains="yourdomain.com"
   data-domain-scope-mode="registrable_domain">
 </script>
@@ -66,6 +69,8 @@ Or use the single-tag shorthand with data attributes:
 
 Use `data-domain-scope-mode="host_only"` to require exact host matches. Plain entries such as `example.com` become exact-host rules in `host_only` mode. In the default `registrable_domain` mode, plain entries match the apex host and its subdomains, while `*.example.com` matches subdomains only.
 
+For temporary preview sessions, `data-session-token` can bootstrap Rover without a `publicKey`. If you also have a `sessionId`, add `data-session-id` for a stable runtime boundary.
+
 Common patterns:
 
 - `allowedDomains: ['example.com']` with `registrable_domain` allows `example.com` and all subdomains.
@@ -73,6 +78,182 @@ Common patterns:
 - `allowedDomains: ['app.example.com']` with `registrable_domain` allows `app.example.com` and its subdomains, but not sibling hosts.
 - `allowedDomains: ['example.com']` with `host_only` allows only the exact host `example.com`.
 
+## Preview Helpers
+
+The SDK also exports generic helper utilities for live demos and previews:
+
+```ts
+import {
+  attachLaunch,
+  createRoverBookmarklet,
+  createRoverConsoleSnippet,
+  createRoverScriptTagSnippet,
+} from '@rtrvr-ai/rover';
+```
+
+Use `createRoverConsoleSnippet(...)` and `createRoverBookmarklet(...)` to generate one-click bootstrap payloads, and `attachLaunch(...)` when you want to attach a pre-created launch from code.
+
+Before you use any of these helpers on another website:
+
+1. Open Rover Workspace.
+2. Create or rotate a site key so Workspace reveals the full `pk_site_*` value.
+3. Copy the **test config JSON** from Workspace.
+4. Either paste that JSON into the Rover website's "Try on Other Sites" tool, or pass the same values into the SDK helpers below.
+
+### Which helper to use
+
+| Path | What you need | Best for | Persistence |
+|---|---|---|---|
+| Hosted Preview | Signed-in URL + prompt | Rover-managed demos | Temporary preview session |
+| Preview Helper | Workspace test config JSON or hosted handoff | Multi-page desktop demos | Re-injects after reload/navigation |
+| Console | Workspace test config JSON + generated snippet | Fast DevTools demos | Current page only |
+| Bookmarklet | Workspace test config JSON + generated bookmarklet | Drag-and-click demos | Current page only |
+| Production install | Workspace install snippet | Real site install | Persistent |
+
+- `createRoverConsoleSnippet(...)`
+  Best for desktop demos, debugging, and screen-sharing when you can paste into DevTools.
+- `createRoverBookmarklet(...)`
+  Best for quick one-click demos across many pages, with the same current-page limitations as manual injection.
+- `createRoverScriptTagSnippet(...)`
+  Best for generating an actual snippet from known config values such as Workspace `siteId` and `publicKey`.
+- `attachLaunch(...)`
+  Best when you already created a launch elsewhere and want Rover to attach to it after boot.
+
+### Example: console snippet from Workspace config
+
+```ts
+import { createRoverConsoleSnippet } from '@rtrvr-ai/rover';
+
+const snippet = createRoverConsoleSnippet({
+  siteId: 'site_123',
+  publicKey: 'pk_site_123',
+  siteKeyId: 'key_123',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'registrable_domain',
+  apiBase: 'https://agent.rtrvr.ai',
+  openOnInit: true,
+  mode: 'full',
+  allowActions: true,
+});
+```
+
+### Example: bookmarklet from Workspace config
+
+```ts
+import { createRoverBookmarklet } from '@rtrvr-ai/rover';
+
+const bookmarklet = createRoverBookmarklet({
+  siteId: 'site_123',
+  publicKey: 'pk_site_123',
+  siteKeyId: 'key_123',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'registrable_domain',
+  apiBase: 'https://agent.rtrvr.ai',
+});
+```
+
+### Example: production script-tag snippet from Workspace config
+
+```ts
+import { createRoverScriptTagSnippet } from '@rtrvr-ai/rover';
+
+const snippet = createRoverScriptTagSnippet({
+  siteId: 'site_123',
+  publicKey: 'pk_site_123',
+  siteKeyId: 'key_123',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'registrable_domain',
+  apiBase: 'https://agent.rtrvr.ai',
+});
+```
+
+### Example: attach a pre-created launch
+
+```ts
+import { attachLaunch, boot } from '@rtrvr-ai/rover';
+
+boot({
+  siteId: 'preview_site',
+  sessionToken: 'rvrsess_short_lived_token',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'host_only',
+});
+
+attachLaunch({
+  requestId: 'rl_123',
+  attachToken: 'attach_123',
+});
+```
+
+### Two config sources
+
+Use one of these sources for the helper functions above:
+
+- **Workspace production config**
+  Persistent `siteId`, `publicKey`, optional `siteKeyId`, `allowedDomains`, and `domainScopeMode` from Rover Workspace.
+- **Hosted preview config**
+  Short-lived preview/runtime values produced by Rover Instant Preview on the website or by your own preview service.
+
+Get Workspace config from:
+
+- [https://www.rtrvr.ai/rover/workspace](https://www.rtrvr.ai/rover/workspace)
+- [https://rover.rtrvr.ai/workspace](https://rover.rtrvr.ai/workspace)
+
+If you want the exact human walkthrough instead of jumping straight into code:
+
+- website guide: [https://www.rtrvr.ai/rover/docs/try-on-other-sites](https://www.rtrvr.ai/rover/docs/try-on-other-sites)
+- repo guide: [../../docs/TRY_ON_OTHER_SITES.md](../../docs/TRY_ON_OTHER_SITES.md)
+- one-click helper path: use the website tool's `Open target with helper` action after pasting the Workspace config
+
+If you want a public extension that can use either config source, see the Preview Helper app:
+
+- [https://github.com/rtrvr-ai/rover/tree/main/apps/preview-helper](https://github.com/rtrvr-ai/rover/tree/main/apps/preview-helper)
+- [https://www.rtrvr.ai/rover/docs/instant-preview-api](https://www.rtrvr.ai/rover/docs/instant-preview-api)
+
+### Hosted preview handoff behavior
+
+The open-source helper extension understands hosted preview handoff URLs that include:
+
+- `rover_preview_id`
+- `rover_preview_token`
+- `rover_preview_api`
+
+When those are present, the helper can fetch the short-lived preview config from the hosted Rover API and reconnect it across navigation.
+
+### Security notes
+
+- `pk_site_*` values are Workspace install credentials for a real site.
+- `rvrsess_*` values are short-lived runtime session credentials.
+- Preview tokens are demo credentials and should be treated as ephemeral.
+- Do not treat preview tokens as a replacement for production Workspace site keys.
+- Keep preview or helper injections scoped to the intended host with `allowedDomains` and the right `domainScopeMode`.
+- Generic `publicKey` config is the normal Workspace path. `sessionToken` is the temporary preview/runtime path.
+
+### Troubleshooting
+
+- **`This API key is missing capability: roverEmbed`**
+  Your Workspace key is not embed-enabled. Rotate or create an embed-ready key, then rebuild the snippet or bookmarklet from the fresh test config JSON.
+- **`React has blocked a javascript: URL`**
+  Delete any old Rover bookmarklet and recreate it from the latest Rover Live Test page. The bookmarklet must be dragged from Rover's dedicated drag control, not clicked on the Rover page itself.
+- **Console or Bookmarklet worked once, then stopped**
+  Those are current-page-only methods. A full reload drops the injected JavaScript.
+- **A site still blocks Rover after you generated valid output**
+  Some sites enforce strict CSP or reload aggressively. Use the Preview Helper or Hosted Preview instead.
+- **`Open hosted shell` does nothing**
+  Hosted Preview should open Rover's dedicated hosted viewer route, not the launcher page.
+
+### Hosted playground
+
+If you want the full managed preview flow, including preview creation and Workspace handoff, use the hosted website:
+
+- [https://www.rtrvr.ai/rover/instant-preview](https://www.rtrvr.ai/rover/instant-preview)
+
+More architecture detail:
+
+- [Instant Preview architecture](https://github.com/rtrvr-ai/rover/blob/main/docs/INSTANT_PREVIEW.md)
+- [Hosted preview API docs](https://www.rtrvr.ai/rover/docs/instant-preview-api)
+- [Hosted preview OpenAPI spec](https://raw.githubusercontent.com/rtrvr-ai/rtrvr-cloud-backend/main/docs/rover-instant-preview.openapi.yaml)
+
 ## npm Install
 
 ```bash