@skippr/live-agent-sdk 0.105.0 → 0.106.0

package/README.md

@@ -230,6 +230,42 @@ function App() {
 - **Close** — call `disconnect()` to end the current session.
 - **Show the right label** — use `isConnected` and `isStarting` to switch your button between start, connecting, and end states.
 
+### Splash screen
+
+When your workspace selects the `Template` launcher style under Appearance, the SDK shows a pre-session card instead of the launcher bubble: what the agent can do, the microphone and screen-access rows it needs, and a Start / Continue button. Script-tag embeds get it as a centred overlay automatically. In React you place it yourself, anywhere inside `<LiveAgent>`:
+
+```tsx
+import { useState } from 'react';
+import { LiveAgent, SplashScreen } from '@skippr/live-agent-sdk';
+
+function App() {
+  const [showSplash, setShowSplash] = useState(true);
+
+  return (
+    <LiveAgent appKey="pk_live_your_key">
+      {showSplash && (
+        <aside className="w-[380px] p-4">
+          <SplashScreen onDismiss={() => setShowSplash(false)} />
+        </aside>
+      )}
+    </LiveAgent>
+  );
+}
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string` | Applied to the component's own light-DOM element. This is the placement and sizing lever — the card fills whatever slot you give it. |
+| `onDismiss` | `() => void` | Called when the user dismisses the splash, via either the close button or "Skip for now". |
+
+- **You own unmounting.** `<SplashScreen>` renders nothing once it no longer applies — the user dismissed it, a session is running, or your workspace has the splash turned off — but it stays mounted until you remove it.
+- **Conditionally render your own wrapper too.** A styled slot (padding, border, grid cell) survives as an empty box when the card stops rendering, as in the example above.
+- **Session start needs no callback.** `useLiveAgent()` already reports `isStarting` / `isConnected`, so read the session from there rather than mirroring it into your own state.
+- **Render exactly one.** Each instance keeps its own microphone and screen state; the SDK warns in the console when a second one mounts, or when the splash is enabled and none is placed.
+- **Bring it back after a skip.** Dismissal lasts for the page load, so the card returns on the next navigation. On a single-page app, call `reopenSplash()` from `useLiveAgent()` — wire it to a "Start guided tour" link or a help-menu item. Skipping never reveals a launcher bubble; the host owns when the card comes back.
+- **Want the centred treatment instead?** Render `<SplashOverlay>` (also exported) for the same backdrop-and-centred card the script-tag embed gets; use the bare `<SplashScreen>` when you want it inline in your own layout. It takes optional `width` (px) and `maxHeight` (% of viewport height) to override the card size your workspace configured; both are clamped to the supported range.
+- **Check the config before you build around it.** `useLiveAgent()` exposes `isSplashConfigured` so you can pick between the splash and your own launcher; it reflects the workspace setting only, not whether the card is on screen right now.
+
 ## API Reference
 
 ### `<LiveAgent>`
@@ -278,6 +314,7 @@ Hook for accessing session state and panel controls. Must be called within `<Liv
 | `activeModule` | `Module \| null` | The module the current session was started with |
 | `isLoadingModules` | `boolean` | Whether the picker list is being fetched |
 | `modulesError` | `string \| null` | Error from fetching the picker list, if any |
+| `isSplashConfigured` | `boolean` | Whether your workspace uses the `Template` launcher style, which turns the splash screen on. Configuration only — it does not tell you whether the splash is currently on screen |
 
 ```ts
 interface Module {
@@ -306,6 +343,7 @@ interface Module {
 | `setPosition` | `(position: 'left' \| 'right') => void` | Change widget position |
 | `selectModule` | `(id: string) => void` | Start a session with the module of the given id |
 | `refetchModules` | `() => Promise<void>` | Refetch the picker list |
+| `reopenSplash` | `() => void` | Show the splash screen again after the user skipped it. No-op while a session is running or when your workspace has the splash turned off |
 
 ### Additional Hooks