@helpai/elements 0.21.0 → 0.22.0

package/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-CA9yYj8Y.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-C-Sv0e6E.js';
 import 'zod';
 
 /**
@@ -978,6 +978,45 @@ interface Endpoints {
     submitForm?: string;
 }
 
+/**
+ * Built-in anonymous usage tracking — utm.gif-style pixel hits that give
+ * the widget OWNER (the site embedding it) insights about how visitors
+ * use the widget: events, pages, devices, locales, funnels.
+ *
+ * Privacy contract (enforced in `src/core/tracking.ts`):
+ *   - never sends message text, form values, or any user content —
+ *     event payloads pass through a static per-event allowlist;
+ *   - the only identifier is the widget's existing anonymous `visitorId`;
+ *   - geo + browser are derived server-side (IP + User-Agent header),
+ *     never collected client-side;
+ *   - `navigator.globalPrivacyControl` / Do-Not-Track force it off
+ *     regardless of config.
+ */
+/** Section: anonymous owner-facing usage tracking. */
+interface TrackingOptions {
+    /**
+     * Master switch. Default `false` — tracking stays off until the
+     * deployment (or the embedding page) explicitly turns it on.
+     */
+    enabled?: boolean;
+    /**
+     * Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`
+     * (e.g. `https://t.help.ai/api/ai-elements/px.gif`).
+     */
+    endpoint?: string;
+    /**
+     * Per-visitor sampling 0..1. `0.25` tracks ~a quarter of visitors
+     * (decided once per page load, so funnels stay intact). Default `1`.
+     */
+    sampleRate?: number;
+}
+/** Post-resolve shape — every field concrete. */
+interface ResolvedTracking {
+    enabled: boolean;
+    endpoint: string;
+    sampleRate: number;
+}
+
 /**
  * The three composing roots: raw input ({@link ChatWidgetOptions}),
  * post-normalisation runtime shape ({@link ResolvedOptions}), and the
@@ -1049,6 +1088,8 @@ interface ChatWidgetOptions {
     forms?: FormsOptions;
     /** Messenger modules (Chat / Home / Messages / Help / News tabs). Server-pushable. */
     modules?: ModulesOptions;
+    /** Anonymous owner-facing usage tracking (pixel hits). Server-pushable. */
+    tracking?: TrackingOptions;
     /**
      * Custom client-side storage adapter. Implements the {@link ClientStorage}
      * interface (`get` / `set` / `remove` / `clear`).
@@ -1148,6 +1189,8 @@ interface ResolvedOptions {
     };
     /** Resolved messenger modules — per-module config + ordered enabled list + default tab. */
     modules: ResolvedModules;
+    /** Resolved anonymous usage tracking. */
+    tracking: ResolvedTracking;
     /** Resolved storage adapter — defaults to `LocalStorageAdapter`. */
     storage: ClientStorage;
     onMessage?: ChatWidgetOptions["onMessage"];
@@ -1175,6 +1218,7 @@ interface ServerConfig {
     features?: FeatureFlags;
     forms?: FormsOptions;
     modules?: ModulesOptions;
+    tracking?: TrackingOptions;
     endpoints?: Endpoints;
 }
 

package/index.mjs

@@ -468,6 +468,11 @@ var DEFAULT_FEATURES = {
   humanInLoop: true
 };
 var DEFAULT_FORMS = { list: [], byTrigger: {} };
+var DEFAULT_TRACKING = {
+  enabled: false,
+  endpoint: `https://t.${BRAND.domain}/api/ai-elements/px.gif`,
+  sampleRate: 1
+};
 var DEFAULT_ENDPOINTS = {
   upload: "/ai/agent/upload-file",
   transcribe: "/ai/agent/transcribe-audio",
@@ -562,6 +567,7 @@ function resolveOptions(rawOpts) {
     poweredBy: resolvePoweredBy(footer.poweredBy),
     composer: resolveComposer(opts.composer),
     modules: resolveModules(opts.modules),
+    tracking: resolveTracking(opts.tracking),
     storage: opts.storage ?? defaultStorage,
     onMessage: opts.onMessage,
     onOpen: opts.onOpen,
@@ -594,6 +600,16 @@ function resolveHaptics(overrides) {
     events: overrides?.events
   };
 }
+function resolveTracking(overrides) {
+  const sampleRate = overrides?.sampleRate ?? DEFAULT_TRACKING.sampleRate;
+  return {
+    enabled: overrides?.enabled ?? DEFAULT_TRACKING.enabled,
+    endpoint: overrides?.endpoint ?? DEFAULT_TRACKING.endpoint,
+    // Clamp instead of reject — a malformed rate must never turn a
+    // disabled tracker on or crash resolve (no Zod on the IIFE path).
+    sampleRate: Math.min(1, Math.max(0, Number.isFinite(sampleRate) ? sampleRate : 1))
+  };
+}
 function resolvePoweredBy(overrides) {
   const brandDefault = {
     text: `Powered by ${BRAND.displayName}`,
@@ -736,6 +752,7 @@ var SECTION_KEYS = [
   "i18n",
   "footer",
   "features",
+  "tracking",
   "endpoints"
 ];
 function mergeServerConfig(user, server) {
@@ -4750,6 +4767,7 @@ function LoadingSpinner({ label }) {
 import { jsx as jsx17, jsxs as jsxs14 } from "preact/jsx-runtime";
 var p15 = BRAND.cssPrefix;
 var STICK_THRESHOLD = 120;
+var INTERACTION_GRACE_MS = 350;
 var DIVIDER_IDLE_MS = 1200;
 function MessageList({
   messagesSig,
@@ -4770,6 +4788,8 @@ function MessageList({
   const hasHydratedRef = useRef5(false);
   const detachedRef = useRef5(false);
   const interactingRef = useRef5(false);
+  const interactionEndedAtRef = useRef5(0);
+  const inInteractionGrace = () => interactingRef.current || performance.now() - interactionEndedAtRef.current < INTERACTION_GRACE_MS;
   const autoPinAtRef = useRef5(0);
   const pinBottom = (el) => {
     autoPinAtRef.current = performance.now();
@@ -4810,7 +4830,7 @@ function MessageList({
       pinBottom(el);
       return;
     }
-    if (detachedRef.current || interactingRef.current) return;
+    if (detachedRef.current || inInteractionGrace()) return;
     const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
     if (distanceFromBottom < STICK_THRESHOLD) pinBottom(el);
   }, [messages.value.length]);
@@ -4820,7 +4840,7 @@ function MessageList({
     const last = messages.value.at(-1);
     if (!last) return;
     const pinIfNear = () => {
-      if (detachedRef.current || interactingRef.current) return;
+      if (detachedRef.current || inInteractionGrace()) return;
       const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
       if (distance < STICK_THRESHOLD * 2) pinBottom(el);
     };
@@ -4870,6 +4890,7 @@ function MessageList({
     };
     const endInteraction = () => {
       interactingRef.current = false;
+      interactionEndedAtRef.current = performance.now();
     };
     const onPointerDown = () => {
       interactingRef.current = true;
@@ -5576,10 +5597,10 @@ function createHomeNav(initialTab, tabs, onSwitch) {
       sig.value = { ...sig.value, activeTab: tab };
       onSwitch?.(tab);
     },
-    push(screen) {
+    push(screen2) {
       const s = sig.value;
       const stack = s.stacks[s.activeTab] ?? [];
-      sig.value = { ...s, stacks: { ...s.stacks, [s.activeTab]: [...stack, screen] } };
+      sig.value = { ...s, stacks: { ...s.stacks, [s.activeTab]: [...stack, screen2] } };
     },
     pop() {
       const s = sig.value;
@@ -7238,6 +7259,118 @@ var EventBus = class {
   }
 };
 
+// src/core/tracking.ts
+var PROTOCOL_VERSION = "1";
+var MAX_HITS_PER_MINUTE = 60;
+var MAX_URL_LENGTH = 2e3;
+var TRACKED = {
+  // Panel lifecycle — the owner's "is the widget used at all" funnel.
+  open: () => void 0,
+  close: () => void 0,
+  expand: (on) => ({ on }),
+  fullscreen: (on) => ({ on }),
+  popOut: () => void 0,
+  // Conversation funnel. `send` is the key conversion; text never rides.
+  send: (p33) => ({ attachments: p33.attachmentCount }),
+  message: (p33) => ({ role: p33.role }),
+  stop: () => void 0,
+  clear: () => void 0,
+  suggestion: () => void 0,
+  toggleHistory: (p33) => ({ view: p33.view }),
+  conversationStarted: () => void 0,
+  // Forms + human-in-the-loop — ids and outcomes, never values.
+  formSubmit: (p33) => ({ formId: p33.formId, skipped: p33.skipped }),
+  toolResult: () => void 0,
+  toolDecision: (p33) => ({ approved: p33.approved }),
+  // Composer / attachments / voice.
+  attach: (p33) => ({ count: p33.count, bytes: p33.totalBytes }),
+  voiceStart: () => void 0,
+  voiceStop: (p33) => ({ ms: p33.durationMs }),
+  voiceCancel: () => void 0,
+  // Preferences — how visitors tune the surface.
+  localeChange: (locale) => ({ locale }),
+  themeChange: (theme) => ({ theme }),
+  textSizeChange: (size) => ({ size }),
+  soundToggle: (p33) => ({ muted: p33.muted }),
+  sidebarToggle: (p33) => ({ collapsed: p33.collapsed }),
+  calloutDismiss: () => void 0,
+  // Health signal only — the error object itself never leaves the page.
+  error: () => void 0
+};
+function privacySignalsOff() {
+  const nav = navigator;
+  return nav.globalPrivacyControl === true || nav.doNotTrack === "1";
+}
+function pageUrl() {
+  return location.origin + location.pathname;
+}
+function referrerOrigin() {
+  try {
+    return document.referrer ? new URL(document.referrer).origin : "";
+  } catch {
+    return "";
+  }
+}
+function createTracker(bus, deps) {
+  const sampleRoll = Math.random();
+  let windowStart = 0;
+  let windowHits = 0;
+  const inflight = /* @__PURE__ */ new Set();
+  const hit = (event, dims) => {
+    const { tracking, publicKey, aiAgentDeploymentId, mode, themeMode } = deps.getOptions();
+    if (!tracking.enabled || privacySignalsOff()) return;
+    if (sampleRoll >= tracking.sampleRate) return;
+    const now = performance.now();
+    if (now - windowStart > 6e4) {
+      windowStart = now;
+      windowHits = 0;
+    }
+    if (++windowHits > MAX_HITS_PER_MINUTE) return;
+    const params = new URLSearchParams();
+    params.set("v", PROTOCOL_VERSION);
+    params.set("e", event);
+    if (publicKey) params.set("pk", publicKey);
+    if (aiAgentDeploymentId) params.set("dep", aiAgentDeploymentId);
+    params.set("vid", deps.getVisitorId());
+    const cid = deps.getConversationId();
+    if (cid) params.set("cid", cid);
+    params.set("url", pageUrl());
+    const ref = referrerOrigin();
+    if (ref) params.set("ref", ref);
+    params.set("sw", String(screen.width));
+    params.set("sh", String(screen.height));
+    params.set("vw", String(innerWidth));
+    params.set("vh", String(innerHeight));
+    params.set("dpr", String(devicePixelRatio));
+    params.set("lang", navigator.language);
+    try {
+      params.set("tz", Intl.DateTimeFormat().resolvedOptions().timeZone);
+    } catch {
+    }
+    params.set("m", mode);
+    params.set("th", themeMode);
+    if (dims) {
+      for (const [k, val] of Object.entries(dims)) {
+        if (val !== void 0) params.set(k, String(val));
+      }
+    }
+    params.set("ts", String(Date.now()));
+    const url = `${tracking.endpoint}?${params}`;
+    if (url.length > MAX_URL_LENGTH) return;
+    const img = new Image(1, 1);
+    inflight.add(img);
+    img.onload = img.onerror = () => inflight.delete(img);
+    img.src = url;
+  };
+  const offs = Object.keys(TRACKED).map(
+    (event) => bus.on(event, (payload) => hit(event, TRACKED[event]?.(payload)))
+  );
+  return () => {
+    for (const off of offs) off();
+    inflight.clear();
+  };
+}
+
 // src/core/hooks.ts
 var log19 = logger.scope("hooks");
 var HOOK_WILDCARD = "*";
@@ -7377,6 +7510,11 @@ function mount(opts) {
     applyResolvedHostAttributes();
     renderApp();
   });
+  const unsubscribeTracker = createTracker(bus, {
+    getOptions: () => currentOptions,
+    getVisitorId: () => persistence.getVisitorId(),
+    getConversationId: () => persistence.loadConversationId()
+  });
   const host = mountResult.hostElement;
   let unsubscribeHooks = null;
   const applyUpdate = (patch) => {
@@ -7426,6 +7564,7 @@ function mount(opts) {
     destroy: () => {
       log20.info("destroy", { widgetId });
       unsubscribeHooks?.();
+      unsubscribeTracker();
       bus.clear();
       render(null, mountResult.appRoot);
       mountResult.destroy();

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.21.0"
+  "version": "0.22.0"
 }

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-CA9yYj8Y.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-C-Sv0e6E.js';
 import { z } from 'zod';
 
 /**
@@ -56,9 +56,9 @@ declare const presentationSchema: z.ZodObject<{
         inset: z.ZodOptional<z.ZodString>;
         initialSize: z.ZodDefault<z.ZodEnum<{
             fullscreen: "fullscreen";
-            normal: "normal";
             expanded: "expanded";
             auto: "auto";
+            normal: "normal";
         }>>;
         autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
     }, z.core.$loose>>;
@@ -148,9 +148,9 @@ declare const launcherSizeSchema: z.ZodEnum<{
 }>;
 type LauncherSize = z.infer<typeof launcherSizeSchema>;
 declare const calloutShapeSchema: z.ZodEnum<{
+    callout: "callout";
     pill: "pill";
     bubble: "bubble";
-    callout: "callout";
 }>;
 type CalloutShape = z.infer<typeof calloutShapeSchema>;
 declare const calloutPositionSchema: z.ZodEnum<{
@@ -162,9 +162,9 @@ type CalloutPosition = z.infer<typeof calloutPositionSchema>;
 declare const launcherCalloutSchema: z.ZodObject<{
     text: z.ZodDefault<z.ZodString>;
     shape: z.ZodDefault<z.ZodEnum<{
+        callout: "callout";
         pill: "pill";
         bubble: "bubble";
-        callout: "callout";
     }>>;
     position: z.ZodDefault<z.ZodEnum<{
         auto: "auto";
@@ -195,9 +195,9 @@ declare const launcherOptionsSchema: z.ZodObject<{
     callout: z.ZodOptional<z.ZodObject<{
         text: z.ZodDefault<z.ZodString>;
         shape: z.ZodDefault<z.ZodEnum<{
+            callout: "callout";
             pill: "pill";
             bubble: "bubble";
-            callout: "callout";
         }>>;
         position: z.ZodDefault<z.ZodEnum<{
             auto: "auto";
@@ -240,9 +240,9 @@ type LauncherOptions = z.infer<typeof launcherOptionsSchema>;
 
 declare const initialSizeSchema: z.ZodEnum<{
     fullscreen: "fullscreen";
-    normal: "normal";
     expanded: "expanded";
     auto: "auto";
+    normal: "normal";
 }>;
 declare const resizeOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -269,9 +269,9 @@ declare const sizeOptionsSchema: z.ZodObject<{
     inset: z.ZodOptional<z.ZodString>;
     initialSize: z.ZodDefault<z.ZodEnum<{
         fullscreen: "fullscreen";
-        normal: "normal";
         expanded: "expanded";
         auto: "auto";
+        normal: "normal";
     }>>;
     autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
 }, z.core.$loose>;
@@ -323,43 +323,43 @@ type FeatureFlags = z.infer<typeof featureFlagsSchema>;
  */
 
 declare const actionNameSchema: z.ZodEnum<{
+    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    close: "close";
-    language: "language";
+    clear: "clear";
     theme: "theme";
+    language: "language";
     textSize: "textSize";
     history: "history";
-    clear: "clear";
     sound: "sound";
 }>;
 type ActionName = z.infer<typeof actionNameSchema>;
 declare const headerActionsSchema: z.ZodArray<z.ZodEnum<{
+    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    close: "close";
-    language: "language";
+    clear: "clear";
     theme: "theme";
+    language: "language";
     textSize: "textSize";
     history: "history";
-    clear: "clear";
     sound: "sound";
 }>>;
 type HeaderActions = z.infer<typeof headerActionsSchema>;
 /** Section wrapper — `actions` list wrapped under `header` in the dashboard form. */
 declare const headerSchema: z.ZodObject<{
     actions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        close: "close";
         expand: "expand";
         fullscreen: "fullscreen";
         popOut: "popOut";
-        close: "close";
-        language: "language";
+        clear: "clear";
         theme: "theme";
+        language: "language";
         textSize: "textSize";
         history: "history";
-        clear: "clear";
         sound: "sound";
     }>>>;
 }, z.core.$loose>;
@@ -375,33 +375,33 @@ type HeaderOptions = z.infer<typeof headerSchema>;
  */
 
 declare const feedbackEventSchema: z.ZodEnum<{
+    voiceStart: "voiceStart";
+    voiceStop: "voiceStop";
     error: "error";
     messageReceived: "messageReceived";
     messageSent: "messageSent";
-    voiceStart: "voiceStart";
-    voiceStop: "voiceStop";
 }>;
 type FeedbackEvent = z.infer<typeof feedbackEventSchema>;
 declare const soundOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     volume: z.ZodDefault<z.ZodNumber>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
 }, z.core.$loose>;
 type SoundOptions = z.infer<typeof soundOptionsSchema>;
 declare const hapticsOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
 }, z.core.$loose>;
 type HapticsOptions = z.infer<typeof hapticsOptionsSchema>;
@@ -410,21 +410,21 @@ declare const feedbackSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         volume: z.ZodDefault<z.ZodNumber>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
     }, z.core.$loose>>;
     haptics: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
@@ -544,16 +544,16 @@ type FooterOptions = z.infer<typeof footerSchema>;
 
 declare const fieldTypeSchema: z.ZodEnum<{
     number: "number";
+    select: "select";
+    textarea: "textarea";
+    time: "time";
     text: "text";
+    checkbox: "checkbox";
+    radio: "radio";
     url: "url";
     email: "email";
     tel: "tel";
     date: "date";
-    time: "time";
-    textarea: "textarea";
-    select: "select";
-    radio: "radio";
-    checkbox: "checkbox";
     multiselect: "multiselect";
 }>;
 type FieldType = z.infer<typeof fieldTypeSchema>;
@@ -578,16 +578,16 @@ declare const formFieldSchema: z.ZodObject<{
     label: z.ZodString;
     type: z.ZodEnum<{
         number: "number";
+        select: "select";
+        textarea: "textarea";
+        time: "time";
         text: "text";
+        checkbox: "checkbox";
+        radio: "radio";
         url: "url";
         email: "email";
         tel: "tel";
         date: "date";
-        time: "time";
-        textarea: "textarea";
-        select: "select";
-        radio: "radio";
-        checkbox: "checkbox";
         multiselect: "multiselect";
     }>;
     placeholder: z.ZodOptional<z.ZodString>;
@@ -638,16 +638,16 @@ declare const formDefSchema: z.ZodObject<{
         label: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
+            select: "select";
+            textarea: "textarea";
+            time: "time";
             text: "text";
+            checkbox: "checkbox";
+            radio: "radio";
             url: "url";
             email: "email";
             tel: "tel";
             date: "date";
-            time: "time";
-            textarea: "textarea";
-            select: "select";
-            radio: "radio";
-            checkbox: "checkbox";
             multiselect: "multiselect";
         }>;
         placeholder: z.ZodOptional<z.ZodString>;
@@ -696,16 +696,16 @@ declare const formsSchema: z.ZodArray<z.ZodObject<{
         label: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
+            select: "select";
+            textarea: "textarea";
+            time: "time";
             text: "text";
+            checkbox: "checkbox";
+            radio: "radio";
             url: "url";
             email: "email";
             tel: "tel";
             date: "date";
-            time: "time";
-            textarea: "textarea";
-            select: "select";
-            radio: "radio";
-            checkbox: "checkbox";
             multiselect: "multiselect";
         }>;
         placeholder: z.ZodOptional<z.ZodString>;
@@ -777,18 +777,18 @@ type I18nOptions = z.infer<typeof i18nSchema>;
  */
 
 declare const moduleLayoutSchema: z.ZodEnum<{
+    home: "home";
     chat: "chat";
     help: "help";
-    home: "home";
     news: "news";
 }>;
 type ModuleLayout = z.infer<typeof moduleLayoutSchema>;
 declare const moduleSchema: z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
+        home: "home";
         chat: "chat";
         help: "help";
-        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -814,9 +814,9 @@ type ModuleOptions = z.infer<typeof moduleSchema>;
 declare const modulesSchema: z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
+        home: "home";
         chat: "chat";
         help: "help";
-        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -840,6 +840,22 @@ declare const modulesSchema: z.ZodArray<z.ZodObject<{
 }, z.core.$loose>>;
 type ModulesOptions = z.infer<typeof modulesSchema>;
 
+/**
+ * Tracking section schema — built-in anonymous usage analytics for the
+ * widget owner (utm.gif-style pixel hits). Off by default; a deployment
+ * turns it on to get event / page / device / locale insights without
+ * wiring its own analytics. No message content or form values ever ride
+ * a hit — payload fields pass a static per-event allowlist in the
+ * runtime tracker.
+ */
+
+declare const trackingSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    endpoint: z.ZodOptional<z.ZodURL>;
+    sampleRate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+type TrackingSettings = z.infer<typeof trackingSchema>;
+
 /**
  * Per-mode widget-settings projection.
  *
@@ -881,4 +897,4 @@ declare const ALL_MODES: readonly Mode[];
  */
 declare function emitJsonSchema(): unknown;
 
-export { ALL_MODES, type ActionName, type AttachmentLimits, type Behavior, type CalloutPosition, type CalloutShape, type ComposerOptions, type FeatureFlags, type FeedbackEvent, type FeedbackOptions, type FieldOption, type FieldType, type FieldValidation, type FooterOptions, type FormCondition, type FormDef, type FormField, type Forms, type HapticsOptions, type HeaderActions, type HeaderOptions, type I18nOptions, type LauncherCallout, type LauncherOptions, type LauncherSize, type LauncherVariant, type Mode, type ModuleLayout, type ModuleOptions, type ModulesOptions, type Position, type PoweredBy, type Presentation, type ResizeOptions, type ResponseMode, type SendButtonOptions, type SizeOptions, type SoundOptions, type StringsOverride, type ThemeOverrides, type ThemePreference, type VoiceMode, actionNameSchema, attachmentLimitsSchema, behaviorSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, emitJsonSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formTriggerSchema, formsSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, voiceModeSchema, widgetSettingsSchemaForMode };
+export { ALL_MODES, type ActionName, type AttachmentLimits, type Behavior, type CalloutPosition, type CalloutShape, type ComposerOptions, type FeatureFlags, type FeedbackEvent, type FeedbackOptions, type FieldOption, type FieldType, type FieldValidation, type FooterOptions, type FormCondition, type FormDef, type FormField, type Forms, type HapticsOptions, type HeaderActions, type HeaderOptions, type I18nOptions, type LauncherCallout, type LauncherOptions, type LauncherSize, type LauncherVariant, type Mode, type ModuleLayout, type ModuleOptions, type ModulesOptions, type Position, type PoweredBy, type Presentation, type ResizeOptions, type ResponseMode, type SendButtonOptions, type SizeOptions, type SoundOptions, type StringsOverride, type ThemeOverrides, type ThemePreference, type TrackingSettings, type VoiceMode, actionNameSchema, attachmentLimitsSchema, behaviorSchema, calloutPositionSchema, calloutShapeSchema, composerOptionsSchema, emitJsonSchema, featureFlagsSchema, feedbackEventSchema, feedbackSchema, fieldOptionSchema, fieldTypeSchema, fieldValidationSchema, footerSchema, formConditionSchema, formDefSchema, formFieldSchema, formTriggerSchema, formsSchema, hapticsOptionsSchema, headerActionsSchema, headerSchema, i18nSchema, initialSizeSchema, launcherCalloutSchema, launcherOptionsSchema, launcherSizeSchema, launcherVariantSchema, modeSchema, moduleLayoutSchema, moduleSchema, modulesSchema, positionSchema, poweredBySchema, presentationSchema, resizeOptionsSchema, responseModeSchema, sendButtonIconSchema, sendButtonOptionsSchema, sendButtonShapeSchema, sendButtonVariantSchema, sizeOptionsSchema, soundOptionsSchema, stringsOverrideSchema, themeFieldSchema, themeOverridesSchema, themePreferenceSchema, toolRefSchema, trackingSchema, voiceModeSchema, widgetSettingsSchemaForMode };