@sable-ai/sdk-core 0.1.3 → 0.1.5

package/README.md

@@ -1,55 +1,349 @@
-# @sable-ai/sdk-core
+# Adding a Sable agent to your website
 
-v0 browser runtime for Sable: joins a LiveKit room and lets the user talk to an
-agent worker. Voice-only. No DOM tools, no UI overlay, no events API.
+> **Beta.** The platform UI, the SDK API, and the error codes described below
+> may still change before general availability. If you're integrating now,
+> pin the SDK to an exact version.
 
-## Install
+Sable is a voice + vision agent that lives inside your users' browsers. Drop
+a single `<script>` tag on the pages where you want it, call `Sable.start()`,
+and an agent you configured on the Sable platform can talk to your user and
+see what they see — no iframes, no overlays you don't control, no changes to
+your backend.
 
-```bash
-bun add @sable-ai/sdk-core
+This guide walks you through the end-to-end integration as a web engineer at
+a company that already has a Sable account.
+
+---
+
+## 1. Create an agent on the Sable platform
+
+1. Sign in to <https://platform.withsable.com>.
+2. **Agents → New agent**. Give it a name and pick a template (voice-only,
+   voice + vision, etc).
+3. Write the agent's system prompt and configure its tools. This is the same
+   agent config you'd use in any Sable channel — the SDK just exposes it in
+   your user's browser instead of a Sable-hosted call page.
+4. Publish the agent. You'll land on the agent detail page.
+
+## 2. Add your domain to the allowlist
+
+Still on the agent detail page:
+
+1. Open the **Web SDK** tab.
+2. Under **Allowed domains**, add every origin where you intend to load the
+   SDK. Exact hostnames only — `example.com`, `www.example.com`,
+   `app.example.com`. Wildcards are supported as a leading `*.`
+   (e.g. `*.example.com` covers every subdomain).
+3. Save.
+
+Why this matters: the SDK is loaded inside the user's browser and talks
+directly to the Sable API from the page. Sable rejects requests from any
+origin that isn't on this list, so adding your domain here is the gate
+that lets the script tag on your site actually connect. **If you forget
+this step, you'll see a CORS error in the devtools console and nothing
+else — the call never starts.**
+
+Allowed domains are scoped to the agent. An agent for your marketing site
+and an agent for your product dashboard can have different allowlists.
+
+## 3. Copy your public key
+
+On the same **Web SDK** tab, under **Public key**, you'll see a value like:
+
+```
+pk_live_8f3a9c2d4e5b6a7c
 ```
 
-Or include the IIFE bundle directly:
+This is the key you'll paste into your page. It's a **publishable** key —
+safe to ship in client-side code, visible in devtools, not a secret. It
+identifies the agent and is validated by Sable against the allowed-domains
+list above, so even if someone copies it onto their own site it won't work
+unless their origin is on your allowlist.
+
+If you ever need to rotate it (e.g. the key shows up somewhere you don't
+want it), click **Rotate key** and update the snippet on your site. The old
+key is immediately invalidated.
+
+## 4. Load the SDK
+
+You have two options. Both expose the same API; pick whichever fits your
+stack.
+
+### Option A: Script tag (works everywhere)
+
+Add this to every page you want the agent to be available on:
 
 ```html
-<script src="./sable.iife.js"></script>
+<script src="https://sdk.withsable.com/v1/sable.js" async></script>
 ```
 
-## Usage
+That's a **~530 B gzipped loader stub** — no dependencies, no
+stylesheet, no livekit, no vision runtime. The loader installs a single
+global (`window.Sable`) and does nothing else until you call `start()`:
+no network requests, no microphone prompt, no DOM mutations. Idle cost
+to your site is effectively zero.
+
+On the first `Sable.start()` call, the loader dynamic-imports the full
+SDK (`sable-core.mjs`, ~150 KB gzipped with livekit-client inlined) from
+the **same CDN path** it was served from — so loading
+`https://sdk.withsable.com/v0.1.5/sable.js` always pulls
+`https://sdk.withsable.com/v0.1.5/sable-core.mjs`, and version cohesion
+is automatic. Pages that never start a session pay only the loader cost;
+pages that do start a session pay the core download exactly once, cached
+aggressively for the lifetime of the version pin.
+
+The script is served from Sable's CDN (`sdk.withsable.com`, Cloudflare
+Pages), cached at the edge, and versioned. Three path conventions:
+
+| URL | Cache | Use case |
+| --- | --- | --- |
+| `https://sdk.withsable.com/v0.1.5/sable.js` | 1 year, immutable | **Recommended for production** — exact version pin |
+| `https://sdk.withsable.com/v1/sable.js` | 1 hour | Latest `0.x` — accepts patch releases automatically |
+| `https://sdk.withsable.com/latest/sable.js` | 5 minutes | Demos and smoke tests only |
+
+`v1` is a stable major line — the API won't change without a major
+bump. Pin to an exact version (`v0.1.5`) if you want bit-for-bit
+reproducibility.
+
+### Option B: npm package (React, Vue, Svelte, Next, etc.)
+
+```bash
+npm install @sable-ai/sdk-core
+```
+
+```js
+import Sable from "@sable-ai/sdk-core";
+
+await Sable.start({ publicKey: "pk_live_..." });
+```
+
+The npm package is a standalone ESM bundle (livekit-client declared as a
+regular dependency so your bundler can dedupe it) — it does **not**
+fetch from the CDN. Importing the module also installs `window.Sable`
+with first-write-wins semantics, so mixing the script tag and the npm
+package on the same page is safe: whichever loads first installs the
+global and the other becomes a no-op. You get TypeScript types and
+bundler-integrated imports. Use this path if you want typed autocomplete
+and a bundler-controlled dependency graph.
+
+## 5. Start a session from your app code
+
+When you want the agent to actually connect — on a button click, on page
+load, when the user opens a help menu, whatever — call:
 
 ```js
 await window.Sable.start({
-  agentPublicId: "agt_...",
-  apiUrl: "https://sable-api-gateway-9dfmhij9.wl.gateway.dev", // optional, this is the default
-  nickelRegion: "us-east1", // optional
+  publicKey: "pk_live_8f3a9c2d4e5b6a7c",
+
+  // Optional — what the agent can see.
+  vision: {
+    enabled: true,
+    // How frames are produced. Defaults to the built-in wireframe renderer.
+    // Discriminated on `type`:
+    //   { type: "wireframe", features: { includeImages?: boolean } }
+    //   { type: "fn", captureFn: () => HTMLCanvasElement | ImageBitmap }
+    frameSource: {
+      type: "wireframe",
+      rate: 2, // frames per second; default 2
+      features: {
+        includeImages: true, // include rendered images, not just layout boxes
+      },
+    },
+  },
+
+  // Optional — implementations for methods the agent can RPC into your page.
+  // The SDK defines a small set of "UI stub" methods (e.g. showMessage,
+  // highlightElement). You can override any of them here, and add your own
+  // for agent tools specific to your app. Anything you pass becomes callable
+  // by the agent.
+  runtime: {
+    showMessage: (text) => myToast.show(text),
+    highlightElement: (selector) => { /* ... */ },
+    openDocument: (docId) => router.push(`/docs/${docId}`),
+  },
+
+  // Optional — arbitrary context forwarded to the agent at session start.
+  // Surfaces verbatim in the agent's initial prompt.
+  context: {
+    userId: currentUser.id,
+    userName: currentUser.name,
+    currentPage: "dashboard",
+  },
 });
+```
 
-// ... user talks to the agent ...
+`Sable.start()` returns a promise that resolves when the mic is live and
+the agent has greeted the user. It rejects if the public key is invalid,
+the origin isn't on the allowlist, or the user denies microphone access.
 
+To end the session:
+
+```js
 await window.Sable.stop();
 ```
 
-## Local test
+You can call `start()` and `stop()` as many times as you like during a page
+lifetime. Only one session can be active at a time.
+
+## 6. React to session events (optional)
+
+If you want to, say, show your own UI when the agent is talking, subscribe
+to events:
+
+```js
+window.Sable.on("session:started", () => { ... });
+window.Sable.on("session:ended", (reason) => { ... });
+window.Sable.on("agent:speaking", (speaking) => { ... });
+window.Sable.on("user:speaking", (speaking) => { ... });
+window.Sable.on("error", (err) => { ... });
+```
+
+All events are fire-and-forget; the SDK does not care whether you subscribe.
+
+---
+
+## Reference: `Sable.start()` options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `publicKey` | `string` | **required** | The `pk_live_*` key from the platform. |
+| `vision.enabled` | `boolean` | `false` | Whether to publish a video track of the page to the agent. |
+| `vision.frameSource` | `FrameSource` | `{ type: "wireframe" }` | Where frames come from. Either the built-in wireframe renderer or a custom function (see below). |
+| `vision.frameSource.rate` | `number` | `2` | Capture rate in frames per second. Applies to both `wireframe` and `fn`. Higher = more responsive agent vision, more bandwidth. |
+| `vision.frameSource.features.includeImages` | `boolean` | `true` | (Wireframe only.) Include rendered images, not just layout boxes. Set to `false` to ship only layout boxes (lower bandwidth). |
+| `vision.frameSource.captureFn` | `() => HTMLCanvasElement \| ImageBitmap` | — | (Required when `type: "fn"`.) Called at `rate` Hz. Useful for feeding the agent a custom canvas (e.g. a 3D scene, a video element, a WebGL surface). |
+| `runtime` | `Record<string, Function>` | `{}` | Implementations for UI-stub methods the agent can call, plus any additional methods you want to expose as agent tools. |
+| `context` | `Record<string, unknown>` | `{}` | Forwarded verbatim to the agent at session start. Appears in the agent's initial prompt. |
+
+## Reference: errors
+
+| Code | Cause | Fix |
+| --- | --- | --- |
+| `SABLE_INVALID_KEY` | Public key doesn't exist or was rotated. | Copy the current key from the platform. |
+| `SABLE_ORIGIN_NOT_ALLOWED` | Page's origin isn't on the agent's allowlist. | Add the exact origin in the platform's Web SDK → Allowed domains. |
+| `SABLE_MIC_DENIED` | User denied microphone permission. | Prompt them again, or show a message explaining why voice is needed. |
+| `SABLE_RATE_LIMITED` | Too many sessions started from this origin in a short window. | Back off and retry. |
+| `SABLE_NETWORK` | Couldn't reach the Sable API. | Usually transient — retry with backoff. |
+
+---
+
+## FAQ
+
+**Do I need a backend integration?**
+No. The SDK talks directly to the Sable API from the page. There's no
+webhook to install, no server-to-server auth, no token exchange you have to
+implement. The public key + allowed-domains check is the entire trust model.
+
+**Is the public key a secret?**
+No — it's designed to be shipped in client-side code. The security boundary
+is the allowed-domains list, not the key itself. Someone who copies your
+key to their own site can't use it unless their origin is also on your
+allowlist.
+
+**Script tag or npm package — which should I use?**
+Either. Use the script tag for static HTML or if you want to avoid
+bundler configuration — you get the Stripe.js-style split bundle
+(~530 B on page load, core lazy-loaded from the CDN on first
+`Sable.start()`). Use the npm package if you want TypeScript types and a
+bundler-integrated, self-contained dependency graph — the package is a
+standalone ESM build that does not fetch from the CDN. Mixing on the
+same page is safe: both install `window.Sable` with first-write-wins
+semantics, so whichever runs first wins and the other becomes a no-op.
+
+**Why a global (`window.Sable`) instead of an import-only API?**
+To keep the drop-in story honest. A single `<script>` tag works in every
+web framework — React, Vue, Svelte, Next, Rails, plain HTML — without
+bundler setup. The npm package also installs the same global on import,
+so mixed usage stays coherent.
+
+**Does the SDK render anything by default?**
+The SDK itself is headless — it handles voice, vision, and agent
+communication but renders nothing on its own. A default UI (mic button,
+avatar, agent-driven overlays) can be enabled via a separate package, or
+you can build your own using the event API and your own component library.
+
+**Does the agent see my users' data?**
+Only what's on the page at the moment the session is active, and only if
+`vision.enabled` is `true`. The wireframe is generated client-side and
+streamed as a video track; Sable never scrapes, indexes, or stores page
+content server-side. Microphone audio is end-to-end within the voice
+session.
+
+**What happens if the user navigates away?**
+The session ends. The SDK tears down the connection, stops the microphone,
+and unmounts anything it mounted. A fresh `Sable.start()` on the next page
+creates a new session.
+
+**How do I test this locally?**
+Add `http://localhost:3000` (or whatever port you use) to the allowed
+domains list alongside your production origin. The SDK treats localhost
+the same as any other origin — there's no special dev bypass.
+
+**Can I self-host the script?**
+Not recommended. The CDN copy is versioned, cached globally, and updated
+automatically. If you really need to — e.g. an air-gapped customer —
+you need to host **both** files side-by-side under the same path:
+`sable.js` (the loader) and `sable-core.mjs` (the full SDK). The loader
+resolves the core via `new URL("./sable-core.mjs", document.currentScript.src)`,
+so they must live in the same directory. Contact support for details.
+
+**Does the SDK work with strict CSP (`script-src` nonces, etc.)?**
+Yes. Apply your nonce to the `<script>` tag as usual. The loader
+dynamic-imports `sable-core.mjs` from the **same origin** it was served
+from (`sdk.withsable.com` by default), so your CSP needs to allow that
+origin in `script-src` — typically `script-src 'self' https://sdk.withsable.com`
+if you load from the public CDN. No third-party origins are contacted
+at runtime beyond `sdk.withsable.com` (for the core bundle) and
+`sable-api-gateway-9dfmhij9.wl.gateway.dev` (for the session — plus
+the LiveKit WebSocket origin returned by the session endpoint). If
+you self-host `sable.js` + `sable-core.mjs` under your own origin,
+`'self'` covers the script side; the API + LiveKit origins still
+need to be in `connect-src`.
+
+---
+
+## Development
+
+> This section is for contributors to `@sable-ai/sdk-core` itself. If
+> you're integrating Sable into your site, stop here.
+
+The package source lives at
+[`sable-inc/js-sdk`](https://github.com/sable-inc/js-sdk) under
+`packages/sdk-core`. Build:
 
 ```bash
 bun install
 bun run --filter @sable-ai/sdk-core build
+```
+
+This produces three artifacts in `dist/`:
+
+| Artifact | Entry | Consumer |
+| --- | --- | --- |
+| `dist/sable.iife.js` | `src/loader.ts` (minified IIFE) | CDN script tag |
+| `dist/sable-core.mjs` | `src/index.ts` (minified ESM, livekit inlined) | CDN lazy-import from the loader |
+| `dist/esm/index.js` + `dist/types/` | `src/index.ts` (ESM, livekit external) | `npm install @sable-ai/sdk-core` |
+
+### Local smoke test
+
+```bash
 python3 -m http.server 5173 --directory packages/sdk-core
 ```
 
-Open `http://localhost:5173/examples/test.html`, paste an agent public ID, click Start.
-Grant mic permission when prompted. Observe the console for LiveKit session
-events.
+Open `http://localhost:5173/examples/test.html`, paste an agent public
+ID, click Start. Grant mic permission when prompted.
+
+**Only `http://localhost:*` origins work against the hosted API** —
+`sable-api`'s CORS policy does not yet allow arbitrary origins.
 
-**Only `http://localhost:*` origins work in v0** — `sable-api`'s CORS policy
-does not yet allow arbitrary origins. See the v0 spec at
-`docs/superpowers/specs/2026-04-07-sdk-voice-integration-design.md` for the
-deferred per-org allowed-origins work.
+### Releasing
 
-## Known limitations (v0)
+Tagging `sdk-core-v<x.y.z>` triggers
+`.github/workflows/release-sdk-core.yml`, which:
 
-- Voice only. No DOM tools, no actions, no wireframe.
-- Bundle is ~1 MB unminified because `livekit-client` is inlined into the IIFE.
-- No session persistence across navigations.
-- No push-to-talk; the mic stays open for the whole session.
-- Errors from `start()` propagate; callers must catch and display them.
+1. Runs typecheck + tests + `bun run build`.
+2. Publishes to npm with OIDC trusted-publisher provenance.
+3. Stages `dist/sable.iife.js` + `dist/sable-core.mjs` under `/v<version>/`,
+   `/v1/`, and `/latest/` via `infra/cdn/stage.sh`.
+4. Deploys the staged directory to Cloudflare Pages
+   (`sable-sdk-cdn` project, custom domain `sdk.withsable.com`).

package/dist/esm/index.js

@@ -2001,7 +2001,7 @@ async function publishCanvasAsVideoTrack(room, lib, canvas, fps) {
 var DEFAULT_FRAME_SOURCE = {
   type: "wireframe",
   rate: 2,
-  features: { includeImages: false }
+  features: { includeImages: true }
 };
 async function startVision(args) {
   const source = args.options.frameSource ?? DEFAULT_FRAME_SOURCE;
@@ -2027,7 +2027,7 @@ async function startVision(args) {
 }
 
 // src/version.ts
-var VERSION = "0.1.3";
+var VERSION = "0.1.4";
 
 // src/session/debug-panel.ts
 var DEBUG_PANEL_STATE_KEY = "sable:debug:panel";