@aiden-voice/widget 0.8.0 → 0.9.1

package/README.md

@@ -96,10 +96,15 @@ across renewals.
   })
   ```
 
-  Without it, or when it fails or returns an unusable token, the visitor sees
-  "This chat session has expired. Reload the page to continue." and their
-  message is put back in the message box. A page served with an already
-  expired `sessionToken` also tries `getSessionToken` before giving up.
+  Without it, or when it returns an empty or already expired token, the
+  visitor sees "This chat session has expired. Reload the page to continue."
+  When it throws or takes longer than 15 seconds, the failure may pass, so the
+  visitor sees "Something went wrong, please try again." and can send again,
+  which asks `getSessionToken` once more. Either way their message is put back
+  in the message box. A page served with an already
+  expired `sessionToken` also tries `getSessionToken` before giving up, and
+  shows no chat button until it answers (at most 15 seconds: a renewal that
+  takes longer counts as failed).
 
 Branding (`color`, `inkColor`, `accentColor`, `name`) follows one rule in
 both modes: **a value you pass to `init()` always wins**, anything you leave
@@ -129,6 +134,7 @@ throws synchronously, at call time, if you pass both or neither.
 | `getSessionToken` | `sessionToken` mode only: a function returning a fresh session token (or a promise of one) from your backend, called when the current one has run out or is refused. Without it an expired session ends the chat until the page is reloaded. Ignored, with a warning, with `publishableKey` or when not a function. | none |
 | `language` | Language of the widget's own text, as a BCP 47 tag (`'fr'`, `'pt-BR'`, `'zh-CN'`). Without it the widget follows the page's `<html lang>`, then English. See [Language](#language). | the page's language, else `'en'` |
 | `messages` | Replaces individual built-in strings in the active language, e.g. `{ newConversation: 'Start over' }`. See [Language](#language). | none |
+| `contentLanguage` | The language of the conversation's content (replies, the visitor's messages, and your `greeting`, `title`, `name` and image text), as a BCP 47 tag, so screen readers read it with the right voice. Separate from `language`, which only sets the widget's own text; `language` counts only for a page with no `<html lang>`. See [Language](#language). | the page's `<html lang>`, else `language`, else unknown |
 | `position` | Launcher/panel corner: `'bottom-right'` or `'bottom-left'`. | `'bottom-right'` |
 | `color` | Primary accent color (any valid CSS color). Overrides the color configured in whoo-aiden; omit it to use that one. | whoo-aiden's, else `'#4f46e5'` |
 | `inkColor` | Body text color (chat title and replies). Darkened automatically if needed to stay readable. Overrides the color configured in whoo-aiden; omit it to use that one. | whoo-aiden's, else `'#111111'` |
@@ -136,18 +142,41 @@ throws synchronously, at call time, if you pass both or neither.
 | `name` | Agent name for the panel header and the dialog's screen-reader label ("Chat with {name}"). Overrides the name configured in whoo-aiden; omit it to use that one. | whoo-aiden's, else `'Aiden'` |
 | `title` | Full panel title, used for the header heading and the dialog's screen-reader label. Replaces the whole "Chat with {name}" string (e.g. `'Ask our concierge'`), with surrounding whitespace trimmed; the agent's messages are still labelled with its name. A blank value is ignored. | `'Chat with {name}'` |
 | `greeting` | Welcome text shown in the panel before the first message. | none |
+| `notice` | A notice, such as a disclaimer or terms of use, pinned at the top of the conversation. Unlike `greeting` it stays after the visitor writes, and comes back after "New conversation". Screen readers read it with the panel's title when the panel opens, until the visitor sends a first message. Supports `**bold**`, `_italic_`, `[links](https://...)` and `- ` lists; raw HTML shows as text. Blank values are ignored. See [Notice](#notice). | none |
+| `requireNoticeAgreement` | Ask the visitor to agree to `notice` before chatting: an "I agree" button (the `agreeToNotice` message) replaces the message field until they do. Remembered for the tab session, and asked again if the notice text changes. Ignored, with a console warning, without a `notice`. See [Notice](#notice). | `false` |
 | `launcherIconUrl` | Image shown on the launcher bubble instead of the default chat icon. `https:` or `data:image/` only. Until it loads, and permanently if it fails, the default icon shows. Alias of `theme.launcher.iconUrl`. | none (default icon) |
 | `theme` | Colors, font and launcher icons. See [Theming](#theming). | defaults |
 | `layout` | Launcher position and size, and panel size. See [Layout](#layout). | defaults |
 | `emptyStateImageUrl` | Image (e.g. a brand lockup) shown above the greeting while the conversation is empty. `https:` or `data:image/` only. Removed if it fails to load. | none |
 | `emptyStateImageAlt` | Alt text for `emptyStateImageUrl`. Set it when the image carries meaning (e.g. your brand name); omit it for a purely decorative image. | none (decorative) |
 | `showFeedback` | Show thumbs up/down controls under each reply so visitors can rate answers (a thumbs-down opens an optional correction form). | `false` (hidden) |
-| `zIndex` | Stacking level of the launcher and panel over your page. The default sits above carousels, sticky headers and most overlays, while leaving room above it for a cookie or consent modal. Lower it if one of your own layers should cover the chat (see the accessibility note below). While the panel fills the screen (a viewport 400px wide or less, or 420px tall or less), it is a modal dialog drawn above everything, whatever `zIndex` says. An invalid value logs a warning and uses the default. | `2147483000` |
+| `zIndex` | Stacking level of the launcher and panel over your page. The default sits above carousels, sticky headers and most overlays, while leaving room above it for a cookie or consent modal. Lower it if one of your own layers should cover the chat (see the accessibility note below). While the panel fills the screen (a viewport 400px wide or less, or 420px tall or less), it is a modal dialog in the browser's top layer: it sits above your page's layers whatever `zIndex` says, and the rest of the page, including page-level accessibility toolbars, can't be reached until it closes. A modal dialog your own page opens afterwards sits above it. An invalid value logs a warning and uses the default. | `2147483000` |
 | `apiBaseUrl` | Override the whoo-aiden API host the widget talks to. | `'https://api.aidenvoice.com'` |
 
 ### When something else already owns the corner
 
-Some third-party overlays (accessibility toolbars, chat or cookie widgets) sit at the maximum possible z-index, `2147483647`, in the same corner. No `zIndex` value can beat that: at an equal level, whichever element comes later in the page wins, and those overlays are usually injected after the widget. Move the widget to the other corner with `position: 'bottom-left'` instead.
+Some third-party overlays (accessibility toolbars, chat or cookie widgets) sit at the maximum possible z-index, `2147483647`, in the same corner. No `zIndex` value can beat that: at an equal level, whichever element comes later in the page wins, and those overlays are usually injected after the widget. Move the widget to the other corner with `position: 'bottom-left'` instead. (None of this applies while the panel fills the screen; see `zIndex`.)
+
+
+## Notice
+
+Use `notice` for text every visitor must be shown before chatting, such as a disclaimer, and `requireNoticeAgreement` to have them agree to it first:
+
+```ts
+init({
+  publishableKey: 'pk_...',
+  notice:
+    "**Welcome to Ask Aiden, our Guest Assistant!**\n\nAll information provided is for informational purposes only. By selecting \"I agree\", you accept our [Website Terms of Use](https://example.com/terms).",
+  requireNoticeAgreement: true,
+})
+```
+
+- **Where it shows:** above the conversation (below `emptyStateImageUrl`, above `greeting`), outlined rather than in a chat bubble, since it isn't something the agent said. It never leaves the transcript. The panel opens scrolled to its first line until the visitor writes.
+- **Screen readers:** the panel is described by the notice, so it's read with the title when the panel opens, until the visitor sends a first message (after that it would repeat on every open). It stays reachable as the first item of the conversation.
+- **It isn't sent to the agent** and isn't saved with the conversation.
+- **Agreement (`requireNoticeAgreement: true`):** until the visitor agrees, an "I agree" button takes the message field's place, and nothing can be sent. When the panel opens, focus is on the button, which the notice describes, so screen readers read the title, "I agree, button" and the notice; after agreeing, focus moves to the message field. The agreement lasts for the tab session (like the conversation), survives "New conversation", and is asked for again if you change the notice text. Change the label with `messages: { agreeToNotice: '...' }`; if you do, make the notice text match it.
+- **No record is kept.** The agreement lives only in the visitor's browser (`sessionStorage`); the widget doesn't send it to whoo-aiden, so it is no proof of consent. Whether that, and the wording, is enough is a question for your legal counsel.
+- **Write it in your content language,** like `greeting`. It's not translated.
 
 ## Language
 
@@ -157,11 +186,12 @@ The widget's own text (buttons, labels, status and error messages, and what scre
 - **Regional tags** match their language: `fr-CA` is French, any `pt-*` gets Brazilian Portuguese, any `es-*` gets Latin American Spanish. Simplified Chinese matches `zh`, `zh-CN`, `zh-SG` and `zh-Hans`. Traditional Chinese (`zh-TW`, `zh-HK`, `zh-Hant`) is not supported and falls back to English.
 - **Decided once, at `init()`.** If your single-page app changes `<html lang>` later, pass `language` (unmount and `init()` again to switch).
 - **Arabic is right to left:** the panel's layout mirrors (the visitor's messages on the left). The corner set by `position` doesn't change.
-- **Not translated:** the agent's replies (the model answers in whatever language it does), and `greeting`, `title` and `name`, which you write in the language you want. Each message's text takes its direction from its own content, so an English reply in an Arabic widget, or the reverse, still reads correctly.
+- **Not translated:** the agent's replies (the model answers in whatever language it does), and `greeting`, `notice`, `title` and `name`, which you write in the language you want. These are marked with the **content language**, not the widget's: `contentLanguage` if you pass it, else your page's `<html lang>` (any language, not just the eleven), else `language` if the page has no `lang`, else unknown. So on a Dutch page the widget's buttons are English, while replies and your Dutch greeting are read with a Dutch voice.
+- **Direction:** each paragraph and list item of a message takes its direction from its own first letter, so an English reply in an Arabic widget, or the reverse, still reads correctly. A paragraph that starts with a Latin name ("Aiden …") in Arabic text is laid out left to right, as the bidi standard decides.
 - **The widget marks its own language** (`lang` and `dir` on its root, naming the variant it ships: `pt-BR`, `es-419`, `zh-Hans`), so screen readers pronounce it correctly even on a page in another language.
-- **Upgrading from a version before 0.8.0:** a page whose `<html lang>` is one of these languages now gets the widget in that language, where it was English before. Pass `language: 'en'` to keep it in English.
+- **Upgrading from a version before 0.8.0:** a page whose `<html lang>` is one of these languages now gets the widget in that language, where it was English before. Pass `language: 'en'` to keep it in English; replies and your own text keep your page's language for screen readers either way.
 
-**Changing the wording.** `messages` replaces any built-in string in the active language. Write overrides in that language, or set `language` to the language of your overrides. `chatWith` takes `{name}`, the agent's name. Unknown keys, and values that aren't non-blank strings, are ignored with a console warning.
+**Changing the wording.** `messages` replaces any built-in string in the active language. Write overrides in that language, or set `language` to the language of your overrides. `chatWith` takes `{name}`, the agent's name. Unknown keys, and values that aren't non-blank strings (invisible characters such as a zero-width space count as blank), are ignored with a console warning. Overrides are marked with the widget's language: an override in another language (an English brand phrase in a French widget) is read with the widget's voice.
 
 ```js
 window.whooAidenWidget.init({
@@ -199,6 +229,8 @@ window.whooAidenWidget.init({
 | `conversationCleared` | Conversation cleared | screen-reader announcement |
 | `genericError` | Something went wrong, please try again. | error alert |
 | `sessionExpired` | This chat session has expired. Reload the page to continue. | error alert |
+| `opensInNewTab` | (opens in new tab) | screen readers only, after each link in a reply: every link in a reply opens in a new tab |
+| `agreeToNotice` | I agree | button the visitor presses to agree to the `notice`, with `requireNoticeAgreement` |
 
 **About the translations:** they were machine-drafted and cross-checked by independent AI agents (back-translation, critique, and rendering checks), not reviewed by native speakers. [docs/translation-verification.md](docs/translation-verification.md) records every check. If any wording reads wrong, override it with `messages`, and please tell us.
 
@@ -562,9 +594,18 @@ The widget distinguishes two deliberately different error tiers:
   response from the server) show a short, non-technical inline message in the
   chat panel itself (e.g. "Something went wrong, please try again"), leaving
   any partial response already rendered in place above it. A session that
-  runs out while the page is open is renewed (see Usage); only when that is
-  impossible does the panel say "This chat session has expired. Reload the
-  page to continue." instead.
+  runs out while the page is open is renewed (see Usage); when the session is
+  refused the panel says "This chat session has expired. Reload the page to
+  continue." instead. When renewing fails for a reason that may pass (offline,
+  the key's daily limit, `getSessionToken` throwing or taking over 15
+  seconds), it says "Something went wrong, please try again", because a reload
+  wouldn't help. Either way the visitor's message goes back into the message
+  box, and leaves the transcript (so a retry doesn't show it twice). Closing
+  the panel cancels a pending reply silently; the message is handed back only
+  if it never reached the server (the widget was still renewing the session).
+  A session refused after the widget is already showing (the start-up check
+  outlived its 3-second wait) no longer removes it: the panel says the session
+  expired instead.
 
 How a bad `sessionToken` is caught at start-up, without the widget ever
 holding a key to check its signature:

package/dist/components/Composer.d.ts

@@ -1,10 +1,12 @@
 import { RefObject } from 'preact';
 import { WidgetMessages } from '../i18n/messages';
-export declare function Composer({ value, onChange, onSend, disabled, inputRef, text, }: {
+export declare function isComposing(event: KeyboardEvent): boolean;
+export declare function Composer({ value, onChange, onSend, disabled, inputRef, text, contentLanguage, }: {
     value: string;
     onChange: (value: string) => void;
     onSend: () => void;
     disabled: boolean;
     inputRef?: RefObject<HTMLInputElement | null>;
     text?: WidgetMessages;
+    contentLanguage?: string;
 }): import('preact').JSX.Element;

package/dist/components/MessageFeedback.d.ts

@@ -1,7 +1,7 @@
 import { RefObject } from 'preact';
 import { FeedbackCategory, MessageFeedbackState } from '../controller';
 import { WidgetMessages } from '../i18n/messages';
-export declare function MessageFeedback({ state, containerRef, onThumbsUp, onThumbsDown, onDraftChange, onSubmitDetailed, onCancel, text, }: {
+export declare function MessageFeedback({ state, containerRef, onThumbsUp, onThumbsDown, onDraftChange, onSubmitDetailed, onCancel, text, contentLanguage, }: {
     state: MessageFeedbackState;
     containerRef?: RefObject<HTMLElement>;
     onThumbsUp: () => void;
@@ -10,4 +10,5 @@ export declare function MessageFeedback({ state, containerRef, onThumbsUp, onThu
     onSubmitDetailed: (correction: string, category: '' | FeedbackCategory) => void;
     onCancel: () => void;
     text?: WidgetMessages;
+    contentLanguage?: string;
 }): import('preact').JSX.Element;

package/dist/components/MessageList.d.ts

@@ -1,8 +1,9 @@
 import { FeedbackCategory, Message, MessageFeedbackState } from '../controller';
 import { WidgetMessages } from '../i18n/messages';
+export declare const NOTICE_ID = "whoo-widget-notice";
 type DraftChangeHandler = (messageId: string, correction: string, category: '' | FeedbackCategory) => void;
 type SubmitHandler = (messageId: string, correction: string, category: '' | FeedbackCategory) => void;
-export declare function MessageList({ messages, messageFeedback, announcement, emptyStateImage, agentName, showFeedback, isStreaming, isSlowResponse, onThumbsUp, onThumbsDown, onDraftChange, onSubmitDetailed, onCancelFeedback, text, }: {
+export declare function MessageList({ messages, messageFeedback, announcement, emptyStateImage, notice, agentName, showFeedback, isStreaming, isSlowResponse, onThumbsUp, onThumbsDown, onDraftChange, onSubmitDetailed, onCancelFeedback, text, contentLanguage, languageTag, announcementIsContent, }: {
     messages: Message[];
     messageFeedback: Record<string, MessageFeedbackState>;
     announcement: string | null;
@@ -10,6 +11,7 @@ export declare function MessageList({ messages, messageFeedback, announcement, e
         url: string;
         alt: string;
     };
+    notice?: string;
     agentName?: string;
     showFeedback?: boolean;
     isStreaming?: boolean;
@@ -20,5 +22,8 @@ export declare function MessageList({ messages, messageFeedback, announcement, e
     onSubmitDetailed: SubmitHandler;
     onCancelFeedback: (messageId: string) => void;
     text?: WidgetMessages;
+    contentLanguage?: string;
+    languageTag?: string;
+    announcementIsContent?: boolean;
 }): import('preact').JSX.Element;
 export {};

package/dist/config.d.ts

@@ -6,6 +6,7 @@ export declare const DEFAULT_Z_INDEX = 2147483000;
 export declare function resolveZIndex(zIndex: unknown): number;
 export declare const DEFAULT_AGENT_NAME = "Aiden";
 export declare function trimmedName(name: unknown): string;
+export declare function isBlankText(text: string): boolean;
 export declare function validateConfig(config: WidgetConfig): void;
 export declare function normalizeGetSessionToken(config: WidgetConfig): (() => string | Promise<string>) | undefined;
 export declare function normalizeMessages(value: unknown): Partial<WidgetMessages>;

package/dist/controller.d.ts

@@ -5,6 +5,7 @@ import { WidgetConfig } from './types';
 export declare const SLOW_RESPONSE_DELAY_MS = 8000;
 export declare const BRANDING_LOOKUP_WAIT_MS = 3000;
 export declare const TOKEN_RENEWAL_MARGIN_MS = 60000;
+export declare const RENEWAL_TIMEOUT_MS = 15000;
 export interface Message {
     role: 'user' | 'assistant';
     content: string;
@@ -30,7 +31,9 @@ export interface WidgetState {
     accentColor: string | null;
     inkColor: string | null;
     announcement: string | null;
+    announcementIsContent: boolean;
     isSlowResponse: boolean;
+    noticeAgreed: boolean;
     draft: string;
 }
 type Listener = (state: WidgetState) => void;
@@ -41,6 +44,8 @@ export declare class WidgetController {
     private sessionToken;
     private sessionTokenExpiresAt;
     private tokenRenewal;
+    private renewalGeneration;
+    private sendEpoch;
     private readonly getSessionToken;
     private conversationId;
     private readonly storageIdentifier;
@@ -51,10 +56,13 @@ export declare class WidgetController {
     readonly launcherIconUrl: string | undefined;
     readonly emptyStateImageUrl: string | undefined;
     readonly emptyStateImageAlt: string;
+    readonly notice: string;
+    readonly requireNoticeAgreement: boolean;
     readonly showFeedback: boolean;
     readonly text: WidgetMessages;
     readonly language: SupportedLanguage;
     readonly languageTag: string;
+    readonly contentLanguage: string;
     readonly dir: 'ltr' | 'rtl';
     constructor(config: WidgetConfig);
     getState(): WidgetState;
@@ -66,6 +74,7 @@ export declare class WidgetController {
     private loadBranding;
     open(): void;
     resetConversation(): void;
+    agreeToNotice(): void;
     setDraft(draft: string): void;
     close(): void;
     sendMessage(text: string): Promise<void>;
@@ -76,6 +85,7 @@ export declare class WidgetController {
     private currentToken;
     private renewToken;
     private fetchNewToken;
+    private obtainToken;
     private withSession;
 }
 export {};

package/dist/i18n/index.d.ts

@@ -20,6 +20,12 @@ export declare function resolveLanguage(option: unknown, pageLang: unknown): {
     tag: string;
     dir: 'ltr' | 'rtl';
 };
+export declare function resolveContentLanguage(option: unknown, pageLang: unknown, languageOption?: unknown): string;
+export declare function templateParts(template: string): {
+    before: string;
+    after: string;
+    hasName: boolean;
+};
 export declare function format(template: string, values: {
     name: string;
 }): string;

package/dist/i18n/messages.d.ts

@@ -25,6 +25,8 @@ export interface WidgetMessages {
     conversationCleared: string;
     genericError: string;
     sessionExpired: string;
+    opensInNewTab: string;
+    agreeToNotice: string;
 }
 export declare const ENGLISH: WidgetMessages;
 export declare const MESSAGE_KEYS: (keyof WidgetMessages)[];

package/dist/markdown/render.d.ts

@@ -1,2 +1,6 @@
 import { ComponentChildren } from 'preact';
-export declare function renderMarkdown(source: string): ComponentChildren;
+export interface RenderOptions {
+    linkCue?: string;
+    linkCueLang?: string;
+}
+export declare function renderMarkdown(source: string, options?: RenderOptions): ComponentChildren;

package/dist/storage.d.ts

@@ -1,3 +1,5 @@
 export declare function getStoredConversationId(identifier: string): string | null;
 export declare function setStoredConversationId(identifier: string, conversationId: string): void;
+export declare function hasAgreedToNotice(identifier: string, notice: string): boolean;
+export declare function setAgreedToNotice(identifier: string, notice: string): void;
 export declare function clearStoredConversationId(identifier: string): void;

package/dist/types.d.ts

@@ -94,6 +94,15 @@ export interface WidgetConfig {
      * Unknown keys and blank or non-string values are ignored with a warning.
      */
     messages?: Partial<WidgetMessages>;
+    /**
+     * The language of the conversation's content (replies, the visitor's
+     * messages, and your greeting, notice, title, name and image text), as a BCP 47
+     * tag, so screen readers read it with the right voice. Defaults to the
+     * page's <html lang>, then to `language` when the page has none, else
+     * unknown. Separate from `language`, which only sets the widget's own
+     * buttons and messages.
+     */
+    contentLanguage?: string;
     position?: 'bottom-right' | 'bottom-left';
     /**
      * Primary accent color. Overrides the color configured in whoo-aiden, in
@@ -113,6 +122,21 @@ export interface WidgetConfig {
     name?: string;
     title?: string;
     greeting?: string;
+    /**
+     * A notice (e.g. a disclaimer or terms of use) pinned at the top of the
+     * conversation. Unlike `greeting` it stays after the visitor sends a
+     * message, and screen readers read it when the panel opens until then.
+     * Supports **bold**, _italic_ and [links](https://...). Blank or non-string
+     * values are ignored.
+     */
+    notice?: string;
+    /**
+     * Require the visitor to agree to `notice` before chatting: the panel shows
+     * an "I agree" button (the `agreeToNotice` message) in place of the message
+     * field until they do. Remembered for the tab session, and asked again if
+     * the notice text changes. Ignored without a `notice`. Off by default.
+     */
+    requireNoticeAgreement?: boolean;
     /** Image shown on the launcher bubble instead of the default chat icon. Alias of `theme.launcher.iconUrl`, which wins if both are set. */
     launcherIconUrl?: string;
     /** Image shown above the greeting while the conversation is empty. */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const WIDGET_VERSION = "0.8.0";
+export declare const WIDGET_VERSION = "0.9.1";