@product7/product7-js 0.3.1 → 0.3.4

package/src/docs/framework-integrations.md

@@ -1,14 +1,14 @@
 # Framework Integrations
 
-Use this document to integrate `@product7/product7-js` in supported frontend frameworks.
+Use this guide to integrate `@product7/product7-js` in modern frontend frameworks.
 
-This guide includes:
+This guide covers:
 
 1. Next.js
 2. React
-3. Vue + Nuxt
+3. Vue and Nuxt
 4. Angular
-5. Svelte + SvelteKit
+5. Svelte and SvelteKit
 6. Astro
 
 ## Before You Start
@@ -19,173 +19,57 @@ Install the SDK:
 npm install @product7/product7-js
 ```
 
-Prepare your runtime values:
+Prepare runtime values:
 
-- `workspace` (required)
-- `boardName` (recommended for feedback button)
-- `metadata` (recommended for personalization and messenger)
+- `workspace` is required
+- `boardName` is recommended for feedback widgets
+- user identity should be passed to `identify()` after `init()`
 
-Example configuration:
+Recommended integration rules:
 
-```ts
-const sdkConfig = {
-	workspace: 'your-workspace',
-	boardName: 'feature-requests',
-	debug: false,
-	metadata: {
-		user_id: 'user_123',
-		email: 'user@example.com',
-		name: 'Jane Doe',
-		custom_fields: {
-			plan: 'pro',
-			role: 'admin',
-		},
-		company: {
-			id: 'company_123',
-			name: 'Acme Inc',
-		},
-	},
-};
-```
-
-Integration rules:
-
-- Run SDK initialization on the client side only.
+- Initialize on the client side only.
 - Always call `await sdk.init()` before creating widgets.
-- Prefer a single shared SDK instance per app session.
-- Destroy widgets and SDK on app teardown where applicable.
-
-## Framework-Specific Configuration
-
-Use framework-native environment variables so values stay deployment-safe.
+- Call `await sdk.identify(user)` after `init()` when you have a logged-in user.
+- Prefer one shared SDK instance per app session.
+- Destroy widgets and the SDK on teardown where appropriate.
 
-### Next.js
+### Shared Config Pattern
 
-- Use `NEXT_PUBLIC_*` for client-side values.
-- Build `metadata` from your auth/session payload.
-- When logged-in user changes, call `sdk.setMetadata(nextMetadata)`.
+Keep workspace-level SDK config separate from user identity:
 
 ```ts
 const sdkConfig = {
-	workspace: process.env.NEXT_PUBLIC_PRODUCT7_WORKSPACE!,
-	boardName: process.env.NEXT_PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
-	debug: process.env.NEXT_PUBLIC_PRODUCT7_DEBUG === 'true',
-	metadata: {
-		user_id: session.user.id,
-		email: session.user.email,
-		name: session.user.name,
-	},
-};
-```
-
-### React (Vite / CRA)
-
-- Vite: use `import.meta.env.VITE_*`.
-- CRA: use `process.env.REACT_APP_*`.
-- Keep config in one helper so all components use the same values.
-
-```ts
-const sdkConfig = {
-	workspace: import.meta.env.VITE_PRODUCT7_WORKSPACE,
-	boardName: import.meta.env.VITE_PRODUCT7_BOARD_ID || 'feature-requests',
-	debug: import.meta.env.DEV,
-	metadata: currentUser
-		? {
-				user_id: currentUser.id,
-				email: currentUser.email,
-				name: currentUser.name,
-			}
-		: undefined,
-};
-```
-
-### Vue + Nuxt
-
-- Vue (Vite): use `import.meta.env.VITE_*`.
-- Nuxt: use `useRuntimeConfig().public`.
-- In Nuxt, initialize in a `.client` plugin and expose SDK through `provide`.
-
-```ts
-// Nuxt example
-const runtime = useRuntimeConfig();
-const sdkConfig = {
-	workspace: runtime.public.product7Workspace,
-	boardName: runtime.public.product7BoardId || 'feature-requests',
-	debug: runtime.public.product7Debug === 'true',
-	metadata,
+	workspace: 'your-workspace',
+	boardName: 'feature-requests',
+	debug: false,
 };
-```
 
-### Angular
-
-- Keep SDK values in `environment.ts` and `environment.prod.ts`.
-- Map app auth user into `metadata` in your singleton service.
-
-```ts
-const sdkConfig = {
-	workspace: environment.product7.workspace,
-	boardName: environment.product7.boardName || 'feature-requests',
-	debug: !environment.production,
-	metadata: {
-		user_id: user.id,
-		email: user.email,
-		name: user.fullName,
+const identifyPayload = {
+	user_id: currentUser.id,
+	email: currentUser.email,
+	name: currentUser.name,
+	custom_fields: {
+		plan: currentUser.plan,
+		role: currentUser.role,
 	},
 };
 ```
 
-### Svelte + SvelteKit
-
-- Svelte: use `import.meta.env.VITE_*`.
-- SvelteKit: use `$env/static/public` (or `$env/dynamic/public`) values.
-- Reuse one config builder in `+layout.svelte` to avoid repeated setup.
-
-```ts
-const sdkConfig = {
-	workspace: PUBLIC_PRODUCT7_WORKSPACE,
-	boardName: PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
-	debug: PUBLIC_PRODUCT7_DEBUG === 'true',
-	metadata,
-};
-```
-
-### Astro
-
-- Expose client-safe values with `PUBLIC_*`.
-- Run SDK code only in client-loaded components (`client:load` / `client:visible`).
-
-```ts
-const sdkConfig = {
-	workspace: import.meta.env.PUBLIC_PRODUCT7_WORKSPACE,
-	boardName: import.meta.env.PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
-	debug: import.meta.env.PUBLIC_PRODUCT7_DEBUG === 'true',
-	metadata,
-};
-```
-
-### Optional SDK Keys You Can Add Per Framework
-
-- `apiUrl`: custom API endpoint override.
-- `env`: force `'staging'` or `'production'`.
-- `mock`: enable mock responses for local development.
-- `theme`: default `'light'` or `'dark'`.
-- `position`: default widget position.
+---
 
-## 1) Next.js
+## 1. Next.js
 
 ### App Router
 
-Create a client provider:
-
 `app/providers.tsx`
 
 ```tsx
 'use client';
 
 import { useEffect, useRef } from 'react';
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
-export function FeedbackProvider() {
+export function Product7Provider() {
 	const sdkRef = useRef<any>(null);
 	const widgetRef = useRef<any>(null);
 
@@ -193,24 +77,26 @@ export function FeedbackProvider() {
 		let cancelled = false;
 
 		(async () => {
-			const sdk = Product7.create({
-				workspace: 'your-workspace',
-				boardName: 'feature-requests',
-				metadata: {
-					user_id: 'user_123',
-					email: 'user@example.com',
-					name: 'Jane Doe',
-				},
+			const sdk = new Product7({
+				workspace: process.env.NEXT_PUBLIC_PRODUCT7_WORKSPACE!,
+				boardName:
+					process.env.NEXT_PUBLIC_PRODUCT7_BOARD_ID || 'feature-requests',
 			});
 
 			await sdk.init();
+			await sdk.identify({
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'Jane Doe',
+			});
+
 			if (cancelled) {
 				sdk.destroy();
 				return;
 			}
 
 			sdkRef.current = sdk;
-			widgetRef.current = sdk.createWidget('button', {
+			widgetRef.current = sdk.createFeedbackWidget({
 				position: 'bottom-right',
 			});
 			widgetRef.current.mount();
@@ -227,12 +113,10 @@ export function FeedbackProvider() {
 }
 ```
 
-Render provider in layout:
-
 `app/layout.tsx`
 
 ```tsx
-import { FeedbackProvider } from './providers';
+import { Product7Provider } from './providers';
 
 export default function RootLayout({
 	children,
@@ -242,7 +126,7 @@ export default function RootLayout({
 	return (
 		<html lang="en">
 			<body>
-				<FeedbackProvider />
+				<Product7Provider />
 				{children}
 			</body>
 		</html>
@@ -257,20 +141,27 @@ export default function RootLayout({
 ```tsx
 import type { AppProps } from 'next/app';
 import { useEffect } from 'react';
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
 export default function App({ Component, pageProps }: AppProps) {
 	useEffect(() => {
-		const sdk = Product7.create({
-			workspace: 'your-workspace',
+		const sdk = new Product7({
+			workspace: process.env.NEXT_PUBLIC_PRODUCT7_WORKSPACE!,
 			boardName: 'feature-requests',
-			metadata: { user_id: 'user_123', email: 'user@example.com' },
 		});
 
 		let widget: any;
+
 		(async () => {
 			await sdk.init();
-			widget = sdk.createWidget('button', { position: 'bottom-right' });
+			await sdk.identify({
+				user_id: 'user_123',
+				email: 'user@example.com',
+			});
+
+			widget = sdk.createFeedbackWidget({
+				position: 'bottom-right',
+			});
 			widget.mount();
 		})();
 
@@ -284,42 +175,51 @@ export default function App({ Component, pageProps }: AppProps) {
 }
 ```
 
-## 2) React
+---
+
+## 2. React
 
 `src/App.tsx`
 
 ```tsx
 import { useEffect, useRef } from 'react';
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
 export default function App() {
 	const sdkRef = useRef<any>(null);
+	const widgetRef = useRef<any>(null);
 
 	useEffect(() => {
-		let widget: any;
+		let disposed = false;
 
 		(async () => {
-			const sdk = Product7.create({
-				workspace: 'your-workspace',
-				boardName: 'feature-requests',
-				metadata: {
-					user_id: 'user_123',
-					email: 'user@example.com',
-					name: 'Jane Doe',
-				},
+			const sdk = new Product7({
+				workspace: import.meta.env.VITE_PRODUCT7_WORKSPACE,
+				boardName: import.meta.env.VITE_PRODUCT7_BOARD_ID || 'feature-requests',
 			});
 
 			await sdk.init();
-			sdkRef.current = sdk;
+			await sdk.identify({
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'Jane Doe',
+			});
 
-			widget = sdk.createWidget('button', {
+			if (disposed) {
+				sdk.destroy();
+				return;
+			}
+
+			sdkRef.current = sdk;
+			widgetRef.current = sdk.createFeedbackWidget({
 				position: 'bottom-right',
 			});
-			widget.mount();
+			widgetRef.current.mount();
 		})();
 
 		return () => {
-			widget?.destroy();
+			disposed = true;
+			widgetRef.current?.destroy();
 			sdkRef.current?.destroy();
 		};
 	}, []);
@@ -328,7 +228,9 @@ export default function App() {
 }
 ```
 
-## 3) Vue + Nuxt
+---
+
+## 3. Vue and Nuxt
 
 ### Vue
 
@@ -337,24 +239,25 @@ export default function App() {
 ```vue
 <script setup lang="ts">
 	import { onMounted, onUnmounted, ref } from 'vue';
-	import Product7 from '@product7/product7-js';
+	import { Product7 } from '@product7/product7-js';
 
 	const sdk = ref<any>(null);
 	const widget = ref<any>(null);
 
 	onMounted(async () => {
-		sdk.value = Product7.create({
-			workspace: 'your-workspace',
+		sdk.value = new Product7({
+			workspace: import.meta.env.VITE_PRODUCT7_WORKSPACE,
 			boardName: 'feature-requests',
-			metadata: {
-				user_id: 'user_123',
-				email: 'user@example.com',
-				name: 'Jane Doe',
-			},
 		});
 
 		await sdk.value.init();
-		widget.value = sdk.value.createWidget('button', {
+		await sdk.value.identify({
+			user_id: 'user_123',
+			email: 'user@example.com',
+			name: 'Jane Doe',
+		});
+
+		widget.value = sdk.value.createFeedbackWidget({
 			position: 'bottom-right',
 		});
 		widget.value.mount();
@@ -365,30 +268,21 @@ export default function App() {
 		sdk.value?.destroy();
 	});
 </script>
-
-<template>
-	<div>My App</div>
-</template>
 ```
 
-### Nuxt
+### Nuxt Plugin
 
-Create a client plugin:
-
-`plugins/feedback.client.ts`
+`plugins/product7.client.ts`
 
 ```ts
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
 export default defineNuxtPlugin(async () => {
-	const sdk = Product7.create({
-		workspace: 'your-workspace',
-		boardName: 'feature-requests',
-		metadata: {
-			user_id: 'user_123',
-			email: 'user@example.com',
-			name: 'Jane Doe',
-		},
+	const runtime = useRuntimeConfig();
+
+	const sdk = new Product7({
+		workspace: runtime.public.product7Workspace,
+		boardName: runtime.public.product7BoardId || 'feature-requests',
 	});
 
 	await sdk.init();
@@ -401,104 +295,125 @@ export default defineNuxtPlugin(async () => {
 });
 ```
 
-Mount a widget in `app.vue` (or a layout):
+When your auth state is ready, identify the user:
 
-```vue
-<script setup lang="ts">
-	const { $product7 } = useNuxtApp();
-	let widget: any;
+```ts
+const { $product7 } = useNuxtApp();
 
-	onMounted(() => {
-		widget = $product7.createWidget('button', {
-			position: 'bottom-right',
-			boardName: 'feature-requests',
+await $product7.identify({
+	user_id: user.id,
+	email: user.email,
+	name: user.name,
+});
+```
+
+### Nuxt Headless Composable
+
+`composables/useFeedbackWidget.ts`
+
+```ts
+import { onMounted, onUnmounted, ref } from 'vue';
+
+interface FeedbackWidgetOptions {
+	boardName?: string;
+	position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+	headless?: boolean;
+}
+
+export function useFeedbackWidget(options: FeedbackWidgetOptions = {}) {
+	const widget = ref<any>(null);
+	const isReady = ref(false);
+
+	onMounted(async () => {
+		const { $product7 } = useNuxtApp();
+
+		widget.value = $product7.createFeedbackWidget({
+			headless: true,
+			...options,
 		});
-		widget.mount();
+		widget.value.mount();
+		isReady.value = true;
 	});
 
-	onBeforeUnmount(() => {
-		widget?.destroy();
+	onUnmounted(() => {
+		widget.value?.destroy();
 	});
-</script>
+
+	return {
+		isReady,
+		open: () => widget.value?.open(),
+		close: () => widget.value?.close(),
+		toggle: () => widget.value?.toggle(),
+	};
+}
 ```
 
-For larger Nuxt apps, use a Pinia store with `isReady` checks to avoid duplicate widget creation.
+Usage:
+
+```vue
+<script setup>
+	const { open, isReady } = useFeedbackWidget({
+		boardName: 'feature-requests',
+	});
+</script>
+
+<template>
+	<button :disabled="!isReady" @click="open">Leave feedback</button>
+</template>
+```
 
-## 4) Angular
+---
 
-Create a singleton service:
+## 4. Angular
 
 `feedback.service.ts`
 
 ```ts
 import { Injectable } from '@angular/core';
-import Product7 from '@product7/product7-js';
+import { Product7 } from '@product7/product7-js';
 
 @Injectable({ providedIn: 'root' })
 export class FeedbackService {
 	private sdk: any = null;
-	private buttonWidget: any = null;
+	private feedbackWidget: any = null;
 
-	async init() {
+	async init(user: { id: string; email: string; name: string }) {
 		if (this.sdk) return;
 
-		this.sdk = Product7.create({
+		this.sdk = new Product7({
 			workspace: 'your-workspace',
 			boardName: 'feature-requests',
-			metadata: {
-				user_id: 'user_123',
-				email: 'user@example.com',
-				name: 'Jane Doe',
-			},
 		});
 
 		await this.sdk.init();
+		await this.sdk.identify({
+			user_id: user.id,
+			email: user.email,
+			name: user.name,
+		});
 	}
 
-	mountButton() {
-		if (!this.sdk || this.buttonWidget) return;
-		this.buttonWidget = this.sdk.createWidget('button', {
+	mountFeedback() {
+		if (!this.sdk || this.feedbackWidget) return;
+
+		this.feedbackWidget = this.sdk.createFeedbackWidget({
 			position: 'bottom-right',
 		});
-		this.buttonWidget.mount();
+		this.feedbackWidget.mount();
 	}
 
 	destroy() {
-		this.buttonWidget?.destroy();
-		this.buttonWidget = null;
+		this.feedbackWidget?.destroy();
+		this.feedbackWidget = null;
 		this.sdk?.destroy();
 		this.sdk = null;
 	}
 }
 ```
 
-Use it in the root component:
-
-`app.component.ts`
-
-```ts
-import { Component, OnDestroy, OnInit } from '@angular/core';
-import { FeedbackService } from './feedback.service';
-
-@Component({
-	selector: 'app-root',
-	template: '<router-outlet></router-outlet>',
-})
-export class AppComponent implements OnInit, OnDestroy {
-	constructor(private feedback: FeedbackService) {}
-
-	async ngOnInit() {
-		await this.feedback.init();
-		this.feedback.mountButton();
-	}
-
-	ngOnDestroy() {
-		this.feedback.destroy();
-	}
-}
-```
+---
 
-## 5) Svelte + SvelteKit
+## 5. Svelte and SvelteKit
 
 ### Svelte
 
@@ -507,7 +422,7 @@ export class AppComponent implements OnInit, OnDestroy {
 ```svelte
 <script lang="ts">
 	import { onMount } from 'svelte';
-	import Product7 from '@product7/product7-js';
+	import { Product7 } from '@product7/product7-js';
 
 	let sdk: any = null;
 	let widget: any = null;
@@ -516,20 +431,23 @@ export class AppComponent implements OnInit, OnDestroy {
 		let disposed = false;
 
 		(async () => {
-			sdk = Product7.create({
+			sdk = new Product7({
 				workspace: 'your-workspace',
 				boardName: 'feature-requests',
-				metadata: {
-					user_id: 'user_123',
-					email: 'user@example.com',
-					name: 'Jane Doe',
-				},
 			});
 
 			await sdk.init();
+			await sdk.identify({
+				user_id: 'user_123',
+				email: 'user@example.com',
+				name: 'Jane Doe',
+			});
+
 			if (disposed) return;
 
-			widget = sdk.createWidget('button', { position: 'bottom-right' });
+			widget = sdk.createFeedbackWidget({
+				position: 'bottom-right',
+			});
 			widget.mount();
 		})();
 
@@ -540,8 +458,6 @@ export class AppComponent implements OnInit, OnDestroy {
 		};
 	});
 </script>
-
-<main>My App</main>
 ```
 
 ### SvelteKit
@@ -552,7 +468,7 @@ export class AppComponent implements OnInit, OnDestroy {
 <script lang="ts">
 	import { browser } from '$app/environment';
 	import { onMount } from 'svelte';
-	import Product7 from '@product7/product7-js';
+	import { Product7 } from '@product7/product7-js';
 
 	let sdk: any;
 	let widget: any;
@@ -561,17 +477,20 @@ export class AppComponent implements OnInit, OnDestroy {
 		if (!browser) return;
 
 		(async () => {
-			sdk = Product7.create({
+			sdk = new Product7({
 				workspace: 'your-workspace',
 				boardName: 'feature-requests',
-				metadata: {
-					user_id: 'user_123',
-					email: 'user@example.com',
-				},
 			});
 
 			await sdk.init();
-			widget = sdk.createWidget('button', { position: 'bottom-right' });
+			await sdk.identify({
+				user_id: 'user_123',
+				email: 'user@example.com',
+			});
+
+			widget = sdk.createFeedbackWidget({
+				position: 'bottom-right',
+			});
 			widget.mount();
 		})();
 
@@ -581,134 +500,93 @@ export class AppComponent implements OnInit, OnDestroy {
 		};
 	});
 </script>
-
-<slot />
 ```
 
-## 6) Astro
+---
+
+## 6. Astro
 
-Astro renders on the server by default, so initialize the SDK from a client-loaded component.
+Astro renders on the server by default, so initialize Product7 from a client-loaded component.
 
-`src/components/FeedbackWidget.astro`
+`src/components/Product7Widget.astro`
 
 ```astro
 <script>
-	import Product7 from '@product7/product7-js';
+	import { Product7 } from '@product7/product7-js';
 
 	let sdk;
 	let widget;
 
 	(async () => {
-		sdk = Product7.create({
+		sdk = new Product7({
 			workspace: 'your-workspace',
 			boardName: 'feature-requests',
-			metadata: {
-				user_id: 'user_123',
-				email: 'user@example.com',
-				name: 'Jane Doe',
-			},
 		});
 
 		await sdk.init();
-		widget = sdk.createWidget('button', { position: 'bottom-right' });
+		await sdk.identify({
+			user_id: 'user_123',
+			email: 'user@example.com',
+			name: 'Jane Doe',
+		});
+
+		widget = sdk.createFeedbackWidget({
+			position: 'bottom-right',
+		});
 		widget.mount();
 	})();
 </script>
 ```
 
-Use the component in a page:
-
-```astro
----
-import FeedbackWidget from '../components/FeedbackWidget.astro';
 ---
 
-<html lang="en">
-	<body>
-		<FeedbackWidget client:load />
-	</body>
-</html>
-```
-
-## Add More Widgets (Any Framework)
+## Adding More Widgets
 
-You can create survey, messenger, and changelog widgets from the same SDK instance:
+Use the same SDK instance for feedback, survey, messenger, and changelog.
 
 ```ts
-const survey = sdk.createWidget('survey', {
+const feedback = sdk.createFeedbackWidget({
+	headless: true,
+	boardName: 'feature-requests',
+});
+feedback.mount();
+
+const survey = sdk.createSurveyWidget({
 	surveyType: 'nps',
 	position: 'center',
-	theme: 'light',
-	description:
-		'To what extent do you agree or disagree that our tools support the work you do?',
 	ratingScale: 5,
-	showTitle: false,
-	showDescription: true,
-	showFeedbackInput: false,
-	showSubmitButton: false,
-	autoSubmitOnSelect: true,
-	lowLabel: 'Strongly Disagree',
-	highLabel: 'Strongly Agree',
-	onSubmit: (response) => {
-		console.log('Survey submitted:', response);
-		// Optional: send to analytics
-		// analytics.track('survey_submitted', { type: response.type, score: response.score });
-	},
-	onDismiss: () => {
-		console.log('Survey dismissed');
-	},
+	showSubmitButton: true,
 });
-survey.show();
-// survey.hide();
-// survey.destroy();
+survey.mount();
+survey.open();
 
-const messenger = sdk.createWidget('messenger', {
+const messenger = sdk.createMessengerWidget({
 	position: 'bottom-right',
-	theme: 'light',
 	teamName: 'Support Team',
-	welcomeMessage: 'How can we help?',
 	enableHelp: true,
 	enableChangelog: true,
-	primaryColor: '#155EEF',
-	onSendMessage: (conversationId, message) => {
-		console.log('Message sent:', conversationId, message);
-	},
-	onArticleClick: (article) => {
-		console.log('Article clicked:', article);
-	},
-	onChangelogClick: (item) => {
-		console.log('Changelog clicked:', item);
-	},
 });
 messenger.mount();
-// messenger.open();
-// messenger.navigateTo('help');
-// messenger.close();
 
-const changelog = sdk.createWidget('changelog', {
+const changelog = sdk.createChangelogWidget({
 	position: 'bottom-left',
-	theme: 'light',
-	showBackdrop: true,
 	triggerText: "What's New",
 	showBadge: true,
-	title: "What's New",
-	viewButtonText: 'View Update',
-	onViewUpdate: (item) => {
-		console.log('Viewed changelog item:', item);
-	},
 });
 changelog.mount();
-// changelog.openSidebar();
-// changelog.closeSidebar();
 ```
 
+---
+
 ## Troubleshooting
 
 - `SDK must be initialized before creating widgets`
-  Call `await sdk.init()` before any `createWidget(...)` call.
+  Call `await sdk.init()` before any widget factory method.
 - Widget not visible
-  Make sure you call `widget.mount()` for mounted widget types.
+  Make sure you call `widget.mount()` for mountable widgets.
 - `window is not defined` or `document is not defined`
-  Move SDK code to client-only lifecycle hooks/components.
+  Move SDK code to client-only lifecycle hooks or client-only components.
 - Duplicate widget instances
-  Cache widget references and guard against double mount.
+  Cache widget references and avoid remounting in repeated renders.
+- Messenger shows the launcher when you want only programmatic control
+  Use `headless: true` when creating the messenger widget.