@clivly/chat-widget 0.3.0 → 0.5.0

package/dist/browser.cjs

@@ -2,21 +2,162 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react_dom_client = require("react-dom/client");
 let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/theme.ts
+const DARK_MEDIA_QUERY = "(prefers-color-scheme: dark)";
+/** The attribute set by next-themes, daisyUI, and most `data-*` theme setups. */
+const THEME_ATTRIBUTE = "data-theme";
+/** Attributes worth re-resolving on. Anything else on `<html>` is noise. */
+const OBSERVED_ATTRIBUTES = ["class", THEME_ATTRIBUTE];
+function isResolvedTheme(value) {
+	return value === "dark" || value === "light";
+}
+/**
+* The host's explicit signals, in precedence order: a `data-theme` attribute
+* beats a class, because a host that sets both is using the attribute as the
+* source of truth and the class as a styling convenience.
+*
+* Both conventions are checked for `light` as well as `dark`. A host that says
+* `class="light"` on an OS-dark machine means it, and the explicit signal
+* should win over the OS preference below it.
+*/
+function readHostTheme(root) {
+	const attribute = root.getAttribute(THEME_ATTRIBUTE);
+	if (isResolvedTheme(attribute)) return attribute;
+	if (root.classList.contains("dark")) return "dark";
+	if (root.classList.contains("light")) return "light";
+	return null;
+}
+function prefersDark(view) {
+	return view.matchMedia?.(DARK_MEDIA_QUERY).matches ?? false;
+}
+function defaultRoot() {
+	return typeof document === "undefined" ? null : document.documentElement;
+}
+function defaultView() {
+	return typeof window === "undefined" ? null : window;
+}
+/**
+* Resolve a requested theme to the one the widget should actually paint.
+*
+* Falls back to `light` when there is nothing to read — during SSR there is no
+* document, and guessing dark would flash the wrong palette on hydration for
+* the majority of pages.
+*/
+function resolveTheme(theme, { root = defaultRoot(), view = defaultView() } = {}) {
+	if (theme !== "auto") return theme;
+	const hostTheme = root ? readHostTheme(root) : null;
+	if (hostTheme) return hostTheme;
+	if (view && prefersDark(view)) return "dark";
+	return "light";
+}
+/**
+* Watch both host signals and call `onChange` whenever the resolved theme
+* changes. Returns an unsubscribe function.
+*
+* An explicit `light`/`dark` subscribes to nothing — there is no signal that
+* could change the answer — so callers can pass any theme without branching.
+*/
+function observeTheme(theme, onChange, { root = defaultRoot(), view = defaultView() } = {}) {
+	if (theme !== "auto") return () => {};
+	let current = resolveTheme(theme, {
+		root,
+		view
+	});
+	const publish = () => {
+		const next = resolveTheme(theme, {
+			root,
+			view
+		});
+		if (next !== current) {
+			current = next;
+			onChange(next);
+		}
+	};
+	const teardowns = [];
+	if (root && typeof MutationObserver !== "undefined") {
+		const observer = new MutationObserver(publish);
+		observer.observe(root, {
+			attributeFilter: OBSERVED_ATTRIBUTES,
+			attributes: true
+		});
+		teardowns.push(() => {
+			observer.disconnect();
+		});
+	}
+	const media = view?.matchMedia?.(DARK_MEDIA_QUERY);
+	if (media) {
+		if (media.addEventListener) {
+			media.addEventListener("change", publish);
+			teardowns.push(() => {
+				media.removeEventListener("change", publish);
+			});
+		} else if (media.addListener) {
+			media.addListener(publish);
+			teardowns.push(() => {
+				media.removeListener(publish);
+			});
+		}
+	}
+	return () => {
+		for (const teardown of teardowns) teardown();
+	};
+}
+/**
+* Narrow an untrusted string — a `data-theme` script attribute, a `setTheme`
+* call from plain JS — to a theme, falling back to `auto`.
+*/
+function parseTheme(value) {
+	if (value === "auto" || value === "dark" || value === "light") return value;
+	return "auto";
+}
+//#endregion
 //#region src/chat-widget.tsx
+const DELIVERY_LABELS = {
+	failed: "Failed to send",
+	pending: "Sending…",
+	sent: null
+};
 const WIDGET_STYLES = `
 .clivly-chat-widget, .clivly-chat-widget * { box-sizing: border-box; }
 .clivly-chat-widget {
   --clivly-chat-accent: #185adb;
+  --clivly-chat-accent-contrast: #ffffff;
   --clivly-chat-panel: #ffffff;
+  --clivly-chat-input: transparent;
   --clivly-chat-border: #d6dde8;
   --clivly-chat-text: #132238;
   --clivly-chat-muted: #60738a;
   --clivly-chat-visitor: #ecf3ff;
   --clivly-chat-operator: #f5f7fa;
+  --clivly-chat-shadow: rgba(19, 34, 56, 0.18);
+  --clivly-chat-error-bg: #fff1f1;
+  --clivly-chat-error-border: #f2c2c2;
+  --clivly-chat-error-text: #9f2d2d;
   color: var(--clivly-chat-text);
+  color-scheme: light;
   font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   position: relative;
 }
+/* Dark is a pure token override — every rule below reads through a variable, so
+   the palette is the only thing that changes between themes. The color-scheme
+   declaration carries the theme to the parts of the UI that CSS cannot reach:
+   native scrollbars, autofill backgrounds, and the caret. */
+.clivly-chat-widget[data-clivly-theme="dark"] {
+  --clivly-chat-accent: #4f8cff;
+  --clivly-chat-accent-contrast: #0b1220;
+  --clivly-chat-panel: #111827;
+  --clivly-chat-input: #0b1220;
+  --clivly-chat-border: #2a3546;
+  --clivly-chat-text: #e8edf5;
+  --clivly-chat-muted: #93a2b8;
+  --clivly-chat-visitor: #1e3a6b;
+  --clivly-chat-operator: #1b2534;
+  --clivly-chat-shadow: rgba(0, 0, 0, 0.5);
+  --clivly-chat-error-bg: #2c1618;
+  --clivly-chat-error-border: #5c2a2e;
+  --clivly-chat-error-text: #ffb4b4;
+  color-scheme: dark;
+}
 .clivly-chat-widget button,
 .clivly-chat-widget input,
 .clivly-chat-widget textarea {
@@ -27,7 +168,7 @@ const WIDGET_STYLES = `
   background: var(--clivly-chat-accent);
   border: 0;
   border-radius: 999px;
-  color: white;
+  color: var(--clivly-chat-accent-contrast);
   cursor: pointer;
   display: inline-flex;
   gap: 0.5rem;
@@ -37,7 +178,7 @@ const WIDGET_STYLES = `
   background: var(--clivly-chat-panel);
   border: 1px solid var(--clivly-chat-border);
   border-radius: 1rem;
-  box-shadow: 0 24px 80px rgba(19, 34, 56, 0.18);
+  box-shadow: 0 24px 80px var(--clivly-chat-shadow);
   display: grid;
   grid-template-rows: auto 1fr auto;
   height: min(44rem, 75vh);
@@ -140,37 +281,54 @@ const WIDGET_STYLES = `
 }
 .clivly-chat-widget__input,
 .clivly-chat-widget__textarea {
+  background: var(--clivly-chat-input);
   border: 1px solid var(--clivly-chat-border);
   border-radius: 0.8rem;
+  color: inherit;
   min-width: 0;
   padding: 0.75rem 0.85rem;
 }
+.clivly-chat-widget__input::placeholder,
+.clivly-chat-widget__textarea::placeholder {
+  color: var(--clivly-chat-muted);
+}
 .clivly-chat-widget__textarea {
   min-height: 5.5rem;
   resize: vertical;
 }
 .clivly-chat-widget__actions {
+  align-items: center;
   display: flex;
   gap: 0.75rem;
   justify-content: space-between;
 }
+/* The subtitle is the only part that may reflow; without min-width the flex
+   default (min-content) lets it push the button below its intrinsic width. */
+.clivly-chat-widget__actions .clivly-chat-widget__subtitle {
+  min-width: 0;
+}
 .clivly-chat-widget__button {
   background: var(--clivly-chat-accent);
   border: 0;
   border-radius: 0.8rem;
-  color: white;
+  color: var(--clivly-chat-accent-contrast);
   cursor: pointer;
+  flex: 0 0 auto;
+  font: inherit;
+  font-weight: 600;
+  line-height: 1.2;
   padding: 0.75rem 0.95rem;
+  white-space: nowrap;
 }
 .clivly-chat-widget__button[disabled] {
   cursor: not-allowed;
   opacity: 0.55;
 }
 .clivly-chat-widget__error {
-  background: #fff1f1;
-  border: 1px solid #f2c2c2;
+  background: var(--clivly-chat-error-bg);
+  border: 1px solid var(--clivly-chat-error-border);
   border-radius: 0.8rem;
-  color: #9f2d2d;
+  color: var(--clivly-chat-error-text);
   font-size: 0.875rem;
   padding: 0.75rem;
 }
@@ -232,14 +390,93 @@ function markMessageFailed(messages, clientMessageId) {
 function sortMessages(messages) {
 	return [...messages].sort((left, right) => left.createdAt.localeCompare(right.createdAt));
 }
-function useThemeStyle(session) {
+function useThemeStyle(session, style) {
 	return (0, react.useMemo)(() => {
 		const brandColor = session?.widget.config.brandColor ?? null;
-		if (!brandColor) return;
-		return { ["--clivly-chat-accent"]: brandColor };
-	}, [session?.widget.config.brandColor]);
+		if (!brandColor) return style;
+		return {
+			["--clivly-chat-accent"]: brandColor,
+			...style
+		};
+	}, [session?.widget.config.brandColor, style]);
+}
+/**
+* Track the theme the widget should paint.
+*
+* The initial value is resolved synchronously so the first paint is already
+* correct — deferring it to an effect would flash light on a dark page.
+*/
+function useResolvedTheme(theme) {
+	const [resolved, setResolved] = (0, react.useState)(() => resolveTheme(theme));
+	(0, react.useEffect)(() => {
+		setResolved(resolveTheme(theme));
+		return observeTheme(theme, setResolved);
+	}, [theme]);
+	return resolved;
+}
+/**
+* Reduce one socket event into widget state.
+*
+* Lives at module scope rather than inside the connect effect so the wire
+* protocol reads as a single unit, and so `ChatWidget` stays inside the
+* cognitive-complexity budget.
+*/
+function applyServerEvent(event, { setError, setIsReady, setMessages }) {
+	switch (event.type) {
+		case "conversation.snapshot":
+			setMessages(sortMessages(event.messages.map((message) => createLocalMessage(message))));
+			return;
+		case "error":
+			setError(event.message);
+			return;
+		case "message.ack":
+			setMessages((currentMessages) => sortMessages(replacePendingMessage(currentMessages, event.clientMessageId, event.message)));
+			return;
+		case "message.created": {
+			const clientMessageId = event.clientMessageId;
+			setMessages((currentMessages) => sortMessages(clientMessageId ? replacePendingMessage(currentMessages, clientMessageId, event.message) : mergeMessage(currentMessages, event.message)));
+			return;
+		}
+		case "session.ready":
+			setIsReady(true);
+			return;
+		default: return;
+	}
 }
-function ChatWidget({ className, createTransport, getSession, initiallyOpen = false, launcherLabel = "Chat with us", storage = DEFAULT_STORAGE, widgetId }) {
+function MessageBubble({ message }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("article", {
+		className: "clivly-chat-widget__message",
+		"data-sender": message.senderType,
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "clivly-chat-widget__message-meta",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: message.author ?? "Clivly" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: formatTimestamp(message.createdAt) })]
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { children: message.body }),
+			message.delivery === "sent" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "clivly-chat-widget__status",
+				children: DELIVERY_LABELS[message.delivery]
+			})
+		]
+	});
+}
+/**
+* The scrollable transcript. Split out of `ChatWidget` because the three states
+* (no session, empty thread, messages) were a nested ternary in the render tree
+* — early returns make them readable and keep the parent's complexity down.
+*/
+function MessageList({ greeting, hasSession, messages }) {
+	if (!hasSession) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+		className: "clivly-chat-widget__empty",
+		children: greeting
+	});
+	if (messages.length === 0) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+		className: "clivly-chat-widget__empty",
+		children: "No messages yet. Say hello to get the conversation started."
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: messages.map((message) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MessageBubble, { message }, message.id)) });
+}
+function ChatWidget({ className, createTransport, getSession, initiallyOpen = false, launcherLabel = "Chat with us", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
 	const [isOpen, setIsOpen] = (0, react.useState)(initiallyOpen);
 	const [error, setError] = (0, react.useState)(null);
 	const [isConnecting, setIsConnecting] = (0, react.useState)(false);
@@ -253,7 +490,8 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 	});
 	const transportRef = (0, react.useRef)(null);
 	const listRef = (0, react.useRef)(null);
-	const themeStyle = useThemeStyle(session);
+	const themeStyle = useThemeStyle(session, style);
+	const resolvedTheme = useResolvedTheme(theme);
 	(0, react.useEffect)(() => () => {
 		transportRef.current?.close();
 		transportRef.current = null;
@@ -267,31 +505,6 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 		transportRef.current = null;
 		setIsReady(false);
 		if (!(session && createTransport)) return;
-		const handleEvent = (event) => {
-			switch (event.type) {
-				case "conversation.snapshot":
-					setMessages(sortMessages(event.messages.map((message) => createLocalMessage(message))));
-					return;
-				case "error":
-					setError(event.message);
-					return;
-				case "message.ack":
-					setMessages((currentMessages) => sortMessages(replacePendingMessage(currentMessages, event.clientMessageId, event.message)));
-					return;
-				case "message.created": {
-					const clientMessageId = event.clientMessageId;
-					if (clientMessageId) {
-						setMessages((currentMessages) => sortMessages(replacePendingMessage(currentMessages, clientMessageId, event.message)));
-						return;
-					}
-					setMessages((currentMessages) => sortMessages(mergeMessage(currentMessages, event.message)));
-					return;
-				}
-				case "session.ready":
-					setIsReady(true);
-					return;
-			}
-		};
 		const connection = createTransport({
 			handlers: {
 				onClose: () => {
@@ -300,7 +513,13 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 				onError: (transportError) => {
 					setError(transportError.message);
 				},
-				onEvent: handleEvent,
+				onEvent: (event) => {
+					applyServerEvent(event, {
+						setError,
+						setIsReady,
+						setMessages
+					});
+				},
 				onOpen: () => {
 					setIsReady(true);
 				}
@@ -368,6 +587,7 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 	const sessionSummary = session ? `${session.contact.name} • ${session.contact.email}` : greeting;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: `clivly-chat-widget ${className ?? ""}`.trim(),
+		"data-clivly-theme": resolvedTheme,
 		style: themeStyle,
 		children: [
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: WIDGET_STYLES }),
@@ -407,26 +627,10 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 						children: [error ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 							className: "clivly-chat-widget__error",
 							children: error
-						}) : null, session ? messages.length > 0 ? messages.map((message) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("article", {
-							className: "clivly-chat-widget__message",
-							"data-sender": message.senderType,
-							children: [
-								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "clivly-chat-widget__message-meta",
-									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: message.author ?? "Clivly" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: formatTimestamp(message.createdAt) })]
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { children: message.body }),
-								message.delivery === "sent" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-									className: "clivly-chat-widget__status",
-									children: message.delivery === "pending" ? "Sending…" : "Failed to send"
-								})
-							]
-						}, message.id)) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: "clivly-chat-widget__empty",
-							children: "No messages yet. Say hello to get the conversation started."
-						}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: "clivly-chat-widget__empty",
-							children: greeting
+						}) : null, /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MessageList, {
+							greeting,
+							hasSession: Boolean(session),
+							messages
 						})]
 					}),
 					session ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("form", {
@@ -617,16 +821,27 @@ const MOUNTED_DATA_ATTR = "clivlyMounted";
 function resolveSocketUrl(socketUrlTemplate, conversationId, token) {
 	return socketUrlTemplate.replaceAll("{conversationId}", encodeURIComponent(conversationId)).replaceAll("{token}", encodeURIComponent(token));
 }
-function mountChatWidget$1({ container, createTransport, sessionUrl, socketUrlTemplate, widgetId, ...props }) {
+function createWidgetMount({ container, createTransport, sessionUrl, socketUrlTemplate, theme = "auto", widgetId, ...props }) {
 	const transport = createTransport ?? (socketUrlTemplate ? createWebSocketTransport({ resolveUrl: (session) => session.socketUrl ?? resolveSocketUrl(socketUrlTemplate, session.conversation.id, session.token) }) : createClivlyTransport());
+	const getSession = createSessionFetcher({ sessionUrl });
 	const root = (0, react_dom_client.createRoot)(container);
-	root.render(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(ChatWidget, {
-		...props,
-		createTransport: transport,
-		getSession: createSessionFetcher({ sessionUrl }),
-		widgetId
-	}));
-	return root;
+	const render = (nextTheme) => {
+		root.render(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(ChatWidget, {
+			...props,
+			createTransport: transport,
+			getSession,
+			theme: nextTheme,
+			widgetId
+		}));
+	};
+	render(theme);
+	return {
+		root,
+		setTheme: render
+	};
+}
+function mountChatWidget$1(options) {
+	return createWidgetMount(options).root;
 }
 function markScriptMounted(script) {
 	script.dataset[MOUNTED_DATA_ATTR] = "true";
@@ -645,15 +860,17 @@ function mountChatWidgetScript$1(script = document.currentScript) {
 	const shadowRoot = host.attachShadow({ mode: "open" });
 	const container = document.createElement("div");
 	shadowRoot.append(container);
-	const root = mountChatWidget$1({
+	const { root, setTheme } = createWidgetMount({
 		container,
 		sessionUrl,
 		socketUrlTemplate: script.dataset.socketUrlTemplate,
+		theme: parseTheme(script.dataset.theme),
 		widgetId
 	});
 	markScriptMounted(script);
 	return {
 		root,
+		setTheme,
 		shadowRoot
 	};
 }

package/dist/browser.d.cts

@@ -1,4 +1,18 @@
 import { Root } from "react-dom/client";
+import { CSSProperties } from "react";
+
+//#region src/theme.d.ts
+/**
+ * Theme resolution for the widget.
+ *
+ * The script-tag build mounts into a Shadow DOM, so the host's `.dark` class on
+ * `<html>` can never reach the widget through a CSS selector. The theme has to
+ * be resolved in JavaScript — reading the same signals the host's own CSS reads
+ * — and applied to an attribute inside the widget. That is what this module
+ * does, and why it is a plain DOM module rather than a stylesheet.
+ */
+type ChatWidgetTheme = "auto" | "dark" | "light";
+//#endregion
 //#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
@@ -101,6 +115,18 @@ interface ChatWidgetProps {
   initiallyOpen?: boolean;
   launcherLabel?: string;
   storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Inline styles on the widget root. The intended use is overriding palette
+   * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
+   * inline declarations beat both palette rules without any specificity games.
+   */
+  style?: CSSProperties;
+  /**
+   * `"auto"` (the default) follows the host app: a `data-theme` attribute or a
+   * `dark`/`light` class on `<html>`, then the OS preference. `"light"` and
+   * `"dark"` pin the widget regardless of what the host is doing.
+   */
+  theme?: ChatWidgetTheme;
   widgetId: string;
 }
 //#endregion
@@ -111,26 +137,31 @@ interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" |
   socketUrlTemplate?: string;
   widgetId: string;
 }
-declare function mountChatWidget$1({
-  container,
-  createTransport,
-  sessionUrl,
-  socketUrlTemplate,
-  widgetId,
-  ...props
-}: MountChatWidgetOptions$1): Root;
-interface ScriptMountResult$1 {
+interface ChatWidgetMount$1 {
   root: Root;
+  /**
+   * Repaint the widget in a different theme. `"auto"` resumes following the
+   * host, so a caller can hand control back as easily as taking it.
+   *
+   * Only needed by hosts whose theme toggle does not touch `<html>` — the
+   * default `"auto"` already tracks a `data-theme` attribute or a `dark`
+   * class there.
+   */
+  setTheme: (theme: ChatWidgetTheme) => void;
+}
+declare function mountChatWidget$1(options: MountChatWidgetOptions$1): Root;
+interface ScriptMountResult$1 extends ChatWidgetMount$1 {
   shadowRoot: ShadowRoot;
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
 declare function autoMountChatWidgetScript$1(script?: HTMLScriptElement | null): ScriptMountResult$1 | null;
 //#endregion
 //#region src/browser.d.ts
+type ChatWidgetMount = ChatWidgetMount$1;
 type MountChatWidgetOptions = MountChatWidgetOptions$1;
 type ScriptMountResult = ScriptMountResult$1;
 declare const mountChatWidget: typeof mountChatWidget$1;
 declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 declare const autoMountChatWidgetScript: typeof autoMountChatWidgetScript$1;
 //#endregion
-export { MountChatWidgetOptions, ScriptMountResult, autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };
+export { ChatWidgetMount, MountChatWidgetOptions, ScriptMountResult, autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };

package/dist/browser.d.mts

@@ -1,4 +1,18 @@
 import { Root } from "react-dom/client";
+import { CSSProperties } from "react";
+
+//#region src/theme.d.ts
+/**
+ * Theme resolution for the widget.
+ *
+ * The script-tag build mounts into a Shadow DOM, so the host's `.dark` class on
+ * `<html>` can never reach the widget through a CSS selector. The theme has to
+ * be resolved in JavaScript — reading the same signals the host's own CSS reads
+ * — and applied to an attribute inside the widget. That is what this module
+ * does, and why it is a plain DOM module rather than a stylesheet.
+ */
+type ChatWidgetTheme = "auto" | "dark" | "light";
+//#endregion
 //#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
@@ -101,6 +115,18 @@ interface ChatWidgetProps {
   initiallyOpen?: boolean;
   launcherLabel?: string;
   storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Inline styles on the widget root. The intended use is overriding palette
+   * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
+   * inline declarations beat both palette rules without any specificity games.
+   */
+  style?: CSSProperties;
+  /**
+   * `"auto"` (the default) follows the host app: a `data-theme` attribute or a
+   * `dark`/`light` class on `<html>`, then the OS preference. `"light"` and
+   * `"dark"` pin the widget regardless of what the host is doing.
+   */
+  theme?: ChatWidgetTheme;
   widgetId: string;
 }
 //#endregion
@@ -111,26 +137,31 @@ interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" |
   socketUrlTemplate?: string;
   widgetId: string;
 }
-declare function mountChatWidget$1({
-  container,
-  createTransport,
-  sessionUrl,
-  socketUrlTemplate,
-  widgetId,
-  ...props
-}: MountChatWidgetOptions$1): Root;
-interface ScriptMountResult$1 {
+interface ChatWidgetMount$1 {
   root: Root;
+  /**
+   * Repaint the widget in a different theme. `"auto"` resumes following the
+   * host, so a caller can hand control back as easily as taking it.
+   *
+   * Only needed by hosts whose theme toggle does not touch `<html>` — the
+   * default `"auto"` already tracks a `data-theme` attribute or a `dark`
+   * class there.
+   */
+  setTheme: (theme: ChatWidgetTheme) => void;
+}
+declare function mountChatWidget$1(options: MountChatWidgetOptions$1): Root;
+interface ScriptMountResult$1 extends ChatWidgetMount$1 {
   shadowRoot: ShadowRoot;
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
 declare function autoMountChatWidgetScript$1(script?: HTMLScriptElement | null): ScriptMountResult$1 | null;
 //#endregion
 //#region src/browser.d.ts
+type ChatWidgetMount = ChatWidgetMount$1;
 type MountChatWidgetOptions = MountChatWidgetOptions$1;
 type ScriptMountResult = ScriptMountResult$1;
 declare const mountChatWidget: typeof mountChatWidget$1;
 declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 declare const autoMountChatWidgetScript: typeof autoMountChatWidgetScript$1;
 //#endregion
-export { MountChatWidgetOptions, ScriptMountResult, autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };
+export { ChatWidgetMount, MountChatWidgetOptions, ScriptMountResult, autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };