@livelayer/react 0.2.5 → 0.3.0

package/README.md

@@ -1,58 +1,289 @@
 # @livelayer/react
 
-React component wrapper for the LiveLayer agent widget.
+Drop-in voice/video AI agent widget for React apps. The full-fidelity widget that powers [app.livelayer.studio](https://app.livelayer.studio), packaged for direct mount in your app's DOM (no iframe).
 
-## Installation
+## Quickstart (5 minutes)
+
+Three files, one published agent, working voice nav.
+
+**1. Install**
 
 ```bash
 npm install @livelayer/react
+# or pnpm add @livelayer/react / yarn add @livelayer/react
 ```
 
-## Usage
+**2. Get an agent ID** — go to [app.livelayer.studio](https://app.livelayer.studio), publish an agent, copy its ID (looks like `cmobfeluv000bju04ct1cqdb0`).
+
+**3. Mount the widget** (Next.js App Router shown — works the same way in any React app):
 
 ```tsx
-import { LiveLayerWidget } from "@livelayer/react";
+"use client";
+
+import { AvatarWidget } from "@livelayer/react";
+import "@livelayer/react/styles.css";
+import { useRouter, usePathname } from "next/navigation";
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  const pathname = usePathname();
 
-function App() {
   return (
-    <LiveLayerWidget
-      agentId="your_agent_id"
-      onAgentEvent={(e) => console.log(e.eventName, e.data)}
-    />
+    <>
+      {children}
+      <AvatarWidget
+        agentId="cmobfeluv000bju04ct1cqdb0"
+        pathname={pathname}
+        onNavigate={(href) => router.push(href)}
+        hideOn={["/privacy", "/terms", "/legal/*"]}
+      />
+    </>
   );
 }
 ```
 
-## Props
+That's it. The widget docks bottom-right, the agent can navigate users to other pages by voice, and it stays out of the way on legal pages. The LiveKit session survives every SPA route change.
 
-| Prop            | Type                                    | Required | Description                                         |
-| --------------- | --------------------------------------- | -------- | --------------------------------------------------- |
-| `agentId`       | `string`                                | Yes      | The published agent ID to connect to                |
-| `mode`          | `"WIDGET" \| "EMBEDDED"`                | No       | Override the experience mode from the agent config  |
-| `onAgentEvent`  | `(event: AgentEventDetail) => void`     | No       | Callback fired when the agent emits a data channel event |
-| `className`     | `string`                                | No       | CSS class name on the wrapper div                   |
-| `style`         | `React.CSSProperties`                   | No       | Inline styles on the wrapper div                    |
+> **Common gotcha:** if the widget renders unstyled, check that you imported `@livelayer/react/styles.css`. It's a separate import to give consumers the option to scope styles.
 
-### AgentEventDetail
+---
 
-```ts
-interface AgentEventDetail {
-  eventName: string;
-  data: Record<string, unknown>;
+## Recipes
+
+### 1. Voice navigation in Next.js / React Router
+
+Pass your router into `onNavigate`. When the agent emits a `navigate` command, the widget calls your callback. The session never reloads.
+
+```tsx
+// Next.js App Router
+import { useRouter } from "next/navigation";
+const router = useRouter();
+<AvatarWidget agentId="..." onNavigate={(href) => router.push(href)} />
+
+// React Router v6
+import { useNavigate } from "react-router-dom";
+const navigate = useNavigate();
+<AvatarWidget agentId="..." onNavigate={navigate} />
+```
+
+If you don't pass `onNavigate`, the widget falls back to (1) clicking a matching `<a href="...">` in the DOM (Next.js `<Link>` and React Router `<Link>` both intercept these), then (2) `history.pushState` for plain HTML pages. **It never uses `window.location` — that's a hard reload that would kill the call.**
+
+You also need to register a `navigate` tool on your agent so it can emit the command. In your agent's tool schema:
+
+```json
+{
+  "name": "navigate",
+  "description": "Take the user to a different page on this site.",
+  "parameters": {
+    "type": "object",
+    "properties": { "href": { "type": "string" } },
+    "required": ["href"]
+  }
 }
 ```
 
-## Peer Dependencies
+When the LLM calls `navigate({ href: "/pricing" })`, your agent server publishes `{ type: "navigate", href: "/pricing" }` on the data channel. The widget handles the rest.
+
+### 2. Hide on sensitive routes
+
+```tsx
+<AvatarWidget
+  agentId="..."
+  pathname={usePathname()}
+  hideOn={["/privacy", "/terms", "/cookies", "/legal/**"]}
+/>
+```
+
+Glob rules:
+- `*` matches one path segment: `/admin/*` → `/admin/users` but not `/admin/users/edit`
+- `**` matches any depth: `/admin/**` → `/admin`, `/admin/users`, `/admin/users/edit`
+- A `RegExp` or function works too: `hideOn={[/^\/blog\/draft-.+$/, (p) => p.startsWith("/internal")]}`
+
+The LiveKit session **stays alive** while hidden. When the user navigates back to an allowed route, the call resumes seamlessly.
+
+`showOn` is the inverse — restrict to a whitelist. `hideOn` wins on collisions.
+
+### 3. Let the agent see the page
+
+When the agent asks "what's the user looking at?", the widget walks the DOM and sends back a structured snapshot. You don't need to do anything for this to work, but you can guide it with `<LiveLayerRegion>`:
+
+```tsx
+import { LiveLayerRegion } from "@livelayer/react";
+
+<LiveLayerRegion id="pricing" intent="show pricing tiers">
+  <PricingTable />
+</LiveLayerRegion>
+```
+
+This renders a `<div data-ll-region="pricing" data-ll-intent="show pricing tiers">` that the page-context extractor surfaces with priority. The `intent` is author-language for the agent.
 
-This package requires React 18 or later:
+To register the agent-side tool:
 
 ```json
 {
-  "react": ">=18.0.0",
-  "react-dom": ">=18.0.0"
+  "name": "getPageContext",
+  "description": "Snapshot of what the user is currently looking at — useful when they ask 'what is this' or 'show me the X'.",
+  "parameters": { "type": "object", "properties": {} }
 }
 ```
 
+When the LLM calls it, your agent publishes `{ type: "request_page_context" }` and waits for the widget's `{ type: "page_context", context: {...} }` response (typically <100ms).
+
+You can override the default extractor entirely:
+
+```tsx
+<AvatarWidget
+  getPageContext={() => ({
+    url: window.location.href,
+    pathname: window.location.pathname,
+    title: document.title,
+    regions: [{ id: "cart", text: cartSummary }],
+    visibleText: "",
+    visibleLinks: [],
+    visibleFields: [],
+  })}
+/>
+```
+
+Or attach extra app state without replacing the walker:
+
+```tsx
+<AvatarWidget
+  pageContextExtras={{ userId: user.id, cartItemCount: items.length }}
+/>
+```
+
+### 4. Persist the session across pages (multi-page apps)
+
+For SPAs (Next.js, Remix, React Router), mount the widget at the app root and the session survives route changes automatically. For multi-page apps where the entire React tree unmounts, use `controlledSession` to own the LiveKit Room yourself and keep it alive across reloads. See [the `ControlledSession` interface](src/AvatarWidget.tsx) for the contract.
+
+### 5. Custom branding
+
+```tsx
+<AvatarWidget
+  branding={{
+    primaryColor: "#0ea5e9",
+    accentColor: "#f59e0b",
+    productName: "Acme Concierge",
+    logoUrl: "/logo.png",
+  }}
+/>
+```
+
+---
+
+## API reference
+
+### `<AvatarWidget>` (primary)
+
+All props are optional except `agentId`.
+
+| Prop | Type | Description |
+|---|---|---|
+| `agentId` | `string` | **Required.** The published agent ID. |
+| `apiKey` | `string` | API key for cross-origin auth. Required if your agent isn't public. |
+| `baseUrl` | `string` | Base URL of the LiveLayer API. Defaults to `https://app.livelayer.studio`. |
+| `pathname` | `string` | Current pathname. **Required for Next.js App Router and React Router v6+.** Pass `usePathname()` / `useLocation().pathname`. |
+| `showOn` | `RoutePattern[]` | Render only on matching paths. |
+| `hideOn` | `RoutePattern[]` | Never render on matching paths. Wins over `showOn`. |
+| `onNavigate` | `(href: string) => void` | Called on agent `navigate` command. Wire to your router. |
+| `onScrollToSelector` | `(sel, behavior?) => void` | Called on agent `scroll_to` command. Default: `scrollIntoView({ behavior: "smooth" })`. |
+| `getPageContext` | `() => PageContext \| Promise<PageContext>` | Override the default DOM walker. |
+| `pageContextExtras` | `Record<string, unknown>` | Extra app state attached to every page context snapshot. |
+| `position` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "custom"` | Where the widget docks. Defaults to `"bottom-right"`. |
+| `defaultDisplayMode` | `"hidden" \| "minimized" \| "expanded"` | Initial display mode. |
+| `branding` | `BrandingConfig` | Colors, product name, logo. |
+| `teamMembers` | `TeamMember[]` | Multi-agent picker. |
+| `controlledSession` | `ControlledSession` | Bring-your-own LiveKit Room. |
+| `onAgentCommand` | `(cmd) => void` | Receive non-universal data-channel commands. |
+| `onAgentEvent` | `(e) => void` | Receive ALL data-channel events (including the universal ones). |
+
+### `<LiveLayerRegion>` (page-context primitive)
+
+```tsx
+<LiveLayerRegion id="pricing" intent="show pricing tiers" as="section">
+  ...
+</LiveLayerRegion>
+```
+
+Renders a wrapper element with `data-ll-region` + `data-ll-intent` that the page-context extractor prioritizes.
+
+### Hooks (power users)
+
+`useLiveKitSession`, `useDisplayMode`, `useAgentInfo`, `usePathname`, `useRouteMatch`, `useAudioLevel`, `useMicrophoneState`, `useCameraState`, `useScreenShareState`, `useMediaDevices`, `useTranscript`. All exported from the package root.
+
+### Types
+
+`AvatarWidgetProps`, `RoutePattern`, `PageContext`, `AgentCommand`, `AgentEventDetail`, `TeamMember`, `BrandingConfig`, `WidgetPosition`, `DisplayMode`. All exported from the package root.
+
+---
+
+## Privacy
+
+The default page-context walker **never** extracts:
+
+- Form values (only labels and field types)
+- Inputs with `type="password"`
+- Inputs with `autocomplete="cc-*"` or `autocomplete="off"`
+- Elements (and their subtrees) with `data-ll-private="true"`
+- The widget itself (`.ll-widget`)
+
+To redact additional content:
+
+```tsx
+<div data-ll-private="true">
+  <UserBankAccount />
+</div>
+```
+
+Or override `getPageContext` entirely to control exactly what reaches the agent.
+
+---
+
+## Migrating from 0.2.x
+
+0.3.0 is **additive**. All existing 0.2.x code continues to work without changes.
+
+**Soft breaking — observability only:** the data-channel commands `navigate`, `scroll_to`, and `request_page_context` are now handled internally by the widget and no longer reach `onAgentCommand`. If you previously observed them via that callback (unlikely — they were never emitted in 0.2.x), switch to `onAgentEvent`, which still fires for every message.
+
+---
+
+## Errors and warnings
+
+Every console message from this package starts with `[LiveLayer]` and includes a doc URL. Examples:
+
+```
+[LiveLayer] Agent emitted "navigate" without href. Skipping.
+            Check your agent's tool schema.
+            See https://livelayer.studio/docs/errors/navigate-missing-href
+
+[LiveLayer] scroll_to: no element matched "#pricing-table".
+            The user may be on a different page.
+            See https://livelayer.studio/docs/errors/scroll-no-match
+```
+
+If you see one of these in production, the doc URL has the explanation and remediation.
+
+---
+
+## Legacy: `<LiveLayerWidget>`
+
+The thin web-component wrapper from 0.1.x is still exported for backwards compatibility. New apps should use `<AvatarWidget>`.
+
+```tsx
+import { LiveLayerWidget } from "@livelayer/react";
+<LiveLayerWidget agentId="..." />
+```
+
+---
+
+## Peer dependencies
+
+- `react` >= 18.0.0
+- `react-dom` >= 18.0.0
+
+No router peer dependency. Works with Next.js App Router, Next.js Pages Router, React Router (any version), Remix, TanStack Router, or no router at all.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -3,11 +3,14 @@ import { AgentState } from '@livelayer/sdk';
 import { Component } from 'react';
 import { ConnectionState } from '@livelayer/sdk';
 import { CSSProperties } from 'react';
+import { ElementType } from 'react';
 import { ErrorInfo } from 'react';
 import { FC } from 'react';
+import { ForwardRefExoticComponent } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { LiveKitSession } from '@livelayer/sdk';
 import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
 import { Room } from 'livekit-client';
 import { SessionOptions } from '@livelayer/sdk';
 import { TranscriptEntry } from '@livelayer/sdk';
@@ -92,6 +95,52 @@ export declare interface AvatarWidgetProps {
     allowScreenShare?: boolean;
     allowTyping?: boolean;
     allowMic?: boolean;
+    /**
+     * Patterns where the widget MAY render. If set, widget renders ONLY on
+     * matching paths. See `RoutePattern` for accepted forms (string globs,
+     * RegExp, or function predicate). Mutually compatible with `hideOn`.
+     *
+     * Pass `pathname` alongside this prop in Next.js / React Router apps.
+     */
+    showOn?: RoutePattern[];
+    /**
+     * Patterns where the widget will NEVER render. Wins over showOn.
+     * Common safe defaults: `["/privacy", "/terms", "/legal/*"]`.
+     */
+    hideOn?: RoutePattern[];
+    /**
+     * Current pathname. REQUIRED for Next.js App Router and React Router v6+
+     * because their internal routers update before window.location does.
+     *
+     * @example
+     * import { usePathname } from "next/navigation";
+     * <AvatarWidget pathname={usePathname()} hideOn={["/privacy"]} />
+     */
+    pathname?: string;
+    /**
+     * Called when the agent emits a `navigate` command. Wire to your
+     * router. If omitted, the widget falls back to (1) clicking a
+     * matching anchor (so Next/RR Link interceptors fire) and then
+     * (2) `history.pushState` for plain HTML sites. `window.location`
+     * is NEVER used — that would trigger a full reload and kill the
+     * session.
+     */
+    onNavigate?: (href: string) => void;
+    /**
+     * Called when the agent emits a `scroll_to` command. Default:
+     * scrolls the matched element into view smoothly. Override to
+     * customize easing or skip the scroll entirely.
+     */
+    onScrollToSelector?: (selector: string, behavior?: "smooth" | "instant") => void;
+    /**
+     * Override the default DOM walker. Receives the consumer's
+     * `pageContextExtras` and returns a structured context for the
+     * agent. Useful for filtering sensitive content or prepending app
+     * state that's not in the DOM.
+     */
+    getPageContext?: (extras?: Record<string, unknown>) => PageContext | Promise<PageContext>;
+    /** Free-form metadata bag the agent should always know about. */
+    pageContextExtras?: Record<string, unknown>;
     onConnect?: () => void;
     onDisconnect?: () => void;
     onTranscript?: (entries: TranscriptEntry[]) => void;
@@ -137,6 +186,8 @@ export declare interface CameraStateHandle {
     clearError: () => void;
 }
 
+export declare function clearPageContextCache(): void;
+
 export { ConnectionState }
 
 /**
@@ -180,6 +231,15 @@ export declare class ErrorBoundary extends Component<Props, State> {
     render(): ReactNode;
 }
 
+declare interface ExtractOptions {
+    /** Override doc — for tests. */
+    doc?: Document;
+}
+
+export declare function extractPageContext(extras?: Record<string, unknown>, opts?: ExtractOptions): PageContext;
+
+export declare function getCachedPageContext(extras?: Record<string, unknown>, opts?: ExtractOptions): PageContext;
+
 export declare interface LegacyAgentEventDetail {
     eventName: string;
     data: Record<string, unknown>;
@@ -187,6 +247,22 @@ export declare interface LegacyAgentEventDetail {
 
 declare type LevelSubscriber = (level: number) => void;
 
+export declare const LiveLayerRegion: ForwardRefExoticComponent<LiveLayerRegionProps & RefAttributes<HTMLElement>>;
+
+export declare interface LiveLayerRegionProps {
+    /** Stable identifier for the region. Becomes `data-ll-region`. */
+    id: string;
+    /** One-line description of what the agent should know about this region. */
+    intent?: string;
+    /** Element to render. Defaults to "div". */
+    as?: ElementType;
+    /** Extra class name on the wrapper. */
+    className?: string;
+    /** Inline styles. */
+    style?: CSSProperties;
+    children: ReactNode;
+}
+
 /**
  * React component that renders a `<livelayer-widget>` custom element.
  *
@@ -220,6 +296,8 @@ export declare interface LiveLayerWidgetProps {
     style?: React.CSSProperties;
 }
 
+export declare function matchesPattern(pattern: RoutePattern, pathname: string): boolean;
+
 export declare interface MediaDevicesHandle {
     mics: MediaDeviceInfo[];
     cameras: MediaDeviceInfo[];
@@ -257,6 +335,42 @@ declare interface Options_2 {
     disablePersistence?: boolean;
 }
 
+/**
+ * Snapshot of what the user is currently looking at, sent to the agent in
+ * response to a `request_page_context` command.
+ *
+ * Form values, password inputs, and elements marked `data-ll-private="true"`
+ * are NEVER included. See README → Privacy.
+ */
+export declare interface PageContext {
+    /** Full URL at the moment the snapshot was taken. */
+    url: string;
+    /** document.title at snapshot time. */
+    title: string;
+    /** Pathname only (no host, no query, no hash). */
+    pathname: string;
+    /** Author-curated regions via <LiveLayerRegion> — agent should prefer these. */
+    regions: Array<{
+        id: string;
+        intent?: string;
+        text: string;
+    }>;
+    /** Visible content fallback — auto-extracted text from headings/paragraphs. */
+    visibleText: string;
+    /** Anchor hrefs visible in viewport, top-to-bottom, max 20. */
+    visibleLinks: Array<{
+        href: string;
+        text: string;
+    }>;
+    /** Form fields visible in viewport — labels and types only, never values. */
+    visibleFields: Array<{
+        label: string;
+        type: string;
+    }>;
+    /** Free-form metadata bag from the consumer's pageContextExtras prop. */
+    extras?: Record<string, unknown>;
+}
+
 declare interface Props {
     children: ReactNode;
     /** Callback fired when an error is caught. Useful for telemetry. */
@@ -265,6 +379,22 @@ declare interface Props {
     fallback?: ReactNode;
 }
 
+/**
+ * Pattern matched against the current pathname to decide if the widget
+ * renders.
+ *
+ * - `string` — exact match OR glob with `*` (one segment) and `**` (any depth)
+ * - `RegExp` — full regex flexibility
+ * - function — fully custom predicate
+ *
+ * Glob examples:
+ *   "/"               only the home route
+ *   "/admin/X"        /admin/foo but NOT /admin/foo/bar       (X = single star)
+ *   "/admin/XX"       /admin and any descendant               (XX = double star)
+ *   "/blog/X/comments" /blog/x/comments but not deeper paths   (X = single star)
+ */
+export declare type RoutePattern = string | RegExp | ((pathname: string) => boolean);
+
 export declare interface ScreenShareStateHandle {
     isEnabled: boolean;
     error: string | null;
@@ -275,6 +405,15 @@ export declare interface ScreenShareStateHandle {
     clearError: () => void;
 }
 
+/**
+ * Pure: should the widget render at this pathname?
+ *
+ * @param pathname  current path, or undefined if not yet known
+ * @param showOn    if set, restricts rendering to matching paths only
+ * @param hideOn    if set, blocks rendering on matching paths (wins)
+ */
+export declare function shouldRenderAtPath(pathname: string | undefined, showOn: RoutePattern[] | undefined, hideOn: RoutePattern[] | undefined): boolean;
+
 declare interface State {
     hasError: boolean;
     error: Error | null;
@@ -363,6 +502,15 @@ export declare function useMediaDevices(): MediaDevicesHandle;
 
 export declare function useMicrophoneState(): MicrophoneStateHandle;
 
+/**
+ * Returns the current pathname, reactive to SPA navigation.
+ * Pass `controlledPathname` to skip internal detection (recommended for
+ * Next.js App Router and React Router v6+ consumers).
+ */
+export declare function usePathname(controlledPathname?: string): string;
+
+export declare function useRouteMatch(pathname: string | undefined, showOn: RoutePattern[] | undefined, hideOn: RoutePattern[] | undefined): boolean;
+
 export declare function useScreenShareState(): ScreenShareStateHandle;
 
 export declare function useTranscript(): TranscriptHandle;