@marketrix.ai/widget 3.8.9 → 3.8.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/README.md +159 -161
  2. package/dist/src/components/MarketrixWidget.d.ts +0 -1
  3. package/dist/src/components/base/Avatar.d.ts +0 -1
  4. package/dist/src/components/base/Badge.d.ts +0 -1
  5. package/dist/src/components/base/Button.d.ts +0 -1
  6. package/dist/src/components/base/Card.d.ts +0 -1
  7. package/dist/src/components/base/Dialog.d.ts +6 -7
  8. package/dist/src/components/base/Flex.d.ts +0 -1
  9. package/dist/src/components/base/Icon.d.ts +0 -1
  10. package/dist/src/components/base/IconButton.d.ts +0 -1
  11. package/dist/src/components/base/Indicator.d.ts +0 -1
  12. package/dist/src/components/base/Menu.d.ts +4 -5
  13. package/dist/src/components/base/Pill.d.ts +0 -1
  14. package/dist/src/components/base/Spinner.d.ts +0 -1
  15. package/dist/src/components/base/Stack.d.ts +0 -1
  16. package/dist/src/components/base/Surface.d.ts +0 -1
  17. package/dist/src/components/base/Text.d.ts +0 -1
  18. package/dist/src/components/base/Textarea.d.ts +0 -1
  19. package/dist/src/components/base/Video.d.ts +0 -1
  20. package/dist/src/components/base/icons.d.ts +0 -1
  21. package/dist/src/components/base/layoutProps.d.ts +0 -1
  22. package/dist/src/components/base/tokens.d.ts +0 -1
  23. package/dist/src/components/base/useDisclosure.d.ts +0 -1
  24. package/dist/src/components/blocks/ChatInput.d.ts +0 -1
  25. package/dist/src/components/blocks/HeaderBar.d.ts +0 -1
  26. package/dist/src/components/blocks/NotificationToast.d.ts +0 -1
  27. package/dist/src/components/blocks/TabBar.d.ts +1 -2
  28. package/dist/src/components/blocks/WidgetDialog.d.ts +0 -1
  29. package/dist/src/components/blocks/WidgetFab.d.ts +0 -1
  30. package/dist/src/components/chat/MessageContent.d.ts +0 -1
  31. package/dist/src/components/chat/MessageItem.d.ts +0 -1
  32. package/dist/src/components/chat/MessageList.d.ts +1 -2
  33. package/dist/src/components/chat/ProgressLine.d.ts +0 -1
  34. package/dist/src/components/chat/SuggestedActions.d.ts +0 -1
  35. package/dist/src/components/chat/TaskStatusIcon.d.ts +0 -1
  36. package/dist/src/components/chat/ThinkingIndicator.d.ts +0 -1
  37. package/dist/src/components/chat/VideoStreamDisplay.d.ts +0 -1
  38. package/dist/src/components/navigation/MessengerShell.d.ts +0 -1
  39. package/dist/src/components/navigation/ResizeHandles.d.ts +0 -1
  40. package/dist/src/components/navigation/ShellTabBar.d.ts +0 -1
  41. package/dist/src/components/navigation/ViewTransition.d.ts +0 -1
  42. package/dist/src/components/ui/StateMessage.d.ts +0 -1
  43. package/dist/src/components/ui/WidgetSettingsLoader.d.ts +1 -2
  44. package/dist/src/components/views/ChatView.d.ts +0 -1
  45. package/dist/src/components/views/HomeView.d.ts +0 -1
  46. package/dist/src/constants/config.d.ts +0 -1
  47. package/dist/src/constants/theme.d.ts +0 -1
  48. package/dist/src/context/ChatContext.d.ts +0 -1
  49. package/dist/src/context/TaskContext.d.ts +0 -1
  50. package/dist/src/context/UIStateContext.d.ts +0 -1
  51. package/dist/src/context/WidgetProviders.d.ts +0 -1
  52. package/dist/src/context/sseReducer.d.ts +0 -1
  53. package/dist/src/design-system/component-tokens.d.ts +0 -1
  54. package/dist/src/design-system/layers.d.ts +0 -1
  55. package/dist/src/design-system/semantic-tokens.d.ts +0 -1
  56. package/dist/src/design-system/shadows.d.ts +0 -1
  57. package/dist/src/design-system/token-adapter.d.ts +0 -1
  58. package/dist/src/hooks/useDragSnap.d.ts +0 -1
  59. package/dist/src/hooks/useFocusTrap.d.ts +0 -1
  60. package/dist/src/hooks/useResize.d.ts +0 -1
  61. package/dist/src/hooks/useScreenShare.d.ts +0 -1
  62. package/dist/src/hooks/useScrollLock.d.ts +0 -1
  63. package/dist/src/hooks/useWidget.d.ts +0 -1
  64. package/dist/src/index.d.ts +0 -1
  65. package/dist/src/lib/utils.d.ts +0 -1
  66. package/dist/src/sdk/contract.d.ts +0 -371
  67. package/dist/src/sdk/contracts/activityLog.d.ts +0 -25
  68. package/dist/src/sdk/contracts/application.d.ts +54 -5
  69. package/dist/src/sdk/contracts/chat.d.ts +0 -1
  70. package/dist/src/sdk/contracts/common.d.ts +10 -14
  71. package/dist/src/sdk/contracts/entities.d.ts +12 -271
  72. package/dist/src/sdk/contracts/widget.d.ts +0 -973
  73. package/dist/src/sdk/index.d.ts +1 -372
  74. package/dist/src/services/ApiService.d.ts +1 -3
  75. package/dist/src/services/ChatService.d.ts +2 -4
  76. package/dist/src/services/ConfigManager.d.ts +0 -1
  77. package/dist/src/services/DomService.d.ts +3 -4
  78. package/dist/src/services/ScreenShareService.d.ts +0 -6
  79. package/dist/src/services/SessionManager.d.ts +0 -1
  80. package/dist/src/services/SessionRecorder.d.ts +0 -1
  81. package/dist/src/services/ShowModeService.d.ts +0 -1
  82. package/dist/src/services/StorageService.d.ts +0 -1
  83. package/dist/src/services/StreamClient.d.ts +0 -2
  84. package/dist/src/services/ToolService.d.ts +3 -4
  85. package/dist/src/services/ValidationService.d.ts +9 -12
  86. package/dist/src/services/WidgetService.d.ts +0 -2
  87. package/dist/src/test/a11y-utils.d.ts +0 -1
  88. package/dist/src/test/fixtures.d.ts +0 -1
  89. package/dist/src/test/setup.d.ts +0 -1
  90. package/dist/src/types/browserTools.d.ts +0 -7
  91. package/dist/src/types/index.d.ts +3 -10
  92. package/dist/src/utils/apiUtils.d.ts +0 -1
  93. package/dist/src/utils/bootstrap.d.ts +0 -1
  94. package/dist/src/utils/chat.d.ts +0 -11
  95. package/dist/src/utils/common.d.ts +0 -1
  96. package/dist/src/utils/dom.d.ts +0 -6
  97. package/dist/src/utils/format.d.ts +0 -1
  98. package/dist/src/utils/suggestedActions.d.ts +0 -1
  99. package/dist/src/utils/validation.d.ts +0 -5
  100. package/dist/src/utils/widgetPositioning.d.ts +0 -1
  101. package/dist/widget.mjs +65 -65
  102. package/dist/widget.mjs.map +1 -1
  103. package/package.json +12 -12
  104. package/dist/index.html +0 -1697
  105. package/dist/src/components/MarketrixWidget.d.ts.map +0 -1
  106. package/dist/src/components/base/Avatar.d.ts.map +0 -1
  107. package/dist/src/components/base/Badge.d.ts.map +0 -1
  108. package/dist/src/components/base/Button.d.ts.map +0 -1
  109. package/dist/src/components/base/Card.d.ts.map +0 -1
  110. package/dist/src/components/base/Dialog.d.ts.map +0 -1
  111. package/dist/src/components/base/Flex.d.ts.map +0 -1
  112. package/dist/src/components/base/Icon.d.ts.map +0 -1
  113. package/dist/src/components/base/IconButton.d.ts.map +0 -1
  114. package/dist/src/components/base/Indicator.d.ts.map +0 -1
  115. package/dist/src/components/base/Menu.d.ts.map +0 -1
  116. package/dist/src/components/base/Pill.d.ts.map +0 -1
  117. package/dist/src/components/base/Spinner.d.ts.map +0 -1
  118. package/dist/src/components/base/Stack.d.ts.map +0 -1
  119. package/dist/src/components/base/Surface.d.ts.map +0 -1
  120. package/dist/src/components/base/Text.d.ts.map +0 -1
  121. package/dist/src/components/base/Textarea.d.ts.map +0 -1
  122. package/dist/src/components/base/Video.d.ts.map +0 -1
  123. package/dist/src/components/base/icons.d.ts.map +0 -1
  124. package/dist/src/components/base/index.d.ts +0 -22
  125. package/dist/src/components/base/index.d.ts.map +0 -1
  126. package/dist/src/components/base/layoutProps.d.ts.map +0 -1
  127. package/dist/src/components/base/tokens.d.ts.map +0 -1
  128. package/dist/src/components/base/useDisclosure.d.ts.map +0 -1
  129. package/dist/src/components/blocks/ChatInput.d.ts.map +0 -1
  130. package/dist/src/components/blocks/HeaderBar.d.ts.map +0 -1
  131. package/dist/src/components/blocks/NotificationToast.d.ts.map +0 -1
  132. package/dist/src/components/blocks/TabBar.d.ts.map +0 -1
  133. package/dist/src/components/blocks/WidgetDialog.d.ts.map +0 -1
  134. package/dist/src/components/blocks/WidgetFab.d.ts.map +0 -1
  135. package/dist/src/components/blocks/index.d.ts +0 -7
  136. package/dist/src/components/blocks/index.d.ts.map +0 -1
  137. package/dist/src/components/chat/MessageContent.d.ts.map +0 -1
  138. package/dist/src/components/chat/MessageItem.d.ts.map +0 -1
  139. package/dist/src/components/chat/MessageList.d.ts.map +0 -1
  140. package/dist/src/components/chat/ProgressLine.d.ts.map +0 -1
  141. package/dist/src/components/chat/SuggestedActions.d.ts.map +0 -1
  142. package/dist/src/components/chat/TaskStatusIcon.d.ts.map +0 -1
  143. package/dist/src/components/chat/ThinkingIndicator.d.ts.map +0 -1
  144. package/dist/src/components/chat/VideoStreamDisplay.d.ts.map +0 -1
  145. package/dist/src/components/navigation/MessengerShell.d.ts.map +0 -1
  146. package/dist/src/components/navigation/ResizeHandles.d.ts.map +0 -1
  147. package/dist/src/components/navigation/ShellTabBar.d.ts.map +0 -1
  148. package/dist/src/components/navigation/ViewTransition.d.ts.map +0 -1
  149. package/dist/src/components/ui/StateMessage.d.ts.map +0 -1
  150. package/dist/src/components/ui/WidgetSettingsLoader.d.ts.map +0 -1
  151. package/dist/src/components/views/ChatView.d.ts.map +0 -1
  152. package/dist/src/components/views/HomeView.d.ts.map +0 -1
  153. package/dist/src/constants/config.d.ts.map +0 -1
  154. package/dist/src/constants/theme.d.ts.map +0 -1
  155. package/dist/src/context/ChatContext.d.ts.map +0 -1
  156. package/dist/src/context/TaskContext.d.ts.map +0 -1
  157. package/dist/src/context/UIStateContext.d.ts.map +0 -1
  158. package/dist/src/context/WidgetProviders.d.ts.map +0 -1
  159. package/dist/src/context/sseReducer.d.ts.map +0 -1
  160. package/dist/src/design-system/component-tokens.d.ts.map +0 -1
  161. package/dist/src/design-system/layers.d.ts.map +0 -1
  162. package/dist/src/design-system/semantic-tokens.d.ts.map +0 -1
  163. package/dist/src/design-system/shadows.d.ts.map +0 -1
  164. package/dist/src/design-system/themes/default.d.ts +0 -7
  165. package/dist/src/design-system/themes/default.d.ts.map +0 -1
  166. package/dist/src/design-system/themes/high-contrast.d.ts +0 -4
  167. package/dist/src/design-system/themes/high-contrast.d.ts.map +0 -1
  168. package/dist/src/design-system/themes/index.d.ts +0 -3
  169. package/dist/src/design-system/themes/index.d.ts.map +0 -1
  170. package/dist/src/design-system/token-adapter.d.ts.map +0 -1
  171. package/dist/src/hooks/useDragSnap.d.ts.map +0 -1
  172. package/dist/src/hooks/useFocusTrap.d.ts.map +0 -1
  173. package/dist/src/hooks/useResize.d.ts.map +0 -1
  174. package/dist/src/hooks/useScreenShare.d.ts.map +0 -1
  175. package/dist/src/hooks/useScrollLock.d.ts.map +0 -1
  176. package/dist/src/hooks/useWidget.d.ts.map +0 -1
  177. package/dist/src/index.d.ts.map +0 -1
  178. package/dist/src/lib/utils.d.ts.map +0 -1
  179. package/dist/src/sdk/contract.d.ts.map +0 -1
  180. package/dist/src/sdk/contracts/activityLog.d.ts.map +0 -1
  181. package/dist/src/sdk/contracts/agent.d.ts +0 -3243
  182. package/dist/src/sdk/contracts/agent.d.ts.map +0 -1
  183. package/dist/src/sdk/contracts/application.d.ts.map +0 -1
  184. package/dist/src/sdk/contracts/chat.d.ts.map +0 -1
  185. package/dist/src/sdk/contracts/common.d.ts.map +0 -1
  186. package/dist/src/sdk/contracts/entities.d.ts.map +0 -1
  187. package/dist/src/sdk/contracts/widget.d.ts.map +0 -1
  188. package/dist/src/sdk/index.d.ts.map +0 -1
  189. package/dist/src/services/ApiService.d.ts.map +0 -1
  190. package/dist/src/services/ChatService.d.ts.map +0 -1
  191. package/dist/src/services/ConfigManager.d.ts.map +0 -1
  192. package/dist/src/services/DomService.d.ts.map +0 -1
  193. package/dist/src/services/ScreenShareService.d.ts.map +0 -1
  194. package/dist/src/services/SessionManager.d.ts.map +0 -1
  195. package/dist/src/services/SessionRecorder.d.ts.map +0 -1
  196. package/dist/src/services/ShowModeService.d.ts.map +0 -1
  197. package/dist/src/services/StorageService.d.ts.map +0 -1
  198. package/dist/src/services/StreamClient.d.ts.map +0 -1
  199. package/dist/src/services/ToolService.d.ts.map +0 -1
  200. package/dist/src/services/ValidationService.d.ts.map +0 -1
  201. package/dist/src/services/WidgetService.d.ts.map +0 -1
  202. package/dist/src/test/a11y-utils.d.ts.map +0 -1
  203. package/dist/src/test/fixtures.d.ts.map +0 -1
  204. package/dist/src/test/setup.d.ts.map +0 -1
  205. package/dist/src/types/browserTools.d.ts.map +0 -1
  206. package/dist/src/types/index.d.ts.map +0 -1
  207. package/dist/src/utils/apiUtils.d.ts.map +0 -1
  208. package/dist/src/utils/bootstrap.d.ts.map +0 -1
  209. package/dist/src/utils/chat.d.ts.map +0 -1
  210. package/dist/src/utils/common.d.ts.map +0 -1
  211. package/dist/src/utils/dom.d.ts.map +0 -1
  212. package/dist/src/utils/format.d.ts.map +0 -1
  213. package/dist/src/utils/suggestedActions.d.ts.map +0 -1
  214. package/dist/src/utils/validation.d.ts.map +0 -1
  215. package/dist/src/utils/widgetPositioning.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,240 +1,238 @@
1
1
  # Marketrix Widget
2
2
 
3
- Embeddable support widget for Marketrix. Integrates into any website via script tag.
3
+ The embeddable Marketrix support widget. Drop it into any web page and your users get an in-product assistant that can **Tell** them how something works, **Show** them step-by-step with on-page highlighting, or **Do** the task for them in the browser.
4
4
 
5
- ## Quick Start
5
+ Published to npm as [`@marketrix.ai/widget`](https://www.npmjs.com/package/@marketrix.ai/widget). Ships as a single ES module (`widget.mjs`) plus a classic `loader.js` bootstrap.
6
+
7
+ > **React 19 is required.** The widget treats `react` and `react-dom` as **peer dependencies** and does not bundle them — the host page must provide React 19. The script-tag loader injects a React 19 importmap for you; npm consumers already have React in their app.
8
+
9
+ ---
10
+
11
+ ## Install
12
+
13
+ There are two integration paths. Most sites should use the **script tag** — it's the simplest and provides React for you.
14
+
15
+ ### 1. Script tag (recommended)
16
+
17
+ Add one `<script>` to your page `<head>`, **before any `<script type="module">` tags** (the loader installs the React importmap that your module scripts rely on):
6
18
 
7
19
  ```html
8
20
  <script
9
21
  src="https://widget.marketrix.ai/loader.js"
10
- mtx-api-host="https://api.marketrix.ai"
11
22
  mtx-id="your-marketrix-id"
12
23
  mtx-key="your-marketrix-key"
24
+ mtx-api-host="https://api.marketrix.ai"
13
25
  ></script>
14
26
  ```
15
27
 
16
- ## Configuration Options
17
-
18
- ### Script Attributes
28
+ `loader.js`:
19
29
 
20
- | Attribute | Type | Required | Description |
21
- | -------------- | ------ | -------- | ------------------------------------------------- |
22
- | `mtx-id` | string | \* | Your Marketrix ID (production mode) |
23
- | `mtx-key` | string | \* | Your Marketrix API key (production mode) |
24
- | `mtx-app` | number | \* | Application ID (dev mode) |
25
- | `mtx-agent` | number | \* | Agent ID (dev mode) |
26
- | `mtx-api-host` | string | yes | API server URL (e.g., `https://api.marketrix.ai`) |
30
+ 1. Injects a React 19 importmap (defaults to `esm.sh/react@19`). If your page already has an importmap, the loader **merges** it and your mappings win — so a host that already ships React 19 keeps its own copy.
31
+ 2. Injects `<script type="module" src=".../widget.mjs">` from the same origin as the loader.
32
+ 3. Forwards every `mtx-*` attribute from the loader tag to the widget.
27
33
 
28
- \*Either `mtx-id` + `mtx-key` (production) OR `mtx-app` + `mtx-agent` (dev) must be provided.
34
+ The widget then **auto-initializes** from those attributes no extra JavaScript required.
29
35
 
30
- ### Widget Settings
36
+ ### 2. npm / programmatic
31
37
 
32
- Widget appearance and behavior are configured through the API. Settings include position, colors, border radius, dimensions, enabled features, device visibility, header/body/greeting text, and quick-action chips.
33
-
34
- ## Interaction Modes
35
-
36
- **Tell**: the agent explains concepts and answers questions. **Show**: the agent demonstrates tasks with step-by-step guidance and visual highlighting. **Do**: the agent performs actions in the browser on the user's behalf.
37
-
38
- ## Programmatic Usage
39
-
40
- ### `initWidget`
38
+ ```bash
39
+ npm install @marketrix.ai/widget
40
+ # react@^19.2.3 and react-dom@^19.2.3 must already be installed in your app
41
+ ```
41
42
 
42
- ```typescript
43
- import {
44
- initWidget,
45
- unmountWidget,
46
- updateMarketrixConfig,
47
- startRecording,
48
- stopRecording,
49
- getRecordingState,
50
- } from '@marketrix.ai/widget';
43
+ ```ts
44
+ import { mountWidget } from '@marketrix.ai/widget';
51
45
 
52
- // Production
53
- await initWidget({
46
+ await mountWidget({
54
47
  mtxId: 'your-marketrix-id',
55
48
  mtxKey: 'your-marketrix-key',
56
49
  mtxApiHost: 'https://api.marketrix.ai',
57
50
  });
51
+ ```
58
52
 
59
- // Dev
60
- await initWidget({
61
- mtxApp: 123,
62
- mtxAgent: 456,
63
- mtxApiHost: 'https://api.marketrix.ai',
64
- });
53
+ `mountWidget` auto-detects the credential mode (production / dev / preview) from the config you pass.
65
54
 
66
- // Mount into a specific container
67
- await initWidget(config, document.getElementById('my-container')!);
55
+ ---
68
56
 
69
- // Update config at runtime (unmounts and reinitializes)
70
- await updateMarketrixConfig({ mtxApiHost: 'https://new-api.marketrix.ai' });
57
+ ## Credential modes
71
58
 
72
- // Session recording
73
- await startRecording();
74
- stopRecording();
75
- const isRecording = getRecordingState();
59
+ The widget supports three modes, auto-detected from the credentials you provide.
76
60
 
77
- // Destroy widget
78
- unmountWidget();
79
- ```
61
+ | Mode | Credentials | Script attributes | Network |
62
+ | -------------- | -------------------------------- | -------------------- | --------------------------------------------------------------- |
63
+ | **Production** | `mtxId` + `mtxKey` | `mtx-id` + `mtx-key` | Fetches settings from the API, opens the live stream |
64
+ | **Dev** | `mtxApp` (application id) | `mtx-app` | Same as production, keyed by id instead of credentials |
65
+ | **Preview** | `settings` object passed in code | — | No network — renders appearance only from the supplied settings |
80
66
 
81
- ### React Component (Preview Mode)
67
+ All modes also accept the common options below.
82
68
 
83
- ```tsx
84
- import { MarketrixWidget } from '@marketrix.ai/widget';
69
+ ---
85
70
 
86
- function App() {
87
- return (
88
- <MarketrixWidget
89
- settings={{ widget_enabled: true, widget_position: 'bottom_right' /* ... */ }}
90
- mtxApiHost='https://api.marketrix.ai'
91
- />
92
- );
93
- }
94
- ```
71
+ ## Configuration options
95
72
 
96
- ## API Reference
73
+ These apply to every mode (script attribute → config key):
97
74
 
98
- #### `initWidget(config: MarketrixConfig, container?: HTMLElement): Promise<void>`
75
+ | Config key | Script attribute | Type | Description |
76
+ | ----------------- | --------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
77
+ | `mtxApiHost` | `mtx-api-host` | string | API server URL, e.g. `https://api.marketrix.ai`. The widget has no baked-in API host — you must supply it. |
78
+ | `container` | — | `HTMLElement` | Element to mount inside (programmatic only). Defaults to a container appended to `<body>`. |
79
+ | `userId` | — | number | Associates widget activity with one of your users. |
80
+ | `show_widget` | — | boolean | When `false`, the widget initializes fully but its UI stays hidden. Default `true`. |
81
+ | `use_screenshare` | `mtx-use-screenshare` | boolean | When `false`, screen-share requests are auto-denied and the Share Screen button is hidden. Default `true`. Disable via `mtx-use-screenshare="false"`. |
99
82
 
100
- Validates credentials, fetches settings from the API, and mounts the widget. Concurrent and duplicate calls are deduplicated.
83
+ Widget **appearance and behavior** (position, colors, sizing, border radius, animation, enabled Tell/Show/Do/Human features, device visibility, header/body/greeting text, and quick-action chips) are configured in the Marketrix dashboard and fetched from the API at init. You don't set them in the embed — except in preview mode, where you pass them inline as `settings`.
101
84
 
102
- #### `unmountWidget(): void`
85
+ ### Full script-tag example
103
86
 
104
- Destroys the widget, stops session recording, and cleans up all resources including the SSE stream connection.
87
+ ```html
88
+ <!doctype html>
89
+ <html>
90
+ <head>
91
+ <script
92
+ src="https://widget.marketrix.ai/loader.js"
93
+ mtx-id="your-marketrix-id"
94
+ mtx-key="your-marketrix-key"
95
+ mtx-api-host="https://api.marketrix.ai"
96
+ mtx-use-screenshare="false"
97
+ ></script>
98
+ </head>
99
+ <body>
100
+ <!-- your app -->
101
+ </body>
102
+ </html>
103
+ ```
105
104
 
106
- #### `mountWidget(config: AddWidgetConfig): Promise<void>`
105
+ The loader takes care of the React 19 importmap. If you manage your own importmap, place it before the loader and the loader will merge (and defer to) it:
107
106
 
108
- Auto-detects mode (preview, production, or dev) and initializes the widget.
107
+ ```html
108
+ <script type="importmap">
109
+ {
110
+ "imports": {
111
+ "react": "https://esm.sh/react@19",
112
+ "react-dom": "https://esm.sh/react-dom@19",
113
+ "react-dom/client": "https://esm.sh/react-dom@19/client",
114
+ "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime"
115
+ }
116
+ }
117
+ </script>
118
+ <script src="https://widget.marketrix.ai/loader.js" mtx-id="..." mtx-key="..." mtx-api-host="..."></script>
119
+ ```
109
120
 
110
- #### `getCurrentConfig(): MarketrixConfig | null`
121
+ ---
111
122
 
112
- Returns the current widget configuration, or `null` if not initialized.
123
+ ## Programmatic API
113
124
 
114
- #### `updateMarketrixConfig(newConfig: Partial<MarketrixConfig>): Promise<void>`
125
+ All functions are named exports of `@marketrix.ai/widget` (also available on the default export).
115
126
 
116
- Updates the widget configuration at runtime. Unmounts the current widget and reinitializes with the merged config.
127
+ ```ts
128
+ import {
129
+ mountWidget,
130
+ initWidget,
131
+ unmountWidget,
132
+ updateMarketrixConfig,
133
+ getCurrentConfig,
134
+ startRecording,
135
+ stopRecording,
136
+ getRecordingState,
137
+ MarketrixWidget,
138
+ } from '@marketrix.ai/widget';
139
+ ```
117
140
 
118
- #### `startRecording(): Promise<void>`
141
+ ### `mountWidget(config): Promise<void>`
119
142
 
120
- Starts RRWeb session recording. Throws if the widget was not initialized with `mtxApiHost` and `mtxApp`.
143
+ Auto-detects the mode (preview / production / dev) from `config` and initializes the widget. The recommended entry point for programmatic use.
121
144
 
122
- #### `stopRecording(): void`
145
+ ```ts
146
+ // Production
147
+ await mountWidget({ mtxId, mtxKey, mtxApiHost });
123
148
 
124
- Stops RRWeb session recording without unmounting the widget.
149
+ // Dev
150
+ await mountWidget({ mtxApp: 123, mtxApiHost });
125
151
 
126
- #### `getRecordingState(): boolean`
152
+ // Preview (no network — just renders the appearance)
153
+ await mountWidget({ settings: { widget_enabled: true, widget_position: 'bottom_right' /* ... */ } });
154
+ ```
127
155
 
128
- Returns whether RRWeb session recording is currently active.
156
+ ### `initWidget(config, container?): Promise<void>`
129
157
 
130
- #### `MarketrixWidget` (React Component)
158
+ Lower-level production/dev initializer. Validates credentials, fetches settings from the API, mounts into a closed Shadow DOM, opens the event stream, and starts session recording once a chat id exists. Optionally mounts inside a specific `container`. Concurrent and duplicate calls are deduplicated; only one production widget runs per page.
131
159
 
132
- React component for preview mode rendering. Accepts `settings`, `container`, `mtxId`, `mtxKey`, and `mtxApiHost` props.
160
+ ```ts
161
+ await initWidget({ mtxId, mtxKey, mtxApiHost }, document.getElementById('my-container')!);
162
+ ```
133
163
 
134
- ## Exported Types
164
+ ### `unmountWidget(): void`
135
165
 
136
- ```typescript
137
- interface MarketrixConfig {
138
- mtxId?: string;
139
- mtxKey?: string;
140
- mtxApp?: number;
141
- mtxAgent?: number;
142
- mtxApiHost?: string;
143
- userId?: number;
144
- widget_position_offset?: { x?: number; y?: number };
145
- widget_position_z_index?: number;
146
- isPreviewMode?: boolean;
147
- // All WidgetSettingsData fields (optional)
148
- }
149
- ```
166
+ Destroys the widget, stops session recording, closes the stream connection, and cleans up all resources.
150
167
 
151
- ## Development
168
+ ### `updateMarketrixConfig(partial): Promise<void>`
152
169
 
153
- ### Prerequisites
170
+ Merges `partial` into the current config and re-initializes (unmount + `initWidget`). Use to switch API host, credentials, etc. at runtime.
154
171
 
155
- | Workflow | Trigger | Action |
156
- | -------------- | -------------------------------- | ------------------------------------------------------------------- |
157
- | `validate.yml` | Push / PR to `dev`, `main` | Type check, lint, format, tests, build, visual, a11y, bundle checks |
158
- | `build.yml` | Tag push (`v*`) or push to `dev` | Build Docker image, push to ACR; publish to npm on tag |
172
+ ### `getCurrentConfig(): MarketrixConfig | null`
159
173
 
160
- Image builds produce `marketrix.azurecr.io/widget:{version}`. Tag pushes also publish `@marketrix.ai/widget` to npm. Deployment to dev/prod is handled by the centralized deploy workflow (e.g. `deploy.yml` in infra). Dev branch pushes do not build images.
174
+ Returns the active configuration, or `null` if the widget isn't initialized.
161
175
 
162
- - Node.js 18+
163
- - npm
176
+ ### Session recording
164
177
 
165
- ### Setup
178
+ The widget records user sessions (via rrweb) automatically once initialized. These helpers let you control it:
166
179
 
167
- ```bash
168
- git clone <repository-url>
169
- cd widget
170
- npm install
171
- npm start # dev server on port 5174
172
- npm run build # production build
173
- ```
180
+ - `startRecording(): Promise<void>` — start or resume recording. Throws if the widget wasn't initialized with `mtxApiHost` and an application (`mtxApp`).
181
+ - `stopRecording(): void` — pause recording without unmounting the widget.
182
+ - `getRecordingState(): boolean` — whether recording is currently active.
174
183
 
175
- ### Project Structure
184
+ ### `MarketrixWidget` — React component (preview)
176
185
 
177
- ```
178
- widget/
179
- ├── src/
180
- │ ├── components/ # React components (chat, layout, UI, input)
181
- │ ├── context/ # WidgetContext provider
182
- │ ├── hooks/ # Custom React hooks
183
- │ ├── services/ # Core services (stream, chat, recording, etc.)
184
- │ ├── sdk/ # oRPC client + contract mirrors
185
- │ ├── types/ # TypeScript types
186
- │ ├── utils/ # Utility functions
187
- │ ├── constants/ # Config constants and theme tokens
188
- │ └── index.tsx # Main entry point
189
- ├── vite.config.ts
190
- ├── tsconfig.json
191
- └── package.json
186
+ For previewing appearance inside a React app (e.g. a settings/configuration screen). Renders into its own Shadow DOM and makes no network calls.
187
+
188
+ ```tsx
189
+ import { MarketrixWidget } from '@marketrix.ai/widget';
190
+
191
+ function Preview() {
192
+ return (
193
+ <MarketrixWidget
194
+ settings={{ widget_enabled: true, widget_position: 'bottom_right' /* ...WidgetSettingsData */ }}
195
+ mtxApiHost='https://api.marketrix.ai'
196
+ />
197
+ );
198
+ }
192
199
  ```
193
200
 
194
- ## Build System
201
+ Props: `settings` (required), `container?`, `mtxId?`, `mtxKey?`, `mtxApiHost?`.
195
202
 
196
- Vite with CSS injection, Shadow DOM isolation, ESM format, TypeScript declarations, and Terser minification.
203
+ ---
197
204
 
198
- Output files:
205
+ ## Interaction modes
199
206
 
200
- - `dist/widget.mjs`Library build (React as peer dependency)
201
- - `dist/loader.js`Classic loader script (loads widget.mjs with configured attributes)
207
+ - **Tell**the agent explains concepts and answers questions in chat.
208
+ - **Show**the agent walks the user through a task step-by-step, highlighting the relevant elements on the page.
209
+ - **Do** — the agent performs the actions in the browser on the user's behalf.
202
210
 
203
- ## CI/CD
211
+ ---
204
212
 
205
- | Workflow | Trigger | Action |
206
- | -------------- | ------------------ | ----------------------------------------------- |
207
- | `validate.yml` | Push to `dev` / PR | Type check, lint, build |
208
- | `build.yml` | Tag push (`v*`) | Build Docker image, push to ACR, publish to npm |
213
+ ## Exported types
209
214
 
210
- ## Dependencies
215
+ TypeScript types are bundled with the package:
211
216
 
212
- ### Production
217
+ - `MarketrixConfig` — full config for `initWidget` / `updateMarketrixConfig` (`mtxId`, `mtxKey`, `mtxApp`, `mtxApiHost`, `userId`, `show_widget`, `use_screenshare`, plus all widget appearance settings, optional).
218
+ - `AddWidgetConfig` — discriminated config for `mountWidget` (production / dev / preview variants + common options).
219
+ - `MarketrixWidgetProps` — props for the `MarketrixWidget` component.
220
+ - `ChatMessage`, `WidgetState`, `InstructionType` (`'tell' | 'show' | 'do'`).
213
221
 
214
- - `react` / `react-dom` v19 (peer dependency)
215
- - `@rrweb/record` - Session recording
216
- - `@orpc/client` / `@orpc/contract` v1 - Type-safe API client (oRPC)
217
- - `react-icons` - Icons
218
- - `zod` - Schema validation
222
+ ---
219
223
 
220
- ### Development
224
+ ## Requirements
221
225
 
222
- - Vite 6
223
- - Tailwind CSS v4 (via `@tailwindcss/vite` plugin)
224
- - TypeScript 5
225
- - Vitest + Testing Library (unit and integration tests)
226
- - ESLint + Prettier
227
- - Terser for production minification
226
+ - **React 19** (`react`/`react-dom` `^19.2.3`) on the host page — peer dependency, not bundled. The script-tag loader provides it via importmap; npm consumers supply it from their app.
227
+ - A reachable Marketrix API host (`mtxApiHost` / `mtx-api-host`).
228
+ - Valid credentials for production (`mtxId` + `mtxKey`) or dev (`mtxApp`) mode.
228
229
 
229
- **Quality gates (run before PR):** `npm run type-check`, `npm run lint:check`, `npm run format:check`, `npm run test:run`, `npm run build`, `npm run visual:check`, `npm run a11y:check`, `npm run bundle:check`. See `.github/pull_request_template.md` and `docs/release-ui-checklist.md`.
230
+ ---
230
231
 
231
232
  ## License
232
233
 
233
- Apache License 2.0 - see LICENSE file for details.
234
+ Apache License 2.0 see the `LICENSE` file.
234
235
 
235
236
  ## Support
236
237
 
237
- For support and questions, please contact the Marketrix team or create an issue
238
- in the repository.
239
-
240
- [Back to top](#marketrix-in-app-support-widget)
238
+ Contact the Marketrix team or open an issue in the repository.
@@ -5,4 +5,3 @@ interface MarketrixWidgetProps {
5
5
  }
6
6
  export declare const MarketrixWidget: React.FC<MarketrixWidgetProps>;
7
7
  export {};
8
- //# sourceMappingURL=MarketrixWidget.d.ts.map
@@ -11,4 +11,3 @@ export interface AvatarProps extends Omit<React.ImgHTMLAttributes<HTMLImageEleme
11
11
  }
12
12
  export declare const Avatar: import("react").ForwardRefExoticComponent<AvatarProps & import("react").RefAttributes<HTMLImageElement>>;
13
13
  export {};
14
- //# sourceMappingURL=Avatar.d.ts.map
@@ -9,4 +9,3 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
9
9
  }
10
10
  export declare const Badge: import("react").ForwardRefExoticComponent<BadgeProps & import("react").RefAttributes<HTMLSpanElement>>;
11
11
  export {};
12
- //# sourceMappingURL=Badge.d.ts.map
@@ -14,4 +14,3 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
14
14
  }
15
15
  export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
16
16
  export {};
17
- //# sourceMappingURL=Button.d.ts.map
@@ -14,4 +14,3 @@ export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
14
14
  * Used for: recent conversation card, help about card, chat input container, etc.
15
15
  */
16
16
  export declare const Card: import("react").ForwardRefExoticComponent<CardProps & import("react").RefAttributes<HTMLDivElement>>;
17
- //# sourceMappingURL=Card.d.ts.map
@@ -8,20 +8,19 @@ interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement> {
8
8
  children: React.ReactNode;
9
9
  variant?: 'default' | 'confirm' | 'info';
10
10
  }
11
- export declare function Dialog({ children, defaultOpen, onOpenChange, open }: DialogProps): import("react/jsx-runtime").JSX.Element;
12
- export declare function DialogTrigger({ children, onClick, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>): import("react/jsx-runtime").JSX.Element;
13
- export declare function DialogContent({ children, className, onKeyDown, ...props }: DialogContentProps): import("react/jsx-runtime").JSX.Element | null;
11
+ export declare function Dialog({ children, defaultOpen, onOpenChange, open }: DialogProps): import("react").JSX.Element;
12
+ export declare function DialogTrigger({ children, onClick, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;
13
+ export declare function DialogContent({ children, className, onKeyDown, ...props }: DialogContentProps): import("react").JSX.Element | null;
14
14
  interface DialogTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
15
15
  variant?: 'default' | 'confirm' | 'info';
16
16
  }
17
- export declare function DialogTitle({ className, variant, ...props }: DialogTitleProps): import("react/jsx-runtime").JSX.Element;
17
+ export declare function DialogTitle({ className, variant, ...props }: DialogTitleProps): import("react").JSX.Element;
18
18
  interface DialogDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
19
19
  variant?: 'default' | 'confirm';
20
20
  }
21
- export declare function DialogDescription({ className, variant, ...props }: DialogDescriptionProps): import("react/jsx-runtime").JSX.Element;
21
+ export declare function DialogDescription({ className, variant, ...props }: DialogDescriptionProps): import("react").JSX.Element;
22
22
  interface DialogCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
23
23
  variant?: 'default' | 'info';
24
24
  }
25
- export declare function DialogClose({ children, className, onClick, variant, ...props }: DialogCloseProps): import("react/jsx-runtime").JSX.Element;
25
+ export declare function DialogClose({ children, className, onClick, variant, ...props }: DialogCloseProps): import("react").JSX.Element;
26
26
  export {};
27
- //# sourceMappingURL=Dialog.d.ts.map
@@ -14,4 +14,3 @@ export interface FlexProps extends SurfaceProps {
14
14
  children?: ReactNode;
15
15
  }
16
16
  export declare const Flex: import("react").ForwardRefExoticComponent<FlexProps & import("react").RefAttributes<HTMLElement>>;
17
- //# sourceMappingURL=Flex.d.ts.map
@@ -6,4 +6,3 @@ export interface IconProps extends React.SVGAttributes<SVGElement> {
6
6
  className?: string;
7
7
  }
8
8
  export declare const Icon: import("react").ForwardRefExoticComponent<IconProps & import("react").RefAttributes<SVGSVGElement>>;
9
- //# sourceMappingURL=Icon.d.ts.map
@@ -15,4 +15,3 @@ export interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonEl
15
15
  }
16
16
  export declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
17
17
  export {};
18
- //# sourceMappingURL=IconButton.d.ts.map
@@ -7,4 +7,3 @@ export interface IndicatorProps {
7
7
  }
8
8
  export declare const Indicator: React.FC<IndicatorProps>;
9
9
  export {};
10
- //# sourceMappingURL=Indicator.d.ts.map
@@ -10,9 +10,8 @@ interface MenuTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
10
10
  interface MenuItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
11
11
  children: React.ReactNode;
12
12
  }
13
- export declare function Menu({ children, defaultOpen, onOpenChange, open }: MenuProps): import("react/jsx-runtime").JSX.Element;
14
- export declare function MenuTrigger({ children, className, onClick, ...props }: MenuTriggerProps): import("react/jsx-runtime").JSX.Element;
15
- export declare function MenuContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element | null;
16
- export declare function MenuItem({ children, className, onClick, ...props }: MenuItemProps): import("react/jsx-runtime").JSX.Element;
13
+ export declare function Menu({ children, defaultOpen, onOpenChange, open }: MenuProps): import("react").JSX.Element;
14
+ export declare function MenuTrigger({ children, className, onClick, ...props }: MenuTriggerProps): import("react").JSX.Element;
15
+ export declare function MenuContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): import("react").JSX.Element | null;
16
+ export declare function MenuItem({ children, className, onClick, ...props }: MenuItemProps): import("react").JSX.Element;
17
17
  export {};
18
- //# sourceMappingURL=Menu.d.ts.map
@@ -7,4 +7,3 @@ export interface PillProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonEle
7
7
  }
8
8
  export declare const Pill: import("react").ForwardRefExoticComponent<PillProps & import("react").RefAttributes<HTMLButtonElement>>;
9
9
  export {};
10
- //# sourceMappingURL=Pill.d.ts.map
@@ -9,4 +9,3 @@ export interface SpinnerProps {
9
9
  }
10
10
  export declare const Spinner: import("react").ForwardRefExoticComponent<SpinnerProps & import("react").RefAttributes<HTMLDivElement>>;
11
11
  export {};
12
- //# sourceMappingURL=Spinner.d.ts.map
@@ -13,4 +13,3 @@ export interface StackProps extends LayoutProps, Omit<React.HTMLAttributes<HTMLD
13
13
  children?: ReactNode;
14
14
  }
15
15
  export declare const Stack: import("react").ForwardRefExoticComponent<StackProps & import("react").RefAttributes<HTMLDivElement>>;
16
- //# sourceMappingURL=Stack.d.ts.map
@@ -16,4 +16,3 @@ export interface SurfaceProps extends LayoutProps, Omit<React.HTMLAttributes<HTM
16
16
  export declare const backgroundClasses: Record<SurfaceBackground, string>;
17
17
  export declare const paddingPresetClasses: Record<SurfacePadding, string>;
18
18
  export declare const Surface: import("react").ForwardRefExoticComponent<SurfaceProps & import("react").RefAttributes<HTMLElement>>;
19
- //# sourceMappingURL=Surface.d.ts.map
@@ -23,4 +23,3 @@ export interface TextProps extends React.HTMLAttributes<HTMLElement> {
23
23
  }
24
24
  export declare const Text: import("react").ForwardRefExoticComponent<TextProps & import("react").RefAttributes<HTMLElement>>;
25
25
  export {};
26
- //# sourceMappingURL=Text.d.ts.map
@@ -7,4 +7,3 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
7
7
  }
8
8
  export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaProps & import("react").RefAttributes<HTMLTextAreaElement>>;
9
9
  export {};
10
- //# sourceMappingURL=Textarea.d.ts.map
@@ -1,3 +1,2 @@
1
1
  export type VideoProps = React.VideoHTMLAttributes<HTMLVideoElement>;
2
2
  export declare const Video: import("react").ForwardRefExoticComponent<VideoProps & import("react").RefAttributes<HTMLVideoElement>>;
3
- //# sourceMappingURL=Video.d.ts.map
@@ -516,4 +516,3 @@ export declare const icons: {
516
516
  };
517
517
  };
518
518
  export type IconName = keyof typeof icons;
519
- //# sourceMappingURL=icons.d.ts.map
@@ -38,4 +38,3 @@ export interface LayoutProps {
38
38
  }
39
39
  export declare function resolveLayoutClasses(props: LayoutProps): string;
40
40
  export declare function stripLayoutProps<T extends LayoutProps>(props: T): Omit<T, keyof LayoutProps>;
41
- //# sourceMappingURL=layoutProps.d.ts.map
@@ -1,3 +1,2 @@
1
1
  export type SpacingToken = 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
2
2
  export declare const spacingScale: Record<SpacingToken, string>;
3
- //# sourceMappingURL=tokens.d.ts.map
@@ -9,4 +9,3 @@ interface UseDisclosureResult {
9
9
  }
10
10
  export declare function useDisclosure({ defaultOpen, onOpenChange, open }: UseDisclosureProps): UseDisclosureResult;
11
11
  export {};
12
- //# sourceMappingURL=useDisclosure.d.ts.map
@@ -18,4 +18,3 @@ export interface ChatInputProps {
18
18
  placeholder?: string;
19
19
  }
20
20
  export declare const ChatInput: React.ForwardRefExoticComponent<ChatInputProps & React.RefAttributes<HTMLTextAreaElement>>;
21
- //# sourceMappingURL=ChatInput.d.ts.map
@@ -8,4 +8,3 @@ export interface HeaderBarProps {
8
8
  controls?: React.ReactNode;
9
9
  }
10
10
  export declare const HeaderBar: React.FC<HeaderBarProps>;
11
- //# sourceMappingURL=HeaderBar.d.ts.map
@@ -8,4 +8,3 @@ export interface NotificationToastProps {
8
8
  position?: 'bottom-center' | 'above-fab';
9
9
  }
10
10
  export declare const NotificationToast: React.FC<NotificationToastProps>;
11
- //# sourceMappingURL=NotificationToast.d.ts.map
@@ -1,5 +1,5 @@
1
1
  import React from 'react';
2
- import { type IconName } from '../base';
2
+ import type { IconName } from '../base/icons';
3
3
  export interface TabBarProps {
4
4
  tabs: {
5
5
  id: string;
@@ -10,4 +10,3 @@ export interface TabBarProps {
10
10
  onChange: (id: string) => void;
11
11
  }
12
12
  export declare const TabBar: React.FC<TabBarProps>;
13
- //# sourceMappingURL=TabBar.d.ts.map
@@ -21,4 +21,3 @@ export interface WidgetDialogProps {
21
21
  status?: WidgetDialogStatus;
22
22
  }
23
23
  export declare const WidgetDialog: React.FC<WidgetDialogProps>;
24
- //# sourceMappingURL=WidgetDialog.d.ts.map
@@ -18,4 +18,3 @@ export interface WidgetFabProps {
18
18
  isPreviewMode?: boolean;
19
19
  }
20
20
  export declare const WidgetFab: React.FC<WidgetFabProps>;
21
- //# sourceMappingURL=WidgetFab.d.ts.map
@@ -6,4 +6,3 @@ interface MessageContentProps {
6
6
  }
7
7
  export declare const MessageContent: React.FC<MessageContentProps>;
8
8
  export {};
9
- //# sourceMappingURL=MessageContent.d.ts.map
@@ -9,4 +9,3 @@ interface MessageItemProps {
9
9
  }
10
10
  export declare const MessageItem: React.FC<MessageItemProps>;
11
11
  export {};
12
- //# sourceMappingURL=MessageItem.d.ts.map