@customerhero/js 2.2.0 → 2.3.0

package/README.md

@@ -56,6 +56,25 @@ chat.identify({
 | `locale`            | `string`                          | Widget locale (e.g. `"en"`, `"es"`). Auto-detected from browser if omitted. |
 | `suggestedMessages` | `string[]`                        | Quick-reply options shown before the first message.                         |
 
+### Appearance
+
+| Option                   | Type                                | Description                                                                       |
+| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
+| `colorScheme`            | `"auto" \| "light" \| "dark"`       | `auto` follows the visitor's OS preference. Defaults to `light`.                  |
+| `primaryColorDark`       | `string`                            | Primary color used in dark mode. Only honoured when the effective scheme is dark. |
+| `backgroundColorDark`    | `string`                            | Background color used in dark mode.                                               |
+| `textColorDark`          | `string`                            | Text color used in dark mode.                                                     |
+| `size`                   | `"compact" \| "default" \| "large"` | Launcher diameter, panel dimensions, and base font size.                          |
+| `cornerStyle`            | `"soft" \| "rounded" \| "square"`   | Panel border-radius preset.                                                       |
+| `launcher.iconUrl`       | `string`                            | Custom launcher icon URL (replaces the default chat-bubble glyph).                |
+| `launcher.label`         | `string`                            | CTA label next to the launcher (turns the bubble into a pill). Max 60 chars.      |
+| `launcher.showOnlineDot` | `boolean`                           | Show a small green dot on the launcher when agents are available.                 |
+| `offset.bottom`          | `number`                            | Pixel offset from the bottom edge. 0–1000. Defaults to 20.                        |
+| `offset.side`            | `number`                            | Pixel offset from the side (mirrors `position`). 0–1000. Defaults to 20.          |
+| `zIndex`                 | `number`                            | Z-index override. Defaults to 99999. Capped at 2 000 000 000.                     |
+
+Dark colors are never auto-derived from `primaryColor`/`backgroundColor`/`textColor` — set them explicitly when enabling dark or auto modes.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -20,8 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CORNER_RADIUS: () => CORNER_RADIUS,
   CustomerHeroChat: () => CustomerHeroChat,
   DEFAULTS: () => DEFAULTS,
+  SIZE_PRESETS: () => SIZE_PRESETS,
   SUPPORTED_LOCALES: () => SUPPORTED_LOCALES,
   ScreenshotCancelled: () => ScreenshotCancelled,
   ScreenshotUnavailable: () => ScreenshotUnavailable,
@@ -29,10 +31,14 @@ __export(index_exports, {
   captureScreenshot: () => captureScreenshot,
   createTranslator: () => createTranslator,
   detectLocale: () => detectLocale,
+  effectiveColors: () => effectiveColors,
   evaluate: () => evaluate,
   isRtlLocale: () => isRtlLocale,
+  panelRadius: () => panelRadius,
   pickFire: () => pickFire,
   resolveLocale: () => resolveLocale,
+  resolveScheme: () => resolveScheme,
+  sizePreset: () => sizePreset,
   startTriggersRuntime: () => startTriggersRuntime
 });
 module.exports = __toCommonJS(index_exports);
@@ -46,7 +52,29 @@ var DEFAULTS = {
   position: "bottom-right",
   placeholderText: "Type your message...",
   welcomeMessage: "Hi! How can I help you today?",
-  title: "CustomerHero"
+  title: "CustomerHero",
+  // Appearance pack (B1–B6) defaults.
+  colorScheme: "light",
+  // Dark fallbacks used when the effective scheme is dark and no per-chatbot
+  // dark color is configured. Operators can — and should — override these.
+  primaryColorDark: "#A78BFA",
+  backgroundColorDark: "#0F172A",
+  textColorDark: "#E5E7EB",
+  size: "default",
+  cornerStyle: "rounded",
+  offsetBottom: 20,
+  offsetSide: 20,
+  zIndex: 99999
+};
+var SIZE_PRESETS = {
+  compact: { bubble: 48, width: 320, height: 480, fontSize: 13 },
+  default: { bubble: 56, width: 380, height: 520, fontSize: 14 },
+  large: { bubble: 64, width: 440, height: 600, fontSize: 15 }
+};
+var CORNER_RADIUS = {
+  soft: 8,
+  rounded: 16,
+  square: 0
 };
 
 // src/i18n/locales/en.ts
@@ -1014,7 +1042,14 @@ function startTriggersRuntime(options) {
 }
 
 // src/client.ts
+function clampInt(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
 function resolveConfig(userConfig, fetched) {
+  const launcherUser = userConfig.launcher ?? {};
+  const launcherFetched = fetched?.launcher ?? {};
+  const offsetUser = userConfig.offset ?? {};
   return {
     chatbotId: userConfig.chatbotId,
     apiBase: userConfig.apiBase ?? DEFAULTS.apiBase,
@@ -1027,7 +1062,32 @@ function resolveConfig(userConfig, fetched) {
     title: userConfig.title ?? fetched?.title ?? DEFAULTS.title,
     avatarUrl: userConfig.avatarUrl ?? fetched?.avatarUrl,
     suggestedMessages: userConfig.suggestedMessages ?? fetched?.suggestedMessages ?? [],
-    stringOverrides: fetched?.stringOverrides
+    stringOverrides: fetched?.stringOverrides,
+    // Appearance pack. Color palette + size + corner style + launcher all
+    // come from the server widget_config (with host-side override). The
+    // *runtime* knobs — colorScheme, offset, zIndex — are host-only because
+    // they depend on the page the widget is embedded in, not the chatbot.
+    primaryColorDark: userConfig.primaryColorDark ?? fetched?.primaryColorDark,
+    backgroundColorDark: userConfig.backgroundColorDark ?? fetched?.backgroundColorDark,
+    textColorDark: userConfig.textColorDark ?? fetched?.textColorDark,
+    size: userConfig.size ?? fetched?.size ?? DEFAULTS.size,
+    cornerStyle: userConfig.cornerStyle ?? fetched?.cornerStyle ?? DEFAULTS.cornerStyle,
+    launcher: {
+      iconUrl: launcherUser.iconUrl ?? launcherFetched.iconUrl,
+      label: launcherUser.label ?? launcherFetched.label,
+      showOnlineDot: launcherUser.showOnlineDot ?? launcherFetched.showOnlineDot ?? false
+    },
+    colorScheme: userConfig.colorScheme ?? DEFAULTS.colorScheme,
+    offset: {
+      bottom: clampInt(offsetUser.bottom, 0, 1e3, DEFAULTS.offsetBottom),
+      side: clampInt(offsetUser.side, 0, 1e3, DEFAULTS.offsetSide)
+    },
+    zIndex: clampInt(userConfig.zIndex, 0, 2e9, DEFAULTS.zIndex),
+    // Defaults to true — the widget shows the attach button unless the
+    // chatbot explicitly opts out via widget_config or the host passes
+    // allowAttachments=false. Server still enforces the same flag at the
+    // upload endpoint either way.
+    allowAttachments: userConfig.allowAttachments ?? fetched?.allowAttachments ?? true
   };
 }
 function sanitizeIncidentBanner(input) {
@@ -1117,9 +1177,40 @@ var CustomerHeroChat = class {
       pendingTriggerId: null,
       pendingPrefill: null,
       incidentBanner: null,
-      incidentBannerDismissed: false
+      incidentBannerDismissed: false,
+      readOnly: false
     };
   }
+  /**
+   * Mark the config as loaded and put the client into read-only preview
+   * mode without hitting the API. Used by `@customerhero/react/preview` to
+   * render the widget against a host-supplied config (the dashboard preview
+   * pane). Public API consumers should not call this.
+   *
+   * Pass a config to re-resolve and update the rendered colors/size/launcher
+   * in place. Callers should reuse the same client instance across config
+   * changes so the open animation only fires once.
+   *
+   * @internal
+   */
+  __seedForPreview(config, extras) {
+    const resolved = config ? resolveConfig(config) : this.state.config;
+    if (config) this.userConfig = config;
+    const seededMessages = resolved.welcomeMessage ? [{ role: "bot", content: resolved.welcomeMessage }] : [];
+    const sanitizedBanner = extras && "banner" in extras ? sanitizeIncidentBanner(extras.banner ?? null) : this.state.incidentBanner;
+    this.setState({
+      config: resolved,
+      configLoaded: true,
+      configError: null,
+      readOnly: true,
+      isOpen: true,
+      messages: seededMessages,
+      incidentBanner: sanitizedBanner,
+      // Reset the dismissed flag so toggling the banner on in the dashboard
+      // re-renders it after a previous preview-side dismiss.
+      incidentBannerDismissed: false
+    });
+  }
   // ── Proactive engagement state ─────────────────────────────────────
   triggersRuntime = null;
   preChatFormSubmitted = false;
@@ -1265,6 +1356,7 @@ var CustomerHeroChat = class {
     }
   }
   async sendMessage(message, options) {
+    if (this.state.readOnly) return;
     const trimmed = message.trim();
     const attachmentTokens = options?.attachmentTokens ?? [];
     if (!trimmed || this.state.isLoading) return;
@@ -1817,6 +1909,33 @@ function pickExtension(mime) {
   return "jpg";
 }
 
+// src/theme.ts
+function resolveScheme(colorScheme, prefersDark) {
+  if (colorScheme === "dark") return "dark";
+  if (colorScheme === "light") return "light";
+  return prefersDark ? "dark" : "light";
+}
+function effectiveColors(config, scheme) {
+  if (scheme === "dark") {
+    return {
+      primary: config.primaryColorDark ?? DEFAULTS.primaryColorDark,
+      background: config.backgroundColorDark ?? DEFAULTS.backgroundColorDark,
+      text: config.textColorDark ?? DEFAULTS.textColorDark
+    };
+  }
+  return {
+    primary: config.primaryColor,
+    background: config.backgroundColor,
+    text: config.textColor
+  };
+}
+function sizePreset(size) {
+  return SIZE_PRESETS[size];
+}
+function panelRadius(cornerStyle) {
+  return CORNER_RADIUS[cornerStyle];
+}
+
 // src/screenshot.ts
 var ScreenshotCancelled = class extends Error {
   constructor(message = "Screenshot cancelled") {
@@ -1951,8 +2070,10 @@ async function canvasToBlob(canvas, quality) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CORNER_RADIUS,
   CustomerHeroChat,
   DEFAULTS,
+  SIZE_PRESETS,
   SUPPORTED_LOCALES,
   ScreenshotCancelled,
   ScreenshotUnavailable,
@@ -1960,9 +2081,13 @@ async function canvasToBlob(canvas, quality) {
   captureScreenshot,
   createTranslator,
   detectLocale,
+  effectiveColors,
   evaluate,
   isRtlLocale,
+  panelRadius,
   pickFire,
   resolveLocale,
+  resolveScheme,
+  sizePreset,
   startTriggersRuntime
 });

package/dist/index.d.cts

@@ -35,6 +35,52 @@ interface CustomerHeroChatConfig {
     locale?: string;
     /** Predefined quick-reply options shown before the user sends a message */
     suggestedMessages?: string[];
+    /**
+     * Color scheme. `auto` follows the visitor's OS preference; `light` and
+     * `dark` force a fixed palette. Defaults to `light` when unset.
+     */
+    colorScheme?: "auto" | "light" | "dark";
+    /** Primary color used in dark mode. Only honoured when the effective
+     *  scheme resolves to dark; never auto-derived from `primaryColor`. */
+    primaryColorDark?: string;
+    /** Background color used in dark mode. Only honoured when the effective
+     *  scheme resolves to dark; never auto-derived from `backgroundColor`. */
+    backgroundColorDark?: string;
+    /** Text color used in dark mode. Only honoured when the effective scheme
+     *  resolves to dark; never auto-derived from `textColor`. */
+    textColorDark?: string;
+    /** Widget size preset. Affects launcher diameter, panel dimensions, and
+     *  base font size. Defaults to `default`. */
+    size?: "compact" | "default" | "large";
+    /** Corner radius preset for the chat panel. `soft` ~ small radius,
+     *  `rounded` ~ medium (default), `square` ~ 0. */
+    cornerStyle?: "soft" | "rounded" | "square";
+    /** Launcher (floating bubble) customization. Each field is optional. */
+    launcher?: {
+        /** Custom launcher icon URL. Replaces the default chat-bubble glyph. */
+        iconUrl?: string;
+        /** Optional CTA label shown next to the launcher (turns the bubble into
+         *  a pill). Max 60 characters. */
+        label?: string;
+        /** When true, render a small green dot on the launcher to advertise
+         *  agent availability. The host site is responsible for keeping
+         *  business-hours state in sync; the SDK only renders the dot. */
+        showOnlineDot?: boolean;
+    };
+    /** Pixel offsets so the widget can sit above sticky cookie bars or chat
+     *  CTAs. Each axis defaults to 20 px when unset. Clamped to 0–1000. */
+    offset?: {
+        bottom?: number;
+        side?: number;
+    };
+    /** Z-index override for sites whose overlays clip the widget. Defaults
+     *  to 99999. Capped at 2_000_000_000. */
+    zIndex?: number;
+    /** When false, the input's attach button is hidden so visitors can't
+     *  even attempt an upload (the server enforces the same flag). Defaults
+     *  to true. Per-chatbot, sourced from the public widget config endpoint
+     *  but overrideable on the host. */
+    allowAttachments?: boolean;
 }
 
 interface ResolvedConfig {
@@ -51,6 +97,23 @@ interface ResolvedConfig {
     suggestedMessages: string[];
     /** Per-chatbot overrides for any translation key, optionally per-locale. */
     stringOverrides?: StringOverrides;
+    colorScheme: "auto" | "light" | "dark";
+    primaryColorDark?: string;
+    backgroundColorDark?: string;
+    textColorDark?: string;
+    size: "compact" | "default" | "large";
+    cornerStyle: "soft" | "rounded" | "square";
+    launcher: {
+        iconUrl?: string;
+        label?: string;
+        showOnlineDot: boolean;
+    };
+    offset: {
+        bottom: number;
+        side: number;
+    };
+    zIndex: number;
+    allowAttachments: boolean;
 }
 interface MessageSource {
     index: number;
@@ -303,6 +366,10 @@ interface ChatState {
     /** True when the visitor has dismissed the active banner this session.
      *  Reset whenever a new banner (different content) lands. */
     incidentBannerDismissed: boolean;
+    /** When true, the chat input is disabled and `sendMessage` is a no-op.
+     *  Used by the dashboard preview (and any other host that wants a
+     *  visual-only render). Public API consumers should not set this. */
+    readOnly: boolean;
 }
 
 type Listener = (state: ChatState) => void;
@@ -314,6 +381,21 @@ declare class CustomerHeroChat {
     private identityData;
     t: TranslateFn;
     constructor(config: CustomerHeroChatConfig);
+    /**
+     * Mark the config as loaded and put the client into read-only preview
+     * mode without hitting the API. Used by `@customerhero/react/preview` to
+     * render the widget against a host-supplied config (the dashboard preview
+     * pane). Public API consumers should not call this.
+     *
+     * Pass a config to re-resolve and update the rendered colors/size/launcher
+     * in place. Callers should reuse the same client instance across config
+     * changes so the open animation only fires once.
+     *
+     * @internal
+     */
+    __seedForPreview(config?: CustomerHeroChatConfig, extras?: {
+        banner?: IncidentBanner | null;
+    }): void;
     private triggersRuntime;
     private preChatFormSubmitted;
     private readStoredConsent;
@@ -400,7 +482,78 @@ declare const DEFAULTS: {
     placeholderText: string;
     welcomeMessage: string;
     title: string;
+    colorScheme: "auto" | "light" | "dark";
+    primaryColorDark: string;
+    backgroundColorDark: string;
+    textColorDark: string;
+    size: "compact" | "default" | "large";
+    cornerStyle: "soft" | "rounded" | "square";
+    offsetBottom: number;
+    offsetSide: number;
+    zIndex: number;
+};
+declare const SIZE_PRESETS: {
+    readonly compact: {
+        readonly bubble: 48;
+        readonly width: 320;
+        readonly height: 480;
+        readonly fontSize: 13;
+    };
+    readonly default: {
+        readonly bubble: 56;
+        readonly width: 380;
+        readonly height: 520;
+        readonly fontSize: 14;
+    };
+    readonly large: {
+        readonly bubble: 64;
+        readonly width: 440;
+        readonly height: 600;
+        readonly fontSize: 15;
+    };
+};
+declare const CORNER_RADIUS: {
+    readonly soft: 8;
+    readonly rounded: 16;
+    readonly square: 0;
+};
+
+type EffectiveScheme = "light" | "dark";
+/**
+ * Resolve the configured `colorScheme` against the visitor's OS preference.
+ * `prefersDark` is the live value of `matchMedia("(prefers-color-scheme: dark)")`
+ * (or `false` when not running in a browser). Kept as a pure function so the
+ * caller subscribes once and re-renders.
+ */
+declare function resolveScheme(colorScheme: ResolvedConfig["colorScheme"], prefersDark: boolean): EffectiveScheme;
+/**
+ * Pick the colors that should drive the widget render right now. When the
+ * effective scheme is dark and a dark color is configured, use it; otherwise
+ * fall back to the light color (so half-configured dark mode still ships
+ * something readable rather than a white panel with white text).
+ */
+declare function effectiveColors(config: ResolvedConfig, scheme: EffectiveScheme): {
+    primary: string;
+    background: string;
+    text: string;
+};
+declare function sizePreset(size: ResolvedConfig["size"]): {
+    readonly bubble: 48;
+    readonly width: 320;
+    readonly height: 480;
+    readonly fontSize: 13;
+} | {
+    readonly bubble: 56;
+    readonly width: 380;
+    readonly height: 520;
+    readonly fontSize: 14;
+} | {
+    readonly bubble: 64;
+    readonly width: 440;
+    readonly height: 600;
+    readonly fontSize: 15;
 };
+declare function panelRadius(cornerStyle: ResolvedConfig["cornerStyle"]): 0 | 8 | 16;
 
 declare class ScreenshotCancelled extends Error {
     constructor(message?: string);
@@ -464,4 +617,4 @@ interface StartTriggersRuntimeOptions {
 }
 declare function startTriggersRuntime(options: StartTriggersRuntimeOptions): TriggersRuntimeHandle;
 
-export { type ActionConfirmationBlock, type ChatMessage, type ChatState, type ConsentSettings, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type IncidentBanner, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type PreChatField, type PreChatFieldKind, type PreChatFormConfig, type PreChatSubmission, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, type TriggerAction, type TriggerConditionLeaf, type TriggerConditionNode, type TriggerDefinition, type TriggerFrequency, type TriggersRuntimeHandle, type VisitorContext, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, evaluate, isRtlLocale, pickFire, resolveLocale, startTriggersRuntime };
+export { type ActionConfirmationBlock, CORNER_RADIUS, type ChatMessage, type ChatState, type ConsentSettings, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type EffectiveScheme, type IdentifyPayload, type IdentityData, type IncidentBanner, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type PreChatField, type PreChatFieldKind, type PreChatFormConfig, type PreChatSubmission, type QuickRepliesBlock, type ResolvedConfig, SIZE_PRESETS, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, type TriggerAction, type TriggerConditionLeaf, type TriggerConditionNode, type TriggerDefinition, type TriggerFrequency, type TriggersRuntimeHandle, type VisitorContext, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, effectiveColors, evaluate, isRtlLocale, panelRadius, pickFire, resolveLocale, resolveScheme, sizePreset, startTriggersRuntime };

package/dist/index.d.ts

@@ -35,6 +35,52 @@ interface CustomerHeroChatConfig {
     locale?: string;
     /** Predefined quick-reply options shown before the user sends a message */
     suggestedMessages?: string[];
+    /**
+     * Color scheme. `auto` follows the visitor's OS preference; `light` and
+     * `dark` force a fixed palette. Defaults to `light` when unset.
+     */
+    colorScheme?: "auto" | "light" | "dark";
+    /** Primary color used in dark mode. Only honoured when the effective
+     *  scheme resolves to dark; never auto-derived from `primaryColor`. */
+    primaryColorDark?: string;
+    /** Background color used in dark mode. Only honoured when the effective
+     *  scheme resolves to dark; never auto-derived from `backgroundColor`. */
+    backgroundColorDark?: string;
+    /** Text color used in dark mode. Only honoured when the effective scheme
+     *  resolves to dark; never auto-derived from `textColor`. */
+    textColorDark?: string;
+    /** Widget size preset. Affects launcher diameter, panel dimensions, and
+     *  base font size. Defaults to `default`. */
+    size?: "compact" | "default" | "large";
+    /** Corner radius preset for the chat panel. `soft` ~ small radius,
+     *  `rounded` ~ medium (default), `square` ~ 0. */
+    cornerStyle?: "soft" | "rounded" | "square";
+    /** Launcher (floating bubble) customization. Each field is optional. */
+    launcher?: {
+        /** Custom launcher icon URL. Replaces the default chat-bubble glyph. */
+        iconUrl?: string;
+        /** Optional CTA label shown next to the launcher (turns the bubble into
+         *  a pill). Max 60 characters. */
+        label?: string;
+        /** When true, render a small green dot on the launcher to advertise
+         *  agent availability. The host site is responsible for keeping
+         *  business-hours state in sync; the SDK only renders the dot. */
+        showOnlineDot?: boolean;
+    };
+    /** Pixel offsets so the widget can sit above sticky cookie bars or chat
+     *  CTAs. Each axis defaults to 20 px when unset. Clamped to 0–1000. */
+    offset?: {
+        bottom?: number;
+        side?: number;
+    };
+    /** Z-index override for sites whose overlays clip the widget. Defaults
+     *  to 99999. Capped at 2_000_000_000. */
+    zIndex?: number;
+    /** When false, the input's attach button is hidden so visitors can't
+     *  even attempt an upload (the server enforces the same flag). Defaults
+     *  to true. Per-chatbot, sourced from the public widget config endpoint
+     *  but overrideable on the host. */
+    allowAttachments?: boolean;
 }
 
 interface ResolvedConfig {
@@ -51,6 +97,23 @@ interface ResolvedConfig {
     suggestedMessages: string[];
     /** Per-chatbot overrides for any translation key, optionally per-locale. */
     stringOverrides?: StringOverrides;
+    colorScheme: "auto" | "light" | "dark";
+    primaryColorDark?: string;
+    backgroundColorDark?: string;
+    textColorDark?: string;
+    size: "compact" | "default" | "large";
+    cornerStyle: "soft" | "rounded" | "square";
+    launcher: {
+        iconUrl?: string;
+        label?: string;
+        showOnlineDot: boolean;
+    };
+    offset: {
+        bottom: number;
+        side: number;
+    };
+    zIndex: number;
+    allowAttachments: boolean;
 }
 interface MessageSource {
     index: number;
@@ -303,6 +366,10 @@ interface ChatState {
     /** True when the visitor has dismissed the active banner this session.
      *  Reset whenever a new banner (different content) lands. */
     incidentBannerDismissed: boolean;
+    /** When true, the chat input is disabled and `sendMessage` is a no-op.
+     *  Used by the dashboard preview (and any other host that wants a
+     *  visual-only render). Public API consumers should not set this. */
+    readOnly: boolean;
 }
 
 type Listener = (state: ChatState) => void;
@@ -314,6 +381,21 @@ declare class CustomerHeroChat {
     private identityData;
     t: TranslateFn;
     constructor(config: CustomerHeroChatConfig);
+    /**
+     * Mark the config as loaded and put the client into read-only preview
+     * mode without hitting the API. Used by `@customerhero/react/preview` to
+     * render the widget against a host-supplied config (the dashboard preview
+     * pane). Public API consumers should not call this.
+     *
+     * Pass a config to re-resolve and update the rendered colors/size/launcher
+     * in place. Callers should reuse the same client instance across config
+     * changes so the open animation only fires once.
+     *
+     * @internal
+     */
+    __seedForPreview(config?: CustomerHeroChatConfig, extras?: {
+        banner?: IncidentBanner | null;
+    }): void;
     private triggersRuntime;
     private preChatFormSubmitted;
     private readStoredConsent;
@@ -400,7 +482,78 @@ declare const DEFAULTS: {
     placeholderText: string;
     welcomeMessage: string;
     title: string;
+    colorScheme: "auto" | "light" | "dark";
+    primaryColorDark: string;
+    backgroundColorDark: string;
+    textColorDark: string;
+    size: "compact" | "default" | "large";
+    cornerStyle: "soft" | "rounded" | "square";
+    offsetBottom: number;
+    offsetSide: number;
+    zIndex: number;
+};
+declare const SIZE_PRESETS: {
+    readonly compact: {
+        readonly bubble: 48;
+        readonly width: 320;
+        readonly height: 480;
+        readonly fontSize: 13;
+    };
+    readonly default: {
+        readonly bubble: 56;
+        readonly width: 380;
+        readonly height: 520;
+        readonly fontSize: 14;
+    };
+    readonly large: {
+        readonly bubble: 64;
+        readonly width: 440;
+        readonly height: 600;
+        readonly fontSize: 15;
+    };
+};
+declare const CORNER_RADIUS: {
+    readonly soft: 8;
+    readonly rounded: 16;
+    readonly square: 0;
+};
+
+type EffectiveScheme = "light" | "dark";
+/**
+ * Resolve the configured `colorScheme` against the visitor's OS preference.
+ * `prefersDark` is the live value of `matchMedia("(prefers-color-scheme: dark)")`
+ * (or `false` when not running in a browser). Kept as a pure function so the
+ * caller subscribes once and re-renders.
+ */
+declare function resolveScheme(colorScheme: ResolvedConfig["colorScheme"], prefersDark: boolean): EffectiveScheme;
+/**
+ * Pick the colors that should drive the widget render right now. When the
+ * effective scheme is dark and a dark color is configured, use it; otherwise
+ * fall back to the light color (so half-configured dark mode still ships
+ * something readable rather than a white panel with white text).
+ */
+declare function effectiveColors(config: ResolvedConfig, scheme: EffectiveScheme): {
+    primary: string;
+    background: string;
+    text: string;
+};
+declare function sizePreset(size: ResolvedConfig["size"]): {
+    readonly bubble: 48;
+    readonly width: 320;
+    readonly height: 480;
+    readonly fontSize: 13;
+} | {
+    readonly bubble: 56;
+    readonly width: 380;
+    readonly height: 520;
+    readonly fontSize: 14;
+} | {
+    readonly bubble: 64;
+    readonly width: 440;
+    readonly height: 600;
+    readonly fontSize: 15;
 };
+declare function panelRadius(cornerStyle: ResolvedConfig["cornerStyle"]): 0 | 8 | 16;
 
 declare class ScreenshotCancelled extends Error {
     constructor(message?: string);
@@ -464,4 +617,4 @@ interface StartTriggersRuntimeOptions {
 }
 declare function startTriggersRuntime(options: StartTriggersRuntimeOptions): TriggersRuntimeHandle;
 
-export { type ActionConfirmationBlock, type ChatMessage, type ChatState, type ConsentSettings, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type IncidentBanner, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type PreChatField, type PreChatFieldKind, type PreChatFormConfig, type PreChatSubmission, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, type TriggerAction, type TriggerConditionLeaf, type TriggerConditionNode, type TriggerDefinition, type TriggerFrequency, type TriggersRuntimeHandle, type VisitorContext, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, evaluate, isRtlLocale, pickFire, resolveLocale, startTriggersRuntime };
+export { type ActionConfirmationBlock, CORNER_RADIUS, type ChatMessage, type ChatState, type ConsentSettings, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type EffectiveScheme, type IdentifyPayload, type IdentityData, type IncidentBanner, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type PreChatField, type PreChatFieldKind, type PreChatFormConfig, type PreChatSubmission, type QuickRepliesBlock, type ResolvedConfig, SIZE_PRESETS, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, type TriggerAction, type TriggerConditionLeaf, type TriggerConditionNode, type TriggerDefinition, type TriggerFrequency, type TriggersRuntimeHandle, type VisitorContext, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, effectiveColors, evaluate, isRtlLocale, panelRadius, pickFire, resolveLocale, resolveScheme, sizePreset, startTriggersRuntime };

package/dist/index.js

@@ -7,7 +7,29 @@ var DEFAULTS = {
   position: "bottom-right",
   placeholderText: "Type your message...",
   welcomeMessage: "Hi! How can I help you today?",
-  title: "CustomerHero"
+  title: "CustomerHero",
+  // Appearance pack (B1–B6) defaults.
+  colorScheme: "light",
+  // Dark fallbacks used when the effective scheme is dark and no per-chatbot
+  // dark color is configured. Operators can — and should — override these.
+  primaryColorDark: "#A78BFA",
+  backgroundColorDark: "#0F172A",
+  textColorDark: "#E5E7EB",
+  size: "default",
+  cornerStyle: "rounded",
+  offsetBottom: 20,
+  offsetSide: 20,
+  zIndex: 99999
+};
+var SIZE_PRESETS = {
+  compact: { bubble: 48, width: 320, height: 480, fontSize: 13 },
+  default: { bubble: 56, width: 380, height: 520, fontSize: 14 },
+  large: { bubble: 64, width: 440, height: 600, fontSize: 15 }
+};
+var CORNER_RADIUS = {
+  soft: 8,
+  rounded: 16,
+  square: 0
 };
 
 // src/i18n/locales/en.ts
@@ -975,7 +997,14 @@ function startTriggersRuntime(options) {
 }
 
 // src/client.ts
+function clampInt(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
 function resolveConfig(userConfig, fetched) {
+  const launcherUser = userConfig.launcher ?? {};
+  const launcherFetched = fetched?.launcher ?? {};
+  const offsetUser = userConfig.offset ?? {};
   return {
     chatbotId: userConfig.chatbotId,
     apiBase: userConfig.apiBase ?? DEFAULTS.apiBase,
@@ -988,7 +1017,32 @@ function resolveConfig(userConfig, fetched) {
     title: userConfig.title ?? fetched?.title ?? DEFAULTS.title,
     avatarUrl: userConfig.avatarUrl ?? fetched?.avatarUrl,
     suggestedMessages: userConfig.suggestedMessages ?? fetched?.suggestedMessages ?? [],
-    stringOverrides: fetched?.stringOverrides
+    stringOverrides: fetched?.stringOverrides,
+    // Appearance pack. Color palette + size + corner style + launcher all
+    // come from the server widget_config (with host-side override). The
+    // *runtime* knobs — colorScheme, offset, zIndex — are host-only because
+    // they depend on the page the widget is embedded in, not the chatbot.
+    primaryColorDark: userConfig.primaryColorDark ?? fetched?.primaryColorDark,
+    backgroundColorDark: userConfig.backgroundColorDark ?? fetched?.backgroundColorDark,
+    textColorDark: userConfig.textColorDark ?? fetched?.textColorDark,
+    size: userConfig.size ?? fetched?.size ?? DEFAULTS.size,
+    cornerStyle: userConfig.cornerStyle ?? fetched?.cornerStyle ?? DEFAULTS.cornerStyle,
+    launcher: {
+      iconUrl: launcherUser.iconUrl ?? launcherFetched.iconUrl,
+      label: launcherUser.label ?? launcherFetched.label,
+      showOnlineDot: launcherUser.showOnlineDot ?? launcherFetched.showOnlineDot ?? false
+    },
+    colorScheme: userConfig.colorScheme ?? DEFAULTS.colorScheme,
+    offset: {
+      bottom: clampInt(offsetUser.bottom, 0, 1e3, DEFAULTS.offsetBottom),
+      side: clampInt(offsetUser.side, 0, 1e3, DEFAULTS.offsetSide)
+    },
+    zIndex: clampInt(userConfig.zIndex, 0, 2e9, DEFAULTS.zIndex),
+    // Defaults to true — the widget shows the attach button unless the
+    // chatbot explicitly opts out via widget_config or the host passes
+    // allowAttachments=false. Server still enforces the same flag at the
+    // upload endpoint either way.
+    allowAttachments: userConfig.allowAttachments ?? fetched?.allowAttachments ?? true
   };
 }
 function sanitizeIncidentBanner(input) {
@@ -1078,9 +1132,40 @@ var CustomerHeroChat = class {
       pendingTriggerId: null,
       pendingPrefill: null,
       incidentBanner: null,
-      incidentBannerDismissed: false
+      incidentBannerDismissed: false,
+      readOnly: false
     };
   }
+  /**
+   * Mark the config as loaded and put the client into read-only preview
+   * mode without hitting the API. Used by `@customerhero/react/preview` to
+   * render the widget against a host-supplied config (the dashboard preview
+   * pane). Public API consumers should not call this.
+   *
+   * Pass a config to re-resolve and update the rendered colors/size/launcher
+   * in place. Callers should reuse the same client instance across config
+   * changes so the open animation only fires once.
+   *
+   * @internal
+   */
+  __seedForPreview(config, extras) {
+    const resolved = config ? resolveConfig(config) : this.state.config;
+    if (config) this.userConfig = config;
+    const seededMessages = resolved.welcomeMessage ? [{ role: "bot", content: resolved.welcomeMessage }] : [];
+    const sanitizedBanner = extras && "banner" in extras ? sanitizeIncidentBanner(extras.banner ?? null) : this.state.incidentBanner;
+    this.setState({
+      config: resolved,
+      configLoaded: true,
+      configError: null,
+      readOnly: true,
+      isOpen: true,
+      messages: seededMessages,
+      incidentBanner: sanitizedBanner,
+      // Reset the dismissed flag so toggling the banner on in the dashboard
+      // re-renders it after a previous preview-side dismiss.
+      incidentBannerDismissed: false
+    });
+  }
   // ── Proactive engagement state ─────────────────────────────────────
   triggersRuntime = null;
   preChatFormSubmitted = false;
@@ -1226,6 +1311,7 @@ var CustomerHeroChat = class {
     }
   }
   async sendMessage(message, options) {
+    if (this.state.readOnly) return;
     const trimmed = message.trim();
     const attachmentTokens = options?.attachmentTokens ?? [];
     if (!trimmed || this.state.isLoading) return;
@@ -1778,6 +1864,33 @@ function pickExtension(mime) {
   return "jpg";
 }
 
+// src/theme.ts
+function resolveScheme(colorScheme, prefersDark) {
+  if (colorScheme === "dark") return "dark";
+  if (colorScheme === "light") return "light";
+  return prefersDark ? "dark" : "light";
+}
+function effectiveColors(config, scheme) {
+  if (scheme === "dark") {
+    return {
+      primary: config.primaryColorDark ?? DEFAULTS.primaryColorDark,
+      background: config.backgroundColorDark ?? DEFAULTS.backgroundColorDark,
+      text: config.textColorDark ?? DEFAULTS.textColorDark
+    };
+  }
+  return {
+    primary: config.primaryColor,
+    background: config.backgroundColor,
+    text: config.textColor
+  };
+}
+function sizePreset(size) {
+  return SIZE_PRESETS[size];
+}
+function panelRadius(cornerStyle) {
+  return CORNER_RADIUS[cornerStyle];
+}
+
 // src/screenshot.ts
 var ScreenshotCancelled = class extends Error {
   constructor(message = "Screenshot cancelled") {
@@ -1911,8 +2024,10 @@ async function canvasToBlob(canvas, quality) {
   });
 }
 export {
+  CORNER_RADIUS,
   CustomerHeroChat,
   DEFAULTS,
+  SIZE_PRESETS,
   SUPPORTED_LOCALES,
   ScreenshotCancelled,
   ScreenshotUnavailable,
@@ -1920,9 +2035,13 @@ export {
   captureScreenshot,
   createTranslator,
   detectLocale,
+  effectiveColors,
   evaluate,
   isRtlLocale,
+  panelRadius,
   pickFire,
   resolveLocale,
+  resolveScheme,
+  sizePreset,
   startTriggersRuntime
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customerhero/js",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": false,
   "description": "Framework-agnostic JavaScript client for the CustomerHero chat widget.",
   "keywords": [