@clivly/chat-widget 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -1,6 +1,24 @@
 import { Root } from "react-dom/client";
 import { CSSProperties, ReactElement } from "react";
-//#region src/theme.d.ts
+/**
+ * Where the widget sits on the host page, and what its launcher looks like.
+ *
+ * Until 0.16 the widget rendered in normal flow wherever it was mounted — the
+ * script tag inserted it directly after itself, so most embeds showed a
+ * full-width-label pill at the end of the page rather than a floating button.
+ * Floating in a corner is now the default; `"inline"` keeps the old behaviour
+ * for a host that positions the widget itself.
+ */
+type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
+/**
+ * - `"auto"` (default): the labelled pill on wide screens, a 48px icon-only
+ *   button below 48rem, where a pill covers the host's own controls.
+ * - `"pill"`: always the labelled pill.
+ * - `"icon"`: always the icon-only button.
+ *
+ * The label stays the button's accessible name in every variant.
+ */
+type ChatWidgetLauncher = "auto" | "icon" | "pill";
 /**
  * Theme resolution for the widget.
  *
@@ -25,8 +43,6 @@ interface ResolveThemeOptions {
  * the majority of pages.
  */
 export declare function resolveTheme(theme: ChatWidgetTheme, { root, view }?: ResolveThemeOptions): ResolvedTheme;
-//#endregion
-//#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
   brandColor?: string | null;
@@ -143,8 +159,6 @@ interface WidgetErrorEvent {
   type: "error";
 }
 type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
-//#endregion
-//#region src/transport.d.ts
 interface ChatTransportHandlers {
   onClose: () => void;
   onError: (error: Error) => void;
@@ -183,8 +197,21 @@ interface CreateLoopbackTransportOptions {
   replyDelayMs?: number;
 }
 export declare function createLoopbackTransport({ operatorName, operatorReply, replyDelayMs }?: CreateLoopbackTransportOptions): CreateChatTransport;
-//#endregion
-//#region src/chat-widget.d.ts
+/**
+ * Where the widget keeps the visitor token that resumes a conversation.
+ *
+ * Keyed by widget AND by who the token was issued to. One key per widget used
+ * to hand the token to whoever opened the widget next on that browser — after
+ * a sign-out, or between two people who don't sign in at all — and the server
+ * resumed the previous person's thread for them (chat widget session review
+ * 2026-10-28, S1). The server now refuses that resume on its own; this keeps
+ * each person's token to themselves so a returning visitor still resumes.
+ *
+ * The identity part is a short hash of the normalised email, so the address
+ * itself isn't written into storage keys. It only partitions storage: the
+ * server's identity check is the security boundary, not this.
+ */
+type VisitorTokenStorage = Pick<Storage, "getItem" | "setItem"> & Partial<Pick<Storage, "removeItem">>;
 interface ChatWidgetProps {
   className?: string;
   createTransport?: CreateChatTransport;
@@ -208,8 +235,23 @@ interface ChatWidgetProps {
   defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
+  /** Launcher shape; see {@link ChatWidgetLauncher}. Defaults to `"auto"`. */
+  launcher?: ChatWidgetLauncher;
+  /** The launcher's visible text, and always its accessible name. */
   launcherLabel?: string;
-  storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Where the widget sits; see {@link ChatWidgetPlacement}. Defaults to
+   * `"bottom-right"`, floating clear of the device's safe-area insets. Stacks
+   * at `--clivly-chat-z-index` (default 2147483000) — lower it through
+   * `style` to sit beneath the host's own dialogs.
+   */
+  placement?: ChatWidgetPlacement;
+  /**
+   * Where the visitor token is kept, per widget and per visitor (see
+   * visitor-token-storage.ts). `removeItem` is optional; with it, the
+   * pre-0.16 shared token is retired after its first use.
+   */
+  storage?: VisitorTokenStorage;
   /**
    * Inline styles on the widget root. The intended use is overriding palette
    * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
@@ -224,14 +266,12 @@ interface ChatWidgetProps {
   theme?: ChatWidgetTheme;
   widgetId: string;
 }
-export declare function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen, launcherLabel, storage, style, theme, widgetId }: ChatWidgetProps): ReactElement;
+export declare function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen, launcher, launcherLabel, placement, storage, style, theme, widgetId }: ChatWidgetProps): ReactElement;
 export declare function ChatLauncher(): null;
 export declare function ChatPanel(): null;
 export declare function MessageComposer(): null;
 export declare function PreChatForm(): null;
 export declare function ConversationView(): null;
-//#endregion
-//#region src/browser-mount.d.ts
 interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
@@ -256,8 +296,6 @@ interface ScriptMountResult$1 extends ChatWidgetMount$1 {
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
 declare function autoMountChatWidgetScript$1(script?: HTMLScriptElement | null): ScriptMountResult$1 | null;
-//#endregion
-//#region src/clivly-transport.d.ts
 interface CreateClivlyTransportOptions$1 {
   createSocket?: (url: string, protocols?: string | string[]) => WebSocket;
 }
@@ -269,15 +307,11 @@ interface CreateClivlyTransportOptions$1 {
  * produce a silently dead socket.
  */
 declare function createClivlyTransport$1(options?: CreateClivlyTransportOptions$1): CreateChatTransport;
-//#endregion
-//#region src/session.d.ts
 interface CreateSessionFetcherOptions {
   fetchImpl?: typeof fetch;
   sessionUrl: string;
 }
 export declare function createSessionFetcher({ fetchImpl, sessionUrl }: CreateSessionFetcherOptions): GetSession;
-//#endregion
-//#region src/index.d.ts
 export type ChatWidgetMount = ChatWidgetMount$1;
 export type MountChatWidgetOptions = MountChatWidgetOptions$1;
 export type ScriptMountResult = ScriptMountResult$1;
@@ -286,5 +320,4 @@ export type CreateClivlyTransportOptions = CreateClivlyTransportOptions$1;
 export declare const createClivlyTransport: typeof createClivlyTransport$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
-//#endregion
-export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };
+export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetLauncher, ChatWidgetPlacement, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };

package/dist/index.d.mts

@@ -1,6 +1,24 @@
 import { Root } from "react-dom/client";
 import { CSSProperties, ReactElement } from "react";
-//#region src/theme.d.ts
+/**
+ * Where the widget sits on the host page, and what its launcher looks like.
+ *
+ * Until 0.16 the widget rendered in normal flow wherever it was mounted — the
+ * script tag inserted it directly after itself, so most embeds showed a
+ * full-width-label pill at the end of the page rather than a floating button.
+ * Floating in a corner is now the default; `"inline"` keeps the old behaviour
+ * for a host that positions the widget itself.
+ */
+type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
+/**
+ * - `"auto"` (default): the labelled pill on wide screens, a 48px icon-only
+ *   button below 48rem, where a pill covers the host's own controls.
+ * - `"pill"`: always the labelled pill.
+ * - `"icon"`: always the icon-only button.
+ *
+ * The label stays the button's accessible name in every variant.
+ */
+type ChatWidgetLauncher = "auto" | "icon" | "pill";
 /**
  * Theme resolution for the widget.
  *
@@ -25,8 +43,6 @@ interface ResolveThemeOptions {
  * the majority of pages.
  */
 export declare function resolveTheme(theme: ChatWidgetTheme, { root, view }?: ResolveThemeOptions): ResolvedTheme;
-//#endregion
-//#region src/types.d.ts
 type WidgetSenderType = "visitor" | "operator" | "system";
 interface WidgetConfig {
   brandColor?: string | null;
@@ -143,8 +159,6 @@ interface WidgetErrorEvent {
   type: "error";
 }
 type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
-//#endregion
-//#region src/transport.d.ts
 interface ChatTransportHandlers {
   onClose: () => void;
   onError: (error: Error) => void;
@@ -183,8 +197,21 @@ interface CreateLoopbackTransportOptions {
   replyDelayMs?: number;
 }
 export declare function createLoopbackTransport({ operatorName, operatorReply, replyDelayMs }?: CreateLoopbackTransportOptions): CreateChatTransport;
-//#endregion
-//#region src/chat-widget.d.ts
+/**
+ * Where the widget keeps the visitor token that resumes a conversation.
+ *
+ * Keyed by widget AND by who the token was issued to. One key per widget used
+ * to hand the token to whoever opened the widget next on that browser — after
+ * a sign-out, or between two people who don't sign in at all — and the server
+ * resumed the previous person's thread for them (chat widget session review
+ * 2026-10-28, S1). The server now refuses that resume on its own; this keeps
+ * each person's token to themselves so a returning visitor still resumes.
+ *
+ * The identity part is a short hash of the normalised email, so the address
+ * itself isn't written into storage keys. It only partitions storage: the
+ * server's identity check is the security boundary, not this.
+ */
+type VisitorTokenStorage = Pick<Storage, "getItem" | "setItem"> & Partial<Pick<Storage, "removeItem">>;
 interface ChatWidgetProps {
   className?: string;
   createTransport?: CreateChatTransport;
@@ -208,8 +235,23 @@ interface ChatWidgetProps {
   defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
+  /** Launcher shape; see {@link ChatWidgetLauncher}. Defaults to `"auto"`. */
+  launcher?: ChatWidgetLauncher;
+  /** The launcher's visible text, and always its accessible name. */
   launcherLabel?: string;
-  storage?: Pick<Storage, "getItem" | "setItem">;
+  /**
+   * Where the widget sits; see {@link ChatWidgetPlacement}. Defaults to
+   * `"bottom-right"`, floating clear of the device's safe-area insets. Stacks
+   * at `--clivly-chat-z-index` (default 2147483000) — lower it through
+   * `style` to sit beneath the host's own dialogs.
+   */
+  placement?: ChatWidgetPlacement;
+  /**
+   * Where the visitor token is kept, per widget and per visitor (see
+   * visitor-token-storage.ts). `removeItem` is optional; with it, the
+   * pre-0.16 shared token is retired after its first use.
+   */
+  storage?: VisitorTokenStorage;
   /**
    * Inline styles on the widget root. The intended use is overriding palette
    * tokens — `{ "--clivly-chat-panel": "#0b0f19" }` — which works because
@@ -224,14 +266,12 @@ interface ChatWidgetProps {
   theme?: ChatWidgetTheme;
   widgetId: string;
 }
-export declare function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen, launcherLabel, storage, style, theme, widgetId }: ChatWidgetProps): ReactElement;
+export declare function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen, launcher, launcherLabel, placement, storage, style, theme, widgetId }: ChatWidgetProps): ReactElement;
 export declare function ChatLauncher(): null;
 export declare function ChatPanel(): null;
 export declare function MessageComposer(): null;
 export declare function PreChatForm(): null;
 export declare function ConversationView(): null;
-//#endregion
-//#region src/browser-mount.d.ts
 interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
@@ -256,8 +296,6 @@ interface ScriptMountResult$1 extends ChatWidgetMount$1 {
 }
 declare function mountChatWidgetScript$1(script?: HTMLScriptElement): ScriptMountResult$1;
 declare function autoMountChatWidgetScript$1(script?: HTMLScriptElement | null): ScriptMountResult$1 | null;
-//#endregion
-//#region src/clivly-transport.d.ts
 interface CreateClivlyTransportOptions$1 {
   createSocket?: (url: string, protocols?: string | string[]) => WebSocket;
 }
@@ -269,15 +307,11 @@ interface CreateClivlyTransportOptions$1 {
  * produce a silently dead socket.
  */
 declare function createClivlyTransport$1(options?: CreateClivlyTransportOptions$1): CreateChatTransport;
-//#endregion
-//#region src/session.d.ts
 interface CreateSessionFetcherOptions {
   fetchImpl?: typeof fetch;
   sessionUrl: string;
 }
 export declare function createSessionFetcher({ fetchImpl, sessionUrl }: CreateSessionFetcherOptions): GetSession;
-//#endregion
-//#region src/index.d.ts
 export type ChatWidgetMount = ChatWidgetMount$1;
 export type MountChatWidgetOptions = MountChatWidgetOptions$1;
 export type ScriptMountResult = ScriptMountResult$1;
@@ -286,5 +320,4 @@ export type CreateClivlyTransportOptions = CreateClivlyTransportOptions$1;
 export declare const createClivlyTransport: typeof createClivlyTransport$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
-//#endregion
-export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };
+export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetLauncher, ChatWidgetPlacement, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };