@clivly/chat-widget 0.15.0 → 0.17.0

package/dist/browser.d.cts

@@ -1,6 +1,24 @@
 import { Root } from "react-dom/client";
 import { CSSProperties } 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.
  *
@@ -11,8 +29,6 @@ import { CSSProperties } from "react";
  * 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 {
   brandColor?: string | null;
@@ -124,8 +140,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;
@@ -152,8 +166,21 @@ interface CreateChatTransportOptions {
   session: WidgetSessionPayload;
 }
 type CreateChatTransport = (options: CreateChatTransportOptions) => ChatTransportConnection;
-//#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;
@@ -177,8 +204,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
@@ -193,8 +235,6 @@ interface ChatWidgetProps {
   theme?: ChatWidgetTheme;
   widgetId: string;
 }
-//#endregion
-//#region src/browser-mount.d.ts
 interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
@@ -219,12 +259,10 @@ 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/browser.d.ts
 export type ChatWidgetMount = ChatWidgetMount$1;
 export type MountChatWidgetOptions = MountChatWidgetOptions$1;
 export type ScriptMountResult = ScriptMountResult$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 export declare const autoMountChatWidgetScript: typeof autoMountChatWidgetScript$1;
-//#endregion
+export {};

package/dist/browser.d.mts

@@ -1,6 +1,24 @@
 import { Root } from "react-dom/client";
 import { CSSProperties } 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.
  *
@@ -11,8 +29,6 @@ import { CSSProperties } from "react";
  * 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 {
   brandColor?: string | null;
@@ -124,8 +140,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;
@@ -152,8 +166,21 @@ interface CreateChatTransportOptions {
   session: WidgetSessionPayload;
 }
 type CreateChatTransport = (options: CreateChatTransportOptions) => ChatTransportConnection;
-//#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;
@@ -177,8 +204,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
@@ -193,8 +235,6 @@ interface ChatWidgetProps {
   theme?: ChatWidgetTheme;
   widgetId: string;
 }
-//#endregion
-//#region src/browser-mount.d.ts
 interface MountChatWidgetOptions$1 extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
@@ -219,12 +259,10 @@ 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/browser.d.ts
 export type ChatWidgetMount = ChatWidgetMount$1;
 export type MountChatWidgetOptions = MountChatWidgetOptions$1;
 export type ScriptMountResult = ScriptMountResult$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 export declare const autoMountChatWidgetScript: typeof autoMountChatWidgetScript$1;
-//#endregion
+export {};