@dsrcjs/ai-widget 0.0.0-stage → 1.0.6

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.
package/LICENSE ADDED
@@ -0,0 +1,64 @@
1
+ ЧЕРНОВИК. Текст лицензии не проверен юристом и не является окончательным;
2
+ до проверки не публикуйте пакет и не ссылайтесь на эти условия в договорах.
3
+
4
+ DRAFT — this licence has not been reviewed by a lawyer and is not final; do not
5
+ publish the package or rely on these terms until it has been reviewed.
6
+
7
+ ---
8
+
9
+ AI-Dana Widget Licence (draft)
10
+
11
+ Copyright (c) 2026 DSRC. All rights reserved.
12
+
13
+ "Software" means the compiled files distributed in this package (the `dist/`
14
+ directory) and this file.
15
+
16
+ 1. Permission granted
17
+
18
+ You may, free of charge, download the Software, embed it in any website or
19
+ web application you control, and use it there for any purpose, including
20
+ commercial use. You may serve a verbatim copy of the Software from your own
21
+ servers or from a public CDN as part of that use.
22
+
23
+ 2. Restrictions
24
+
25
+ You may not:
26
+
27
+ a. modify, adapt or translate the Software, or create derivative works from
28
+ it;
29
+ b. decompile, disassemble or otherwise reverse-engineer the Software, or
30
+ attempt to reconstruct its source code, except to the extent this
31
+ restriction is void under applicable law;
32
+ c. distribute a modified copy of the Software, under this or any other name;
33
+ d. extract, reuse or incorporate any part of the Software into another
34
+ product, library or package;
35
+ e. remove or alter this licence, the copyright notice, or any attribution in
36
+ the Software;
37
+ f. sublicense, sell or rent the Software on its own, apart from a website or
38
+ application that uses it.
39
+
40
+ Configuring the Software through its documented public interface — options,
41
+ HTML attributes, CSS custom properties and `::part()` selectors — is use, not
42
+ modification.
43
+
44
+ 3. Service
45
+
46
+ The Software talks to the AI-Dana API, which is a separate service under its
47
+ own terms, quotas and availability. Nothing here grants a right to that
48
+ service. Access to the API may be limited, suspended or withdrawn at any
49
+ time, for any user or for any site, without notice and without affecting this
50
+ licence.
51
+
52
+ 4. No warranty
53
+
54
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
55
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
56
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
57
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
58
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
59
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
60
+
61
+ 5. Termination
62
+
63
+ This licence ends automatically if you breach any of its terms. On
64
+ termination you must stop using the Software and remove it from your sites.
package/README.md CHANGED
@@ -1,3 +1,297 @@
1
- # Temporary Holding Version
1
+ # @dsrcjs/ai-widget
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The AI-Dana chat as an embeddable widget for other sites: a launcher button (draggable) and a chat window that slides in from the right (60% of the page, dimming the rest) over
4
+ the page. One self-contained file, React and styles inside, rendered in a Shadow DOM so the page's CSS does not leak in
5
+ and the widget's CSS does not leak out.
6
+
7
+ Features: streaming answers with markdown, agent steps, stop, 1–5 rating and feedback, branches/regenerate, the
8
+ visitor's chat history, mode picker, attachments (when the site allows files), kk/ru/en, light/dark/auto, a daily
9
+ limit banner, mobile fullscreen.
10
+
11
+ ## Install
12
+
13
+ The package is on the public npm registry as [`@dsrcjs/ai-widget`](https://www.npmjs.com/package/@dsrcjs/ai-widget):
14
+
15
+ ```bash
16
+ npm i @dsrcjs/ai-widget
17
+ ```
18
+
19
+ It ships only the built files; the source is not public. See [LICENSE](LICENSE): embedding and using it is free,
20
+ modifying, reverse-engineering and redistributing it are not.
21
+
22
+ ### `<script>` tag
23
+
24
+ One tag, no build step. AI-Dana serves the widget itself, and this address always carries the current release — it
25
+ reaches your page within minutes of a release, nothing to bump on your side:
26
+
27
+ ```html
28
+ <script src="https://ai-dana.example.kz/widget/ai-dana-chat.js" defer></script>
29
+ <ai-dana-chat api-url="https://ai-dana.example.kz" launcher></ai-dana-chat>
30
+ ```
31
+
32
+ Want to pin a version instead? The same file by exact version never changes and is cached forever:
33
+
34
+ ```html
35
+ <script src="https://ai-dana.example.kz/widget/v/1.2.3/ai-dana-chat.js" defer></script>
36
+ ```
37
+
38
+ Do not put `integrity="…"` (SRI) on the rolling address: the hash is tied to the bytes of one release, and the next
39
+ one would stop your page loading the widget. Pin a version if you need SRI.
40
+
41
+ The package is also on npm, and jsDelivr mirrors it (`@1` = the current major, updated within a day or so):
42
+ `https://cdn.jsdelivr.net/npm/@dsrcjs/ai-widget@1/dist/ai-dana-chat.js`.
43
+
44
+ `api-url` is required on any page that is not the backend itself: the published bundle has no backend address
45
+ baked in, and without the attribute the widget calls the page's own origin. No key: the backend answers such a
46
+ visitor as the **anonymous tier** (the shared daily budget,
47
+ the default modes and theme, `Access-Control-Allow-Origin: *`, so any site may embed it). A site that asked for its
48
+ own branding, origins and higher limits gets a key and adds `site-key="…"` (see [Site key](#site-key)) from the ready snippet
49
+ AI-Dana gives with the key.
50
+
51
+ | Attribute | Meaning |
52
+ | ------------------- | ----------------------------------------------------------------------------------------------------------- |
53
+ | `site-key` | Public key of the widget site; without it the anonymous tier |
54
+ | `api-url` | Backend origin, an absolute `http(s)` URL (required on other sites); absent or `""` = the page's own origin |
55
+ | `launcher` | Launcher button + floating window. Without it only the window is rendered (size the element yourself) |
56
+ | `lang` | `kk` \| `ru` \| `en` (observed) |
57
+ | `theme` | `light` \| `dark` \| `auto` (observed) |
58
+ | `position` | `bottom-right` (default) \| `bottom-left` |
59
+ | `draggable="false"` | Pin the launcher |
60
+ | `open` | Open on load |
61
+
62
+ The element has `open()`, `close()`, `setTheme(theme)` and `setLang(lang)` and fires `openchange`
63
+ (`event.detail.open`). The script also exposes the global `AiDanaChat` with `mountLauncher` and `mount`.
64
+
65
+ ### npm / ESM
66
+
67
+ ```ts
68
+ import { mountLauncher, mount } from '@dsrcjs/ai-widget';
69
+
70
+ // Everything is optional; a key only for sites that have one
71
+ const chat = mountLauncher({ lang: 'ru' });
72
+ chat.setTheme({ primary: '#0a7d4f' });
73
+
74
+ // Or the window alone, inside your own container (you size it and decide when to show it)
75
+ const inline = mount(document.getElementById('chat')!, { siteKey: 'YOUR_SITE_KEY' });
76
+ ```
77
+
78
+ `mountLauncher(options)` appends its host to `document.body`; `mountLauncher(container, options)` renders into
79
+ `container`. The ES build lazy-loads the markdown renderer as a separate chunk; the IIFE includes everything.
80
+
81
+ ### Options
82
+
83
+ | Option | Type | Default | Notes |
84
+ | -------------- | --------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
85
+ | `siteKey` | `string` | — (anonymous tier) | Only for sites that were given a key |
86
+ | `apiUrl` | `string` | `''` (no address in the published build) | Backend origin; calls go to `{apiUrl}/api/v1/widget/…`; `''` = same origin |
87
+ | `lang` | `'kk' \| 'ru' \| 'en'` | `<html lang>` → browser language → `ru` | |
88
+ | `theme` | `ThemeOptions` | `{}` | Layer 2, see [Theming](#theming) |
89
+ | `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Launcher corner |
90
+ | `draggable` | `boolean` | `true` | Never draggable below 640px |
91
+ | `defaultOpen` | `boolean` | `false` (`true` for `mount`) | |
92
+ | `onOpenChange` | `(open: boolean) => void` | — | |
93
+ | `visitorId` | `string` (UUID) | kept in `localStorage.aid_visitor` | Deprecated: the backend now issues and signs the visitor id itself; a passed id works only while the backend still accepts unsigned ids |
94
+
95
+ ### Handle
96
+
97
+ ```ts
98
+ interface Handle {
99
+ open(): void;
100
+ close(): void;
101
+ unmount(): void; // removes the React root, the shadow content and (for mountLauncher without container) the host
102
+ setTheme(theme: ThemeOptions): void; // merges into layer 2; `{ primary: undefined }` drops a key
103
+ setLang(lang: 'kk' | 'ru' | 'en'): void;
104
+ }
105
+ ```
106
+
107
+ ## Public contract
108
+
109
+ These are the things other sites depend on, so they change **only in a major version** (see
110
+ [Versioning](#versioning)):
111
+
112
+ | What | Where |
113
+ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
114
+ | `mount(container, options)`, `mountLauncher([container,] options)`, the `Handle` they return | [npm / ESM](#npm--esm), [Options](#options), [Handle](#handle) |
115
+ | `<ai-dana-chat>` and its attributes, methods and `openchange` event | [`<script>` tag](#script-tag) |
116
+ | The global `AiDanaChat` of the IIFE build (`mount`, `mountLauncher`) | [`<script>` tag](#script-tag) |
117
+ | The `--aid-*` CSS variables | [`--aid-*` variables](#aid--variables) |
118
+ | The `::part()` names | [Parts](#parts) |
119
+ | The `localStorage` keys | [Storage](#storage) |
120
+
121
+ Everything else — the DOM inside the shadow root, class names, the structure of the React tree, the names of the
122
+ internal modules and the chunk layout of the ES build — is private and may change in any release. A `::part()` that
123
+ is not in the table does not exist; style only the parts listed there.
124
+
125
+ A removal or a rename of anything in the table is a major release; a new option, attribute, variable or part is a
126
+ minor one.
127
+
128
+ ## Theming
129
+
130
+ Four layers, the higher one wins: **site CSS variables > JS `theme` > admin theme > kit defaults**. `::part()` rules
131
+ are plain CSS on top of all of them.
132
+
133
+ ```ts
134
+ interface ThemeOptions {
135
+ primary?: string; // hex, rgb(), hsl() or a basic name; hover/pressed/foreground (WCAG contrast) are derived
136
+ radius?: string | number; // a number means px
137
+ font?: string; // font-family; the widget uses a system stack by default (no web font is embedded)
138
+ scheme?: 'light' | 'dark' | 'auto';
139
+ logoUrl?: string;
140
+ title?: string;
141
+ launcher?: 'icon' | 'label'; // icon only (default) or icon + launcherLabel
142
+ launcherLabel?: string; // default: «Задать вопрос» in the visitor's language
143
+ launcherShape?: 'circle' | 'rounded' | 'square'; // launcher corners, default circle
144
+ background?: string; // window colours; unset ones follow the kit and the scheme
145
+ foreground?: string;
146
+ bubble?: string; // assistant bubble and muted surfaces
147
+ border?: string;
148
+ windowWidth?: number; // px; site CSS --aid-window-width / --aid-offset-x still wins
149
+ windowHeight?: number;
150
+ position?: 'bottom-right' | 'bottom-left'; // the JS `position` option wins over this
151
+ offsetX?: number;
152
+ offsetY?: number;
153
+ }
154
+ ```
155
+
156
+ Dana is one drawn character with no colour options; `logoUrl` (https, a path on your own site or a `data:image/…` URL; sent without a Referer) replaces her in the header only. Her pictures are
157
+ fetched from the backend (`<apiUrl>/static/avatars/dana/`). Site CSS can still style the box around her through
158
+ `::part(avatar)`.
159
+
160
+ 1. **Admin** — the «Оформление» and «Кнопка запуска» sections of the widget site (colour picker, choices, live
161
+ preview); they are stored as `theme` JSON with the same keys, keys the form does not know are kept:
162
+ `{"primary": "#7b1fa2", "radius": 12, "scheme": "dark", "title": "Shop assistant", "logoUrl": "https://…/logo.svg"}`.
163
+ `welcome` (`{"ru": "…", "kk": "…", "en": "…"}`) is the greeting in an empty chat. Both arrive with `GET config`.
164
+ 2. **JS** — `theme` option or `handle.setTheme({ primary: '#0a7d4f', radius: 16 })`.
165
+ 3. **CSS variables** — on the host element, inherited into the shadow root. Any CSS colour format works.
166
+
167
+ ```css
168
+ ai-dana-chat {
169
+ --aid-primary: #c2185b;
170
+ --aid-radius: 4px;
171
+ --aid-font: Georgia, serif;
172
+ }
173
+ ```
174
+
175
+ For `mountLauncher()` without a container the host is `div[data-ai-dana-chat]`.
176
+
177
+ 4. **`::part()`**
178
+
179
+ ```css
180
+ ai-dana-chat::part(launcher) {
181
+ box-shadow: 0 0 0 4px gold;
182
+ }
183
+ ai-dana-chat::part(header) {
184
+ background: #fde68a;
185
+ color: #111;
186
+ }
187
+ ```
188
+
189
+ ### `--aid-*` variables
190
+
191
+ | Variable | Default | Meaning |
192
+ | ------------------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------- |
193
+ | `--aid-primary` | kit primary | Accent: launcher, user bubble, send button |
194
+ | `--aid-primary-foreground` | derived from primary | Text on primary |
195
+ | `--aid-primary-hovered`, `--aid-primary-pressed` | derived from primary | Button states, launcher hover |
196
+ | `--aid-secondary`, `--aid-ring` | primary at 10% / 50% | Soft backgrounds; focus ring (a 3px outline with a 3px offset on the launcher) |
197
+ | `--aid-background`, `--aid-foreground` | kit, per scheme | Window background and text |
198
+ | `--aid-muted`, `--aid-border` | kit, per scheme | Muted surfaces, borders |
199
+ | `--aid-radius` | kit radius (12px) | Corner radius; the window card is 6px rounder, the settings panel 4px |
200
+ | `--aid-font` | system stack | `font-family` |
201
+ | `--aid-z-index` | `2147483000` | Launcher, overlay and window |
202
+ | `--aid-offset-x`, `--aid-offset-y` | `20px` | Launcher distance from its corner |
203
+ | `--aid-window-width` | `60vw` | Width of the window card on desktop: at least 720px, never wider than the page minus 48px |
204
+ | `--aid-overlay` | `rgb(2 6 23 / 0.35)` | Dimming of the page behind the window |
205
+
206
+ The colours of errors, warnings, success, mode states and secondary text are **not** variables: they come from the kit
207
+ and the widget, and stay readable only on a window background that suits the colour scheme.
208
+
209
+ Colour variables set on the host apply to both light and dark schemes; scope them yourself
210
+ (`@media (prefers-color-scheme: dark)`) if they should differ.
211
+
212
+ ### Parts
213
+
214
+ `launcher`, `launcher-label`, `badge`, `overlay`, `window`, `sidebar` (with `data-state`), `header`, `logo`, `title`,
215
+ `new-chat`, `search`, `history`, `thread-item`, `settings-button`, `settings`, `toolbar`, `expand`, `close`,
216
+ `mode-select`, `mode-list`, `mode-option`, `messages`, `scroll-down`, `empty`, `avatar`, `welcome`, `example`,
217
+ `message` (with `data-role`), `bubble`, `user-bubble`, `assistant-bubble`, `error-bubble`, `markdown`, `steps`,
218
+ `actions`, `copy`, `regenerate`, `rating`, `feedback`, `branch`, `edit`, `edit-button`, `attachment`, `composer`,
219
+ `composer-file`, `attach`, `input`, `send`, `stop`, `counter`, `source`, `intro`, `answer-blocks`, `clarification`, `data-table`, `disclaimer`,
220
+ `limit-banner` (with `data-state` `low`, `blocked`, `overloaded`), `notice`, `category` (a category card of the empty chat, «What can be done»), `dashboard-preview`
221
+ (the compact chart under an answer), `dashboard-toggle` («Dashboard» / «Hide dashboard» under an answer), `files`
222
+ (the export files of an answer), `report` (the report block: «Generate report» button and its files), `dashboard`
223
+ (the panel, with `data-fullscreen`), `dashboard-tabs` («Chat / Dashboard» in the toolbar of a window narrower than
224
+ 1280px).
225
+
226
+ Parts that came with the chat redesign, and parts that were always there but were not listed. The «Parts» above and
227
+ these are one list: the widget is tested to draw every part named here and to name every part it draws.
228
+
229
+ - `plan` (the chips «What was counted» over an answer), `catalog` (the catalog card), `answer-actions` (the row of
230
+ block actions under an answer), `data-toggle` («Data» in it), `methodology` (the «Methodology» link),
231
+ `section-chart` (the chart of a dashboard section and the compact one under an answer).
232
+
233
+ - `history-toggle` (the «History» button of the window row while the panel is hidden; the hidden panel stays as an empty `sidebar` with `data-state="collapsed"`, and `settings-button` now sits in the window row).
234
+
235
+ - `mode-health` (the state of a mode in words with a dot — «Free», «Busy», «Unavailable»; `data-level` `idle`, `busy`, `unavailable`; in the mode button and in its list).
236
+
237
+ - `composer-hint` (the line over the field when the chosen mode is unavailable or there are no modes).
238
+
239
+ - `file-type` (the coloured tile with a file's type: the selected file, a file under a question, the files of a report; `data-kind` `pdf`, `doc`, `ppt`, `xls`, `csv`, `other`).
240
+
241
+ - `feedback-saved` (the saved reason and text of a feedback under an answer).
242
+
243
+ ## Storage
244
+
245
+ | `localStorage` key | Value |
246
+ | ------------------ | ------------------------------------------------------- |
247
+ | `aid_visitor` | Visitor id signed by the backend (`<uuid>:<signature>`) |
248
+ | `aid_pos` | Dragged launcher offset `{x, y}` from its corner |
249
+ | `aid_mode` | Last selected mode slug |
250
+ | `aid_prefs` | Visitor's settings `{lang, scheme}` |
251
+ | `aid_sidebar` | `collapsed` / `expanded` |
252
+ | `aid_intro_ack` | `1` once the intro notice was acknowledged |
253
+
254
+ No cookies are used. With blocked storage (sandboxed iframe, strict private mode) the widget works with a per-load
255
+ visitor and forgets the position.
256
+
257
+ ## Size
258
+
259
+ `dist/ai-dana-chat.js` (IIFE): about 360 KB gzip with React, markdown, charts and styles.
260
+
261
+ ## Site key
262
+
263
+ AI-Dana issues the key together with the site's allowed origins (exact origins, e.g. `https://shop.kz`; no `*`, no
264
+ paths), modes, limits, files and theme, and gives you the ready snippet with it.
265
+
266
+ ## Limits and CORS
267
+
268
+ - Every request carries `X-Visitor-Id`, and `X-Widget-Key` only when the site has a key. Without a key the request
269
+ is served as the anonymous tier and CORS answers `Access-Control-Allow-Origin: *`, so the widget works on any site.
270
+ - With a key the browser's `Origin` must be in the site's `allowed_origins` exactly (scheme, host and port). A wrong
271
+ origin or key gets no CORS headers, so in the browser it looks like a network error: check the origin first.
272
+ - `503`: the shared daily budget for anonymous messages is spent. The widget locks the input and says «the service is
273
+ overloaded, try later» in the limit banner (`::part(limit-banner)` with `data-state="overloaded"`) instead of a bare
274
+ error code; sites with a key are not affected.
275
+ - No cookies and no `Access-Control-Allow-Credentials`; the widget never sees the main site's session.
276
+ - `daily_messages_per_visitor` (per site and visitor) and `rate_per_minute` are enforced by the backend. The widget
277
+ shows the remaining count when it runs low, disables the input at zero and shows the reset time on `429`.
278
+ - The question length limit comes from `max_query_chars` in `GET config`.
279
+ - Files: only when both the site (`allow_files`) and the mode allow them; the mode's `max_file_mb` applies.
280
+ - Links from answers open in a new tab with `noopener`; only `http(s)` links are clickable. Images are loaded only
281
+ from the AI-Dana attachments API (with the widget headers), never from arbitrary URLs.
282
+
283
+ ## Versioning
284
+
285
+ [SemVer](https://semver.org/). The major version changes only when something in
286
+ [Public contract](#public-contract) is removed or renamed; a new option, attribute, variable or part is a minor one;
287
+ everything else is a patch. What changed is in [CHANGELOG.md](CHANGELOG.md) (Keep a Changelog); each release moves the
288
+ `Unreleased` entries into a version heading.
289
+
290
+ ## Known limitations
291
+
292
+ - The focus trap is on whenever the window is open, also on desktop where the window is not modal: Tab does not
293
+ leave the widget until it is closed (Esc).
294
+ - On mobile the fullscreen window does not lock the page scroll behind it.
295
+ - Fonts are not embedded: `--aid-font`/`font` must name a font the page has already loaded.
296
+ - No unread badge yet (the `badge` part exists but nothing feeds it).
297
+ - The custom element observes only `lang` and `theme`; other attributes are read on connect.