@marketrix.ai/widget 3.8.10 → 3.8.53

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 (216) hide show
  1. package/README.md +158 -169
  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 +9 -12
  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 -256
  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/WidgetDialog.d.ts +0 -13
  28. package/dist/src/components/blocks/WidgetFab.d.ts +0 -1
  29. package/dist/src/components/chat/MessageContent.d.ts +0 -1
  30. package/dist/src/components/chat/MessageItem.d.ts +0 -1
  31. package/dist/src/components/chat/MessageList.d.ts +1 -2
  32. package/dist/src/components/chat/ProgressLine.d.ts +0 -1
  33. package/dist/src/components/chat/SuggestedActions.d.ts +0 -1
  34. package/dist/src/components/chat/TaskStatusIcon.d.ts +0 -1
  35. package/dist/src/components/chat/ThinkingIndicator.d.ts +0 -1
  36. package/dist/src/components/chat/VideoStreamDisplay.d.ts +0 -1
  37. package/dist/src/components/navigation/MessengerShell.d.ts +1 -3
  38. package/dist/src/components/navigation/ResizeHandles.d.ts +0 -1
  39. package/dist/src/components/navigation/ShellTabBar.d.ts +0 -1
  40. package/dist/src/components/navigation/ViewTransition.d.ts +0 -1
  41. package/dist/src/components/ui/StateMessage.d.ts +0 -1
  42. package/dist/src/components/ui/WidgetSettingsLoader.d.ts +1 -2
  43. package/dist/src/components/views/ChatView.d.ts +1 -3
  44. package/dist/src/components/views/HomeView.d.ts +0 -1
  45. package/dist/src/constants/theme.d.ts +0 -1
  46. package/dist/src/context/ConversationContext.d.ts +56 -0
  47. package/dist/src/context/UIStateContext.d.ts +0 -1
  48. package/dist/src/context/WidgetProviders.d.ts +8 -7
  49. package/dist/src/context/sseReducer.d.ts +3 -4
  50. package/dist/src/design-system/component-tokens.d.ts +0 -1
  51. package/dist/src/design-system/layers.d.ts +0 -1
  52. package/dist/src/design-system/semantic-tokens.d.ts +0 -1
  53. package/dist/src/design-system/shadows.d.ts +0 -1
  54. package/dist/src/design-system/token-adapter.d.ts +0 -1
  55. package/dist/src/hooks/useDragSnap.d.ts +0 -1
  56. package/dist/src/hooks/useFocusTrap.d.ts +0 -1
  57. package/dist/src/hooks/useResize.d.ts +0 -1
  58. package/dist/src/hooks/useScreenShare.d.ts +0 -1
  59. package/dist/src/hooks/useScrollLock.d.ts +0 -1
  60. package/dist/src/hooks/useWidget.d.ts +2 -6
  61. package/dist/src/index.d.ts +0 -1
  62. package/dist/src/lib/utils.d.ts +0 -1
  63. package/dist/src/sdk/contract.d.ts +0 -371
  64. package/dist/src/sdk/contracts/activityLog.d.ts +0 -25
  65. package/dist/src/sdk/contracts/application.d.ts +54 -5
  66. package/dist/src/sdk/contracts/chat.d.ts +0 -1
  67. package/dist/src/sdk/contracts/common.d.ts +10 -14
  68. package/dist/src/sdk/contracts/entities.d.ts +12 -271
  69. package/dist/src/sdk/contracts/widget.d.ts +0 -973
  70. package/dist/src/sdk/index.d.ts +1 -372
  71. package/dist/src/services/ApiService.d.ts +1 -3
  72. package/dist/src/services/ChatService.d.ts +3 -6
  73. package/dist/src/services/ConfigManager.d.ts +0 -1
  74. package/dist/src/services/DomService.d.ts +3 -33
  75. package/dist/src/services/ScreenShareService.d.ts +0 -6
  76. package/dist/src/services/SessionManager.d.ts +0 -1
  77. package/dist/src/services/SessionRecorder.d.ts +0 -1
  78. package/dist/src/services/ShowModeService.d.ts +0 -1
  79. package/dist/src/services/StorageService.d.ts +3 -5
  80. package/dist/src/services/StreamClient.d.ts +0 -2
  81. package/dist/src/services/ToolService.d.ts +3 -4
  82. package/dist/src/services/ValidationService.d.ts +9 -12
  83. package/dist/src/services/WidgetService.d.ts +0 -2
  84. package/dist/src/test/a11y-utils.d.ts +0 -1
  85. package/dist/src/test/fixtures.d.ts +0 -1
  86. package/dist/src/test/setup.d.ts +0 -1
  87. package/dist/src/types/browserTools.d.ts +2 -9
  88. package/dist/src/types/index.d.ts +3 -19
  89. package/dist/src/utils/apiUtils.d.ts +0 -1
  90. package/dist/src/utils/bootstrap.d.ts +0 -11
  91. package/dist/src/utils/chat.d.ts +0 -11
  92. package/dist/src/utils/common.d.ts +0 -1
  93. package/dist/src/utils/dom.d.ts +0 -13
  94. package/dist/src/utils/format.d.ts +0 -1
  95. package/dist/src/utils/suggestedActions.d.ts +0 -1
  96. package/dist/src/utils/validation.d.ts +0 -9
  97. package/dist/src/utils/widgetPositioning.d.ts +0 -1
  98. package/dist/widget.mjs +62 -65
  99. package/dist/widget.mjs.map +1 -1
  100. package/package.json +15 -15
  101. package/dist/index.html +0 -1697
  102. package/dist/src/components/MarketrixWidget.d.ts.map +0 -1
  103. package/dist/src/components/base/Avatar.d.ts.map +0 -1
  104. package/dist/src/components/base/Badge.d.ts.map +0 -1
  105. package/dist/src/components/base/Button.d.ts.map +0 -1
  106. package/dist/src/components/base/Card.d.ts.map +0 -1
  107. package/dist/src/components/base/Dialog.d.ts.map +0 -1
  108. package/dist/src/components/base/Flex.d.ts.map +0 -1
  109. package/dist/src/components/base/Icon.d.ts.map +0 -1
  110. package/dist/src/components/base/IconButton.d.ts.map +0 -1
  111. package/dist/src/components/base/Indicator.d.ts.map +0 -1
  112. package/dist/src/components/base/Menu.d.ts.map +0 -1
  113. package/dist/src/components/base/Pill.d.ts.map +0 -1
  114. package/dist/src/components/base/Spinner.d.ts.map +0 -1
  115. package/dist/src/components/base/Stack.d.ts.map +0 -1
  116. package/dist/src/components/base/Surface.d.ts.map +0 -1
  117. package/dist/src/components/base/Text.d.ts.map +0 -1
  118. package/dist/src/components/base/Textarea.d.ts.map +0 -1
  119. package/dist/src/components/base/Video.d.ts.map +0 -1
  120. package/dist/src/components/base/icons.d.ts.map +0 -1
  121. package/dist/src/components/base/index.d.ts +0 -22
  122. package/dist/src/components/base/index.d.ts.map +0 -1
  123. package/dist/src/components/base/layoutProps.d.ts.map +0 -1
  124. package/dist/src/components/base/tokens.d.ts.map +0 -1
  125. package/dist/src/components/base/useDisclosure.d.ts.map +0 -1
  126. package/dist/src/components/blocks/ChatInput.d.ts.map +0 -1
  127. package/dist/src/components/blocks/HeaderBar.d.ts.map +0 -1
  128. package/dist/src/components/blocks/NotificationToast.d.ts.map +0 -1
  129. package/dist/src/components/blocks/TabBar.d.ts +0 -13
  130. package/dist/src/components/blocks/TabBar.d.ts.map +0 -1
  131. package/dist/src/components/blocks/WidgetDialog.d.ts.map +0 -1
  132. package/dist/src/components/blocks/WidgetFab.d.ts.map +0 -1
  133. package/dist/src/components/blocks/index.d.ts +0 -7
  134. package/dist/src/components/blocks/index.d.ts.map +0 -1
  135. package/dist/src/components/chat/MessageContent.d.ts.map +0 -1
  136. package/dist/src/components/chat/MessageItem.d.ts.map +0 -1
  137. package/dist/src/components/chat/MessageList.d.ts.map +0 -1
  138. package/dist/src/components/chat/ProgressLine.d.ts.map +0 -1
  139. package/dist/src/components/chat/SuggestedActions.d.ts.map +0 -1
  140. package/dist/src/components/chat/TaskStatusIcon.d.ts.map +0 -1
  141. package/dist/src/components/chat/ThinkingIndicator.d.ts.map +0 -1
  142. package/dist/src/components/chat/VideoStreamDisplay.d.ts.map +0 -1
  143. package/dist/src/components/navigation/MessengerShell.d.ts.map +0 -1
  144. package/dist/src/components/navigation/ResizeHandles.d.ts.map +0 -1
  145. package/dist/src/components/navigation/ShellTabBar.d.ts.map +0 -1
  146. package/dist/src/components/navigation/ViewTransition.d.ts.map +0 -1
  147. package/dist/src/components/ui/StateMessage.d.ts.map +0 -1
  148. package/dist/src/components/ui/WidgetSettingsLoader.d.ts.map +0 -1
  149. package/dist/src/components/views/ChatView.d.ts.map +0 -1
  150. package/dist/src/components/views/HomeView.d.ts.map +0 -1
  151. package/dist/src/constants/config.d.ts +0 -8
  152. package/dist/src/constants/config.d.ts.map +0 -1
  153. package/dist/src/constants/theme.d.ts.map +0 -1
  154. package/dist/src/context/ChatContext.d.ts +0 -34
  155. package/dist/src/context/ChatContext.d.ts.map +0 -1
  156. package/dist/src/context/TaskContext.d.ts +0 -39
  157. package/dist/src/context/TaskContext.d.ts.map +0 -1
  158. package/dist/src/context/UIStateContext.d.ts.map +0 -1
  159. package/dist/src/context/WidgetProviders.d.ts.map +0 -1
  160. package/dist/src/context/sseReducer.d.ts.map +0 -1
  161. package/dist/src/design-system/component-tokens.d.ts.map +0 -1
  162. package/dist/src/design-system/layers.d.ts.map +0 -1
  163. package/dist/src/design-system/semantic-tokens.d.ts.map +0 -1
  164. package/dist/src/design-system/shadows.d.ts.map +0 -1
  165. package/dist/src/design-system/themes/default.d.ts +0 -7
  166. package/dist/src/design-system/themes/default.d.ts.map +0 -1
  167. package/dist/src/design-system/themes/high-contrast.d.ts +0 -4
  168. package/dist/src/design-system/themes/high-contrast.d.ts.map +0 -1
  169. package/dist/src/design-system/themes/index.d.ts +0 -3
  170. package/dist/src/design-system/themes/index.d.ts.map +0 -1
  171. package/dist/src/design-system/token-adapter.d.ts.map +0 -1
  172. package/dist/src/hooks/useDragSnap.d.ts.map +0 -1
  173. package/dist/src/hooks/useFocusTrap.d.ts.map +0 -1
  174. package/dist/src/hooks/useResize.d.ts.map +0 -1
  175. package/dist/src/hooks/useScreenShare.d.ts.map +0 -1
  176. package/dist/src/hooks/useScrollLock.d.ts.map +0 -1
  177. package/dist/src/hooks/useWidget.d.ts.map +0 -1
  178. package/dist/src/index.d.ts.map +0 -1
  179. package/dist/src/lib/utils.d.ts.map +0 -1
  180. package/dist/src/sdk/contract.d.ts.map +0 -1
  181. package/dist/src/sdk/contracts/activityLog.d.ts.map +0 -1
  182. package/dist/src/sdk/contracts/agent.d.ts +0 -3243
  183. package/dist/src/sdk/contracts/agent.d.ts.map +0 -1
  184. package/dist/src/sdk/contracts/application.d.ts.map +0 -1
  185. package/dist/src/sdk/contracts/chat.d.ts.map +0 -1
  186. package/dist/src/sdk/contracts/common.d.ts.map +0 -1
  187. package/dist/src/sdk/contracts/entities.d.ts.map +0 -1
  188. package/dist/src/sdk/contracts/widget.d.ts.map +0 -1
  189. package/dist/src/sdk/index.d.ts.map +0 -1
  190. package/dist/src/services/ApiService.d.ts.map +0 -1
  191. package/dist/src/services/ChatService.d.ts.map +0 -1
  192. package/dist/src/services/ConfigManager.d.ts.map +0 -1
  193. package/dist/src/services/DomService.d.ts.map +0 -1
  194. package/dist/src/services/ScreenShareService.d.ts.map +0 -1
  195. package/dist/src/services/SessionManager.d.ts.map +0 -1
  196. package/dist/src/services/SessionRecorder.d.ts.map +0 -1
  197. package/dist/src/services/ShowModeService.d.ts.map +0 -1
  198. package/dist/src/services/StorageService.d.ts.map +0 -1
  199. package/dist/src/services/StreamClient.d.ts.map +0 -1
  200. package/dist/src/services/ToolService.d.ts.map +0 -1
  201. package/dist/src/services/ValidationService.d.ts.map +0 -1
  202. package/dist/src/services/WidgetService.d.ts.map +0 -1
  203. package/dist/src/test/a11y-utils.d.ts.map +0 -1
  204. package/dist/src/test/fixtures.d.ts.map +0 -1
  205. package/dist/src/test/setup.d.ts.map +0 -1
  206. package/dist/src/types/browserTools.d.ts.map +0 -1
  207. package/dist/src/types/index.d.ts.map +0 -1
  208. package/dist/src/utils/apiUtils.d.ts.map +0 -1
  209. package/dist/src/utils/bootstrap.d.ts.map +0 -1
  210. package/dist/src/utils/chat.d.ts.map +0 -1
  211. package/dist/src/utils/common.d.ts.map +0 -1
  212. package/dist/src/utils/dom.d.ts.map +0 -1
  213. package/dist/src/utils/format.d.ts.map +0 -1
  214. package/dist/src/utils/suggestedActions.d.ts.map +0 -1
  215. package/dist/src/utils/validation.d.ts.map +0 -1
  216. package/dist/src/utils/widgetPositioning.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,249 +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
19
-
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`) |
28
+ `loader.js`:
27
29
 
28
- \*Either `mtx-id` + `mtx-key` (production) OR `mtx-app` + `mtx-agent` (dev) must be provided.
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.
29
33
 
30
- ### Widget Settings
34
+ The widget then **auto-initializes** from those attributes — no extra JavaScript required.
31
35
 
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.
36
+ ### 2. npm / programmatic
33
37
 
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
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
+ ```
39
42
 
40
- ### `initWidget`
43
+ ```ts
44
+ import { mountWidget } from '@marketrix.ai/widget';
41
45
 
42
- ```typescript
43
- import {
44
- initWidget,
45
- unmountWidget,
46
- updateMarketrixConfig,
47
- startRecording,
48
- stopRecording,
49
- getRecordingState,
50
- } from '@marketrix.ai/widget';
51
-
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
- - Node.js 24 (CI pins `node-version: 24`)
156
- - npm
172
+ ### `getCurrentConfig(): MarketrixConfig | null`
157
173
 
158
- ### Setup
174
+ Returns the active configuration, or `null` if the widget isn't initialized.
159
175
 
160
- ```bash
161
- git clone <repository-url>
162
- cd widget
163
- npm install
164
- npm start # dev server on port 9001 (widget.marketrix.localhost)
165
- npm run build # production build → dist/widget.mjs
166
- ```
176
+ ### Session recording
167
177
 
168
- ### Project Structure
178
+ The widget records user sessions (via rrweb) automatically once initialized. These helpers let you control it:
169
179
 
170
- ```
171
- widget/
172
- ├── src/
173
- │ ├── components/ # React components (base, blocks, chat, navigation, ui, views)
174
- │ ├── design-system/ # design tokens + primitives
175
- │ ├── context/ # WidgetContext provider
176
- │ ├── hooks/ # Custom React hooks
177
- │ ├── services/ # Core services (StreamClient, ChatService, SessionRecorder, ToolService, …)
178
- │ ├── sdk/ # oRPC client + scoped contract mirror (contract.ts + contracts/*)
179
- │ ├── types/ # TypeScript types
180
- │ ├── utils/ # Utility functions (incl. bootstrap.tsx — closed Shadow DOM mount)
181
- │ ├── constants/ # Config constants
182
- │ ├── lib/ # shared helpers
183
- │ └── index.tsx # Main entry point (public API)
184
- ├── public/loader.js # classic script-tag loader
185
- ├── vite.config.ts
186
- ├── tsconfig.json
187
- └── package.json
188
- ```
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.
189
183
 
190
- ## Build System
184
+ ### `MarketrixWidget` — React component (preview)
191
185
 
192
- Vite with CSS injection, Shadow DOM isolation, ESM format, TypeScript declarations, and Terser minification.
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.
193
187
 
194
- Output files:
188
+ ```tsx
189
+ import { MarketrixWidget } from '@marketrix.ai/widget';
195
190
 
196
- - `dist/widget.mjs` — Library build (React as peer dependency)
197
- - `dist/loader.js` — Classic loader script (loads widget.mjs with configured attributes)
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
+ }
199
+ ```
198
200
 
199
- ## CI/CD
201
+ Props: `settings` (required), `container?`, `mtxId?`, `mtxKey?`, `mtxApiHost?`.
200
202
 
201
- Single workflow `ci.yml` with three jobs:
203
+ ---
202
204
 
203
- | Job | Trigger | Action |
204
- | --------- | -------------------- | ------------------------------------------------------------------------------- |
205
- | `validate` | Push / PR to `dev` | type-check, lint, build, format:check, test:run, visual/a11y/bundle checks |
206
- | `build` | Tag push (`v*`) | Build Docker image → `marketrix.azurecr.io/widget:{version}` (v-prefix stripped) |
207
- | `publish` | Tag push (`v*`) | `npm publish @marketrix.ai/widget` (skipped if version already on registry) |
205
+ ## Interaction modes
208
206
 
209
- `contract-drift.yml` fails PRs whose `src/sdk/` mirror has drifted from `Marketrix-ai/api` (needs the `CONTRACTS_READ_TOKEN` secret). Dev branch pushes do not build images. Deployment to dev/prod is handled by the centralized `deploy.yml` in `infra`.
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.
210
210
 
211
- ### Release
211
+ ---
212
212
 
213
- ```bash
214
- npm run tag <version> # bumps package.json, refreshes lockfile, builds, commits, tags vX
215
- git push origin HEAD && git push origin v<version>
216
- ```
213
+ ## Exported types
217
214
 
218
- ## Dependencies
215
+ TypeScript types are bundled with the package:
219
216
 
220
- ### Production (peer + runtime)
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'`).
221
221
 
222
- - `react` / `react-dom` ^19 — peer dependency
223
- - `@rrweb/record` — session recording
224
- - `@orpc/client` / `@orpc/contract` ^1 — type-safe API client (oRPC)
225
- - `@base-ui/react` — UI primitives
226
- - `zod` ^4 — schema validation
227
- - `tailwind-merge` — class merging
222
+ ---
228
223
 
229
- ### Development
224
+ ## Requirements
230
225
 
231
- - Vite 8
232
- - Tailwind CSS 4 (via `@tailwindcss/vite` plugin)
233
- - TypeScript 6
234
- - Vitest + Testing Library + axe (unit, integration, a11y)
235
- - ESLint 10 + Prettier
236
- - 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.
237
229
 
238
- **Quality gates (run before PR):** `npm run code:check` (type-check + lint + format), `npm run test:run`, `npm run build`, then `npm run visual:check`, `npm run a11y:check`, `npm run bundle:check`.
230
+ ---
239
231
 
240
232
  ## License
241
233
 
242
- Apache License 2.0 - see LICENSE file for details.
234
+ Apache License 2.0 — see the `LICENSE` file.
243
235
 
244
236
  ## Support
245
237
 
246
- For support and questions, please contact the Marketrix team or create an issue
247
- in the repository.
248
-
249
- [Back to top](#marketrix-widget)
238
+ Contact the Marketrix team or open an issue in the repository.
package/dist/src/components/MarketrixWidget.d.ts CHANGED
@@ -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
package/dist/src/components/base/Avatar.d.ts CHANGED
@@ -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
package/dist/src/components/base/Badge.d.ts CHANGED
@@ -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
package/dist/src/components/base/Button.d.ts CHANGED
@@ -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
package/dist/src/components/base/Card.d.ts CHANGED
@@ -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
package/dist/src/components/base/Dialog.d.ts CHANGED
@@ -6,22 +6,19 @@ interface DialogProps {
6
6
  }
7
7
  interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement> {
8
8
  children: React.ReactNode;
9
- variant?: 'default' | 'confirm' | 'info';
9
+ variant?: 'default' | 'confirm';
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
- variant?: 'default' | 'confirm' | 'info';
15
+ variant?: 'default' | 'confirm';
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;
22
- interface DialogCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
23
- variant?: 'default' | 'info';
24
- }
25
- export declare function DialogClose({ children, className, onClick, variant, ...props }: DialogCloseProps): import("react/jsx-runtime").JSX.Element;
21
+ export declare function DialogDescription({ className, variant, ...props }: DialogDescriptionProps): import("react").JSX.Element;
22
+ type DialogCloseProps = React.ButtonHTMLAttributes<HTMLButtonElement>;
23
+ export declare function DialogClose({ children, className, onClick, ...props }: DialogCloseProps): import("react").JSX.Element;
26
24
  export {};
27
- //# sourceMappingURL=Dialog.d.ts.map
package/dist/src/components/base/Flex.d.ts CHANGED
@@ -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
package/dist/src/components/base/Icon.d.ts CHANGED
@@ -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
package/dist/src/components/base/IconButton.d.ts CHANGED
@@ -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
package/dist/src/components/base/Indicator.d.ts CHANGED
@@ -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
package/dist/src/components/base/Menu.d.ts CHANGED
@@ -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
package/dist/src/components/base/Pill.d.ts CHANGED
@@ -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
package/dist/src/components/base/Spinner.d.ts CHANGED
@@ -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
package/dist/src/components/base/Stack.d.ts CHANGED
@@ -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
package/dist/src/components/base/Surface.d.ts CHANGED
@@ -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
package/dist/src/components/base/Text.d.ts CHANGED
@@ -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
package/dist/src/components/base/Textarea.d.ts CHANGED
@@ -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
package/dist/src/components/base/Video.d.ts CHANGED
@@ -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