@boldare/askdare 0.0.0-stage → 0.1.0-rc.1

package/docs/texts.md

@@ -0,0 +1,176 @@
+# Texts
+
+Every text the chat shows has a key, such as `composer.placeholder`. The library ships each text in English and Polish, and you can replace any of them per bot. The keys are public API ([ADR-0006](https://github.com/boldare/askdare/blob/main/docs/adr/0006-support-matrix-and-versioning.md)), so you can rely on them in your configuration.
+
+The keys cover the chat and the launcher on your page: `launcher.*`, and `header.title`, which also names the chat dialog. A key named after an error code, such as `error.rate_limited`, is the text the widget shows for that code; some errors have a more specific key, such as `error.conversationTooLong`. The server sends these keys with its errors ([Wire protocol](protocol.md#error-keys-and-parameters)).
+
+## Override texts
+
+Set `widget.texts` in `defineBot`:
+
+```ts
+defineBot({
+  // …
+  widget: {
+    texts: {
+      'composer.placeholder': 'Ask about plans, support or security…',
+      'launcher.label': 'Questions?',
+      'message.attachments.one': '{count} file',
+      'message.attachments.other': '{count} files',
+    },
+  },
+});
+```
+
+- **Keys.** Only the keys in the table below are accepted. An unknown key, or a text that is empty or longer than 300 characters, makes `defineBot` throw at startup.
+- **Shortcuts.** `title`, `greeting`, `placeholder` and `launcherLabel` set `header.title`, `welcome.greeting`, `composer.placeholder` and `launcher.label`. If you set a shortcut and the same key in `texts`, the shortcut wins.
+- **Every language.** An override replaces the text in every language. With `locale: 'auto'`, Polish visitors see your override too.
+- **Placeholders.** Words in braces, such as `{count}`, `{name}`, `{size}` and `{max}`, are filled in by the widget. Keep the ones the default text has. A placeholder the widget doesn't fill for that key is shown as typed.
+- **Bold.** In `welcome.greeting`, `**words**` are shown in bold.
+
+A page can still set its own greeting with `askdare('configure', { greeting })`; see [Styling](styling.md#3-page-javascript).
+
+## Languages
+
+`widget.locale` picks the language:
+
+| Value | Texts |
+| --- | --- |
+| `'en'` (default) | English |
+| A Polish tag, such as `'pl'` or `'pl-PL'` | Polish |
+| Any other BCP 47 tag, such as `'de'` | English, unless you set `texts` |
+| `'auto'` | The language of the page that embeds the chat (its `lang` attribute), else the visitor's browser language, else English |
+
+`defineBot` throws on a value that is neither `'auto'` nor a valid BCP 47 tag. The language part of the tag picks the dictionary, and the full tag picks the plural rules.
+
+With `'auto'`, the launcher on your page follows the same order. Your `instructions` function receives the chosen tag as `context.locale`, so you can tell the model which language to answer in.
+
+## Plurals
+
+A text with a number has one key per plural category: `zero`, `one`, `two`, `few`, `many` and `other`, the categories `Intl.PluralRules` uses. `message.attachments` is such a text: after a page reload, the chat shows it under each message that had files.
+
+The widget asks `Intl.PluralRules` which category the number falls into for the visitor's locale and shows the text for it. When the language has no text for that category, the widget shows the `other` text.
+
+Each language uses only some categories:
+
+- **English** uses `one` and `other`. Zero is `other` in English, so `message.attachments.zero` has no effect there.
+- **Polish** uses `one`, `few`, `many` and `other` (fractions): 1 załącznik, 3 załączniki, 5 załączników.
+
+To see the categories of another language, run `new Intl.PluralRules('cs').resolvedOptions().pluralCategories` in a browser console. Override every category the language uses: if you set only `one` and `other` on a Polish bot, `few` and `many` keep their Polish defaults.
+
+## Add a language
+
+The library has dictionaries for English and Polish only, and `widget.texts` has no per-language form. For another language, set a fixed `locale` and translate every key:
+
+```ts
+defineBot({
+  // …
+  widget: {
+    locale: 'de',
+    texts: {
+      'header.title': 'Assistent',
+      'composer.placeholder': 'Nachricht eingeben…',
+      'message.attachments.one': '{count} Anhang',
+      'message.attachments.other': '{count} Anhänge',
+      // … and every other key
+    },
+  },
+});
+```
+
+- Keys you leave out show English.
+- Plurals follow the rules of the tag you set, so translate each category the language uses.
+- Keep `locale` fixed. With `'auto'`, your translations would show to every visitor, whatever their language. For a site in several languages without a dictionary, define one bot per language, each with its own `locale` and `texts`.
+- The chat document's `lang` attribute is your `locale` as soon as `widget.texts` has any key, so screen readers read your translation in the right language. Without your texts, a language without a built-in dictionary shows English, and `lang` says `en`.
+
+## All texts
+
+The table is generated from the library's dictionaries with `pnpm --filter @boldare/askdare docs:texts`.
+
+<!-- BEGIN:generated-texts -->
+<!-- Generated by `pnpm --filter @boldare/askdare docs:texts` from the dictionaries. Do not edit by hand. -->
+
+| Key | English | Polish |
+| --- | --- | --- |
+| `header.title` | Assistant | Asystent |
+| `header.newConversation` | Start a new conversation | Zacznij nową rozmowę |
+| `header.close` | Close chat | Zamknij czat |
+| `confirm.newConversation` | Start a new conversation? The current one will be deleted. | Zacząć nową rozmowę? Obecna zostanie usunięta. |
+| `confirm.cancel` | Cancel | Anuluj |
+| `confirm.accept` | Start new | Zacznij nową |
+| `welcome.label` | Welcome | Powitanie |
+| `welcome.greeting` | Hi! How can I help? | Cześć! W czym mogę pomóc? |
+| `welcome.online` | Online | Online |
+| `welcome.suggestions` | Suggested questions | Proponowane pytania |
+| `composer.placeholder` | Type your message… | Napisz wiadomość… |
+| `composer.send` | Send | Wyślij |
+| `composer.attach` | Attach files | Dołącz pliki |
+| `composer.dictate` | Dictate a message | Podyktuj wiadomość |
+| `status.loading` | Loading the conversation… | Wczytuję rozmowę… |
+| `status.thinking` | Thinking… | Myślę… |
+| `status.searching` | Searching documents… | Przeszukuję dokumenty… |
+| `status.tool` | Using {name}… | Korzystam z narzędzia {name}… |
+| `status.typing` | The assistant is typing | Asystent pisze |
+| `message.sources` | Sources | Źródła |
+| `message.attachments.zero` | — | — |
+| `message.attachments.one` | {count} attachment | {count} załącznik |
+| `message.attachments.two` | — | — |
+| `message.attachments.few` | — | {count} załączniki |
+| `message.attachments.many` | — | {count} załączników |
+| `message.attachments.other` | {count} attachments | {count} załącznika |
+| `attachment.list` | Attachments | Załączniki |
+| `attachment.uploading` | Uploading… | Wysyłam… |
+| `attachment.remove` | Remove {name} | Usuń {name} |
+| `attachment.unsupported` | This file type is not supported. | Ten typ pliku nie jest obsługiwany. |
+| `attachment.tooLarge` | Too large (max {size}). | Za duży (maks. {size}). |
+| `attachment.tooMany` | You can attach up to {count} files per message. | Limit plików w jednej wiadomości: {count}. |
+| `dictation.listening` | Listening… | Słucham… |
+| `dictation.transcribing` | Transcribing… | Przepisuję… |
+| `dictation.cancel` | Cancel dictation | Anuluj dyktowanie |
+| `dictation.done` | Done | Gotowe |
+| `dictation.empty` | Nothing was recorded. Please try again. | Nic się nie nagrało. Spróbuj ponownie. |
+| `microphone.blocked` | Microphone access is blocked. Allow it in your browser to dictate. | Dostęp do mikrofonu jest zablokowany. Zezwól na niego w przeglądarce. |
+| `microphone.missing` | No microphone was found. | Nie znaleziono mikrofonu. |
+| `microphone.failed` | The microphone could not be started. | Nie udało się włączyć mikrofonu. |
+| `disclosure.text` | You’re chatting with an AI assistant. It can make mistakes. | Rozmawiasz z asystentem AI. Może popełniać błędy. |
+| `disclosure.privacy` | Privacy policy | Polityka prywatności |
+| `launcher.label` | Ask us | Zapytaj nas |
+| `launcher.open` | Open chat | Otwórz czat |
+| `launcher.close` | Close chat | Zamknij czat |
+| `launcher.unavailable` | The chat couldn’t load. Please try again later. | Nie udało się załadować czatu. Spróbuj ponownie później. |
+| `error.connection` | Connection problem. Please try again. | Problem z połączeniem. Spróbuj ponownie. |
+| `error.history` | Could not load the previous conversation. | Nie udało się wczytać poprzedniej rozmowy. |
+| `error.updated` | The assistant was updated. Please reload the page. | Asystent został zaktualizowany. Odśwież stronę. |
+| `error.stalled` | The connection stalled. Please try again. | Połączenie zostało przerwane. Spróbuj ponownie. |
+| `error.uploadFailed` | The file could not be uploaded. | Nie udało się wysłać pliku. |
+| `error.transcriptionFailed` | The recording could not be transcribed. | Nie udało się przepisać nagrania. |
+| `error.invalid_input` | The request was invalid. | Nieprawidłowe żądanie. |
+| `error.unauthorized` | Authentication is required. | Wymagane jest uwierzytelnienie. |
+| `error.session_expired` | Your session has expired. Please try again. | Sesja wygasła. Spróbuj ponownie. |
+| `error.not_found` | Not found. | Nie znaleziono. |
+| `error.content_blocked` | This message cannot be processed. | Nie możemy przetworzyć tej wiadomości. |
+| `error.rate_limited` | Too many messages. Please wait a moment. | Zbyt wiele wiadomości. Poczekaj chwilę. |
+| `error.budget_exceeded` | The assistant is unavailable for the rest of the day. | Asystent jest niedostępny do końca dnia. |
+| `error.internal_error` | Something went wrong. Please try again. | Coś poszło nie tak. Spróbuj ponownie. |
+| `error.upstream_error` | The assistant is temporarily unavailable. Please try again. | Asystent jest chwilowo niedostępny. Spróbuj ponownie. |
+| `error.bot_unavailable` | The assistant is currently unavailable. | Asystent jest obecnie niedostępny. |
+| `error.timeout` | The assistant took too long to respond. Please try again. | Odpowiedź trwała zbyt długo. Spróbuj ponownie. |
+| `error.conversationTooLong` | This conversation is too long. Please start a new one. | Ta rozmowa jest zbyt długa. Zacznij nową. |
+| `error.conversationGone` | This conversation is no longer available. | Ta rozmowa nie jest już dostępna. |
+| `error.messageLength` | Messages can be up to {max} characters. | Wiadomość może mieć maksymalnie {max} znaków. |
+| `error.attachmentExpired` | An attachment expired or is invalid. Please attach it again. | Załącznik wygasł lub jest nieprawidłowy. Dołącz go ponownie. |
+| `error.filesNotAccepted` | This assistant does not accept files. | Ten asystent nie przyjmuje plików. |
+| `error.tooManyFiles` | Attach up to {count} files per message. | Limit plików w jednej wiadomości: {count}. |
+| `error.fileType.images` | Only images (PNG, JPEG, WebP, GIF) are supported. | Obsługujemy tylko obrazy (PNG, JPEG, WebP, GIF). |
+| `error.fileType.pdf` | Only PDF files are supported. | Obsługujemy tylko pliki PDF. |
+| `error.fileType.both` | Only images (PNG, JPEG, WebP, GIF) and PDF files are supported. | Obsługujemy tylko obrazy (PNG, JPEG, WebP, GIF) i pliki PDF. |
+| `error.fileTooLarge` | Files can be up to {size}. | Plik może mieć maksymalnie {size}. |
+| `error.pdfPages` | PDFs can have up to {max} pages. | PDF może mieć maksymalnie {max} stron. |
+| `error.voiceNotAccepted` | This assistant does not accept voice input. | Ten asystent nie przyjmuje nagrań głosowych. |
+| `error.recordingFormat` | This recording format is not supported. | Ten format nagrania nie jest obsługiwany. |
+| `error.recordingTooLong` | This recording is too long. | To nagranie jest zbyt długie. |
+| `error.dictationBusy` | Another dictation is still being transcribed. Please try again in a moment. | Poprzednie nagranie jest jeszcze przepisywane. Spróbuj za chwilę. |
+| `error.dictationBudget` | Dictation is unavailable for the rest of the day. You can still type. | Dyktowanie jest niedostępne do końca dnia. Wiadomość możesz nadal wpisać. |
+
+A dash (—) means the language has no text of its own for that plural category, so the widget shows the `other` text.
+<!-- END:generated-texts -->

package/docs/themes.md

@@ -0,0 +1,172 @@
+# Themes
+
+The widget comes with four looks, each in light and dark. Pick one, adjust it, or build your own on top of one. The decisions behind this are in [ADR-0008](https://github.com/boldare/askdare/blob/main/docs/adr/0008-ui-customization-and-themes.md).
+
+## Pick a preset
+
+```ts
+defineBot({
+  // …
+  widget: {
+    title: 'Brightloop assistant',
+    subtitle: 'Answers from our help center',
+    greeting: 'Hi! How can I help?',
+    starters: ['What does the Business plan include?', 'What are your support hours?'],
+    theme: 'sage', // aura (default), halo, sage, care
+    colorScheme: 'auto', // or 'light', 'dark'
+  },
+});
+```
+
+| Preset | Character | Welcome | Launcher | Fonts |
+| --- | --- | --- | --- | --- |
+| **Aura** (default) | Soft glass for AI products in Boldare's colors: an airy pastel field, a glossy bubble with its reflection, a two-weight headline (`**bold**` words in the greeting), a card composer with a Send pill | Centred greeting with pill suggestions | Orb | Plus Jakarta Sans |
+| **Halo** | Clean and friendly: white into ice blue, a frosted orb in rings of light, a bold question, a round field with a soft blue mic | Centred greeting with pill suggestions | Orb | Geist |
+| **Sage** | A calm companion: sage and mint, light type, a mint bubble for the assistant, black pill buttons, the mic beside the field | Persona card with an "Online" pill | Pill with avatar and label | Geist |
+| **Care** | Trust first: indigo and lavender, larger hyperlegible type, AAA text contrast | Opening message with a checklist | Pill with label | Atkinson Hyperlegible Next |
+
+`starters` are clickable suggestions (up to 4). `avatar` is the assistant's picture: a path on your app such as `/avatar.png`, or a small PNG, JPEG, WebP or GIF data URL. `launcherLabel` is the text of the pill launcher (default "Ask us").
+
+To compare them, run the demo site from the repository (`site/`) with `ASKDARE_GALLERY=1` and open `/gallery`: every state of the widget (welcome, conversation, streaming, attachments, error, listening) in any preset, scheme and width. The site's home page shows the same assistant in each preset: switch the theme and show the chat as a bubble or inside the page.
+
+## Adjust a preset
+
+```ts
+import { defineTheme } from '@boldare/askdare';
+
+export const brand = defineTheme({
+  extends: 'aura',
+  accent: '#a8875c', // buttons, links and your own messages; text on it is picked for contrast
+  tokens: { radius: '12px' },
+  dark: { accent: '#d4b48a' },
+  variants: { launcher: 'pill', avatar: 'initials' },
+});
+
+defineBot({ /* … */ widget: { theme: brand } });
+```
+
+`defineTheme` validates once, so several bots can share a theme. In development, a theme whose colors are hard to read logs a warning with the failing pairs and their contrast ratios.
+
+### Tokens
+
+Each token is a CSS variable, set per bot from its theme. Colors are hex.
+
+| Token | Variable | Used for |
+| --- | --- | --- |
+| `accent`, `onAccent` | `--ask-color-accent`, `--ask-color-on-accent` | Buttons, links, focus ring, and the text on them |
+| `background` | `--ask-color-background` | Panel |
+| `surface` | `--ask-color-surface` | Assistant bubbles, cards, chips |
+| `text`, `muted` | `--ask-color-text`, `--ask-color-muted` | Text, secondary text |
+| `border` | `--ask-color-border` | Hairlines (alpha allowed: `#rrggbbaa`) |
+| `danger`, `success` | `--ask-color-danger`, `--ask-color-success` | Errors, checks |
+| `userBubble`, `onUserBubble` | `--ask-color-user-bubble`, `--ask-color-on-user-bubble` | The visitor's messages |
+| `backdrop` | `--ask-backdrop` | Background behind the panel, such as a gradient, or `none` |
+| `orb` | `--ask-orb` | Paint of the orb avatar and launcher |
+| `fontFamily`, `headingFamily` | `--ask-font-family`, `--ask-font-family-heading` | Text and headings |
+| `fontSize` | `--ask-font-size` | Base size, 13px to 20px |
+| `radius` | `--ask-radius` | Corner radius, 0px to 32px |
+
+CSS values (`backdrop`, `orb`) may not contain `url()`, braces, semicolons or backslashes: they are written into a stylesheet.
+
+### Variants
+
+| Variant | Values |
+| --- | --- |
+| `avatar` | `orb`, `icon`, `initials`, `none` (a configured `avatar` picture wins) |
+| `welcome` | `hero`, `persona`, `intro` |
+| `launcher` | `orb`, `circle`, `pill` |
+| `bubbles` | `filled`, `plain` |
+| `surface` | `solid`, `glass` |
+| `density` | `comfortable`, `compact` |
+| `composer` | `outline`, `gradient` |
+
+Variants are set as attributes on the iframe document (`data-ask-welcome="persona"` and so on), so your own CSS can target them too.
+
+## Example: a theme in your brand
+
+The demo site's BLDR theme puts the chat in Boldare's style: ink and light grey, heavy type, square corners, and yellow buttons with a hard ink shadow. It takes three steps, all on the public API. Try it on the home page: pick the yellow diamond in the dock at the bottom.
+
+**1. Tokens and variants** set the colors, type and shapes. Start from the preset closest to your brand and override what differs:
+
+```ts
+import { defineTheme } from '@boldare/askdare';
+
+export const bldr = defineTheme({
+  extends: 'halo',
+  tokens: {
+    accent: '#242424',
+    onAccent: '#ffffff',
+    background: '#f1f1f1',
+    surface: '#ffffff',
+    text: '#242424',
+    muted: '#4f4f4f',
+    border: '#24242433',
+    userBubble: '#242424',
+    onUserBubble: '#ffffff',
+    backdrop: 'none',
+    orb: 'radial-gradient(circle at 35% 30%, #fff7c2 0%, #f2da3a 50%, #c4ac12 100%)',
+    // Aura's font: it ships with the library, so the chat can use it in any theme.
+    fontFamily: '"Plus Jakarta Sans Variable", system-ui, sans-serif',
+    headingFamily: '"Plus Jakarta Sans Variable", system-ui, sans-serif',
+    radius: '0px',
+  },
+  variants: { avatar: 'initials', launcher: 'pill', surface: 'solid', composer: 'outline' },
+});
+```
+
+**2. Your own CSS** in `widget.css` adds what tokens can't: the dark header, the yellow highlight in the greeting, and hard shadows that buttons press into. Select parts by `data-ask-part` ([Styling](styling.md#2-your-own-css)):
+
+```ts
+const BLDR_CSS = `
+  [data-ask-part="header"] { background: #242424; color: #fff; border-bottom: 0; }
+  [data-ask-part="subtitle"] { color: #c9c9c9; }
+  [data-ask-part="header"] button { color: #fff; }
+  [data-ask-part="avatar"] { border-radius: 0; background: #f2da3a; color: #242424; font-weight: 800; }
+  [data-ask-part="greeting"] strong { padding: 0 0.15em; background: #f2da3a; box-decoration-break: clone; }
+  [data-ask-part="starter"] {
+    border: 2px solid #242424; border-radius: 0; background: #fff; box-shadow: -4px 4px 0 #242424;
+  }
+  [data-ask-part="starter"]:hover:not(:disabled) {
+    transform: translate(2px, -2px); box-shadow: -6px 6px 0 #242424;
+  }
+  [data-ask-part="message"][data-role="assistant"] [data-ask-part="bubble"] { border: 2px solid #242424; }
+  [data-ask-part="composer-box"] { border: 2px solid #242424; border-radius: 0; box-shadow: none; }
+  [data-ask-part="send"] {
+    border: 2px solid #242424; border-radius: 0; background: #f2da3a; color: #242424;
+    box-shadow: -3px 3px 0 #242424;
+  }
+`;
+
+defineBot({
+  // …
+  widget: {
+    theme: bldr,
+    css: BLDR_CSS,
+    greeting: 'Your **AI partner** for Brightloop questions', // **bold** gets the yellow highlight
+    launcherLabel: 'Ask Boldare',
+  },
+});
+```
+
+**3. The chat button** is on your page, not in the chat, so style it with your page's CSS through `::part(launcher)`. See "The launcher" in [Styling](styling.md#2-your-own-css):
+
+```css
+[data-askdare="bldr"]::part(launcher) {
+  border: 2px solid #242424;
+  border-radius: 0;
+  background: #f2da3a;
+  color: #242424;
+  box-shadow: -4px 4px 0 #242424;
+}
+```
+
+Check the result in both color schemes, or set `colorScheme: 'light'` as BLDR does when you style only one. In development, `defineTheme` warns about color pairs that are hard to read; it can't check colors in your own CSS, so check those yourself.
+
+## Fonts
+
+Fonts are OFL-licensed and served by your app, never from a CDN. A browser downloads only the fonts the chosen preset renders, and only the Latin Extended file when the text needs it (Polish, for example): at most about 80 KB per preset.
+
+## How it is served
+
+- The theme is a small stylesheet per bot, `/api/chat/theme/<bot>.css`, with a content hash in its URL, so the first paint already has the right colors. The iframe's CSP forbids inline styles.
+- The launcher on the host page follows the theme: load the script as `widget.js?bot=<id>` and the server includes that bot's launcher look (colors, label, avatar path; public configuration) in it. `data-bot` on the tag still works, with the default launcher.

package/docs/tools.md

@@ -0,0 +1,52 @@
+# Tools
+
+Tools are server-side functions the model may call during a conversation: look up an order, check a price, fetch the weather. You describe the arguments with a Zod schema; askdare validates every call before your code runs.
+
+```ts
+// tools.ts
+import { defineTool } from '@boldare/askdare';
+import { z } from 'zod';
+
+export const orderStatus = defineTool({
+  name: 'get_order_status',
+  description: 'Status of an order by its number. Use it when the visitor asks about an order.',
+  input: z.object({
+    orderNumber: z.string().regex(/^\d{6}$/).describe('Six-digit order number'),
+  }),
+  execute: async ({ orderNumber }, { signal }) => {
+    const response = await fetch(`https://shop.example.com/api/orders/${orderNumber}`, { signal });
+    if (!response.ok) return { error: 'No such order.' };
+    const order = (await response.json()) as { status: string };
+    return { orderNumber, status: order.status };
+  },
+});
+```
+
+```ts
+// askdare.config.ts
+defineBot({
+  // …
+  tools: [orderStatus],
+});
+```
+
+## How a call works
+
+1. The model decides to call a tool and proposes arguments.
+2. askdare validates them with your schema. Invalid arguments go back to the model as an error, and `execute` doesn't run.
+3. `execute` runs on your server, with a timeout (`timeoutMs`, 10 seconds by default). Several calls in one step run in parallel.
+4. Whatever `execute` returns goes back to the model as JSON. Return `{ error: '…' }` for failures the model should explain; a thrown error reaches the model as a generic failure.
+5. The visitor sees only a short status ("Using get_order_status…"), never the arguments or the result.
+
+A bot makes at most `limits.maxSteps` model calls per message (default 5); the last one must answer in words.
+
+## Rules
+
+- **Every field is required.** OpenAI's strict mode demands it: use `.nullable()` instead of `.optional()`. `defineTool` fails at startup otherwise.
+- **Describe well.** The model picks tools by `description` and fills fields by their `.describe()`.
+- **Never trust the model with identity.** The model can be talked into anything, so a tool must not take user IDs, emails or permissions from its arguments. The second argument of `execute` holds what askdare verified: `botId`, `visitorId` (pseudonymous, created by the server), `locale`, `identity` (the signed-in user, when your site [identifies](identity.md) them) and an abort `signal`.
+- **Read-only, for now.** Tools that change data (place an order, send an email) need the visitor's confirmation, which askdare doesn't offer yet. Keep tools to lookups.
+- **Keep results small.** Return the fields the model needs. Large results cost input tokens on every later message.
+- **Keep it under about 20 tools per bot.** More tools make the model slower and less accurate.
+
+The demo site has two working examples in [`site/tools.ts`](https://github.com/boldare/askdare/blob/main/site/tools.ts).