@hachther/akilio-widget 0.6.6 → 0.7.0

package/README.md

@@ -37,6 +37,74 @@ citations, products, and suggestions).
 Use `streaming={false}` or `data-streaming="false"` to use `POST /api/v1/chat/`
 for compatibility with an older backend or proxy.
 
+## Response notification sound
+
+An optional dependency-free chime can notify visitors when the final response
+arrives, including while the browser tab is in the background:
+
+```tsx
+<AkilioWidget
+  projectKey='your-project-key'
+  enableResponseSound
+  responseSoundVolume={0.22}
+/>
+```
+
+Standalone scripts use `data-enable-response-sound="true"` and optionally
+`data-response-sound-volume="0.22"`. The sound is disabled by default. It is
+prepared when the visitor sends a question to comply with browser autoplay
+rules, plays only for successful final responses, downloads no audio file, and
+never blocks message delivery if audio is unavailable or denied.
+
+## Launcher position
+
+The built-in launcher defaults to the bottom-right corner. It can also be
+placed at the bottom-left or displayed as a vertical tab in the middle of the
+right viewport edge:
+
+```tsx
+<AkilioWidget
+  projectKey='your-project-key'
+  launcherPosition='right-middle'
+/>
+```
+
+Supported values are `bottom-right`, `bottom-left`, and `right-middle`. The
+`right-middle` position automatically opens a full-height right drawer on
+desktop, even when the configured mode is `floating`. On mobile it returns to
+the compact bottom-right launcher and the normal mobile presentation.
+
+The standalone equivalent is `data-launcher-position="right-middle"`.
+
+## Page-end contextual prompt
+
+Documentation pages can show a compact “Ask about this page” input when the
+reader approaches the end of the document:
+
+```tsx
+<AkilioWidget
+  projectKey='your-project-key'
+  contextualPrompt={{
+    enabled: true,
+    trigger: 'near-page-end',
+    threshold: 320,
+    placeholder: 'Ask a question about this page...',
+    dismissible: true,
+  }}
+/>
+```
+
+Submitting opens the main chat and sends the question through its normal
+authenticated streaming flow with the current page URL and title. The prompt
+does not steal focus, stays hidden while chat is open, supports Escape and a
+dismiss button, and does not appear before required privacy consent is granted.
+It uses an `IntersectionObserver` end marker with a scroll fallback.
+
+Standalone attributes are `data-contextual-prompt="true"`,
+`data-contextual-prompt-threshold="320"`,
+`data-contextual-prompt-placeholder="Ask about this page..."`, and
+`data-contextual-prompt-dismissible="true"`.
+
 ## Server widget policy
 
 The public project configuration may include an authoritative `widget_policy`.
@@ -132,6 +200,26 @@ The coachmark stays inside the widget’s style boundary, does not darken or blo
 the host page, does not steal keyboard focus, and respects reduced-motion
 preferences.
 
+## Capability-driven chat actions
+
+The widget reads `capabilities.chat` from the public project configuration. An
+enabled `summarize_page` intent that supports the `widget` surface is shown as
+an explicit “Summarize this page” action when its `page.url` requirement is
+available. Selecting it sends `intent: "summarize_page"` and the current page
+context to the chat endpoint. Unsupported, disabled, wrong-surface, or
+unmet-requirement actions are not displayed. Older API responses without the
+capability catalog retain the previous suggestion behavior.
+
+An enabled `contact` intent adds a “Contact the team” action. Contact responses
+can display validated `email`, `phone`, and `form` links from `contact_options`.
+When the response includes a `start_contact_request` action and public
+configuration enables `capabilities.chat.contact_request`, the widget renders
+the advertised fields as an inline contact form. It applies the server-provided
+consent text, submits through the authenticated `/contact-requests/` endpoint,
+prevents submission without required consent, and displays success, progress,
+failure, dark-mode, and mobile states. Repeating the source message remains
+idempotent on the API.
+
 Production React and standalone JavaScript widget for the Akilio backend.
 
 ## Included modes