# @olotalk/assistant
The [Olotalk](https://olotalk.com) AI chat assistant, a Svelte 5 component that mounts a RAG-powered, multilingual chat assistant into any web page via Shadow DOM.
> **Most users should use [`@olotalk/assistant-loader`](https://www.npmjs.com/package/@olotalk/assistant-loader) instead.** It handles config fetching, browser compatibility, and dynamic loading with a single `
```
A corner launcher AND a header button that opens a drawer, on one transcript.
Only one panel is open at a time: opening one closes the others, because two
panels showing the same conversation is a duplicated transcript competing for the
same screen. A shape whose sibling is open also hides its own resting affordance
for as long as that lasts, while the drawer is out, the corner launcher goes
away rather than floating on top of it inviting you to open what is already
open (ADR 0246).
Adding a *shape* is how you add another panel. Adding a **way in** to the panel
you already have is cheaper, and is what `reach` and doors are for (ADR 0226):
- **`data-olotalk-open`, your own affordances, no JavaScript.** Put the
attribute on any element you already have and it becomes a door:
```html
```
One delegated listener handles the page, so a button rendered later by a
framework works with no re-scan. The value names *which* mounted shape to
open; empty means the one panel on the page. `data-olotalk-prefill` opens it
with a question, which the shape then sends or leaves editable according to
its own `sendOnPrefill` (a corner bubble sends; select-to-ask holds it for
amending). A door that names a shape nothing has mounted warns and does
nothing rather than failing silently.
A plain door **toggles**, press it again while the panel is open and it
closes, which is what a header control that says "Ask AI" is read as. A door
carrying a prefill always opens instead: those mean "ask *this*", so a second
press re-asks rather than dismissing. `getAssistant(id).isOpen()` is the same
state, if you want to drive your own affordance from it.
`data-olotalk-door="branded"` opts a door into the assistant's own look, a
quiet chip at rest, the launcher's gradient rim turning around it on hover.
Opt-in on purpose: without it a door keeps *your* styles and we inject nothing,
which is the point of putting the attribute on an element you already have.
This is what makes the **drawer** installable by pasting: it has no launcher
of its own by design, and its snippet now ships the button with it,
branded, with the robot mark inline so it can blink.
- **`getAssistant(id).open({ prefill })`, the same door, in JavaScript.** For a
trigger that is not a click: a nav field's submit, a router event, your own
component. This has always been the contract: the instance registry exists so
a trigger resolves the panel that already exists rather than conjuring a
second one.
- **`reach`, our triggers, any residence.** `reach: "selection,commandk"`
raises select-to-ask and ⌘K over whatever is mounted. ⌘K toggles the
residence; it is claimed only when you ask for it, and a reach naming the
residence's own trigger is simply redundant, not an error.
**`mode: "selection"` and `reach: "selection"` are not the same thing.** The
word does double duty, and this is the easiest place to misread it:
| | at rest | ways in |
|---|---|---|
| `mode: "selection"` | nothing on the page, no button anywhere | highlighting text, and only that |
| `mode: "bubble", reach: "selection"` | the corner launcher | the launcher **and** highlighting |
Select-to-ask with no button on the page is the first one, mounted on its own:
it is a shape, not a modifier.
## The open panel is a window
Visitors can **resize** almost any panel that floats over the page, and **drag**
the anchored one. Neither is configurable: there is nothing to switch on, and
nothing an embed can turn off.
`drawer` opts out via `resizable: false` on its shape record: its width is the
amount of page it takes away, and it is the one shape whose opening already
moves the host layout (ADR 0244).
| | resize | drag |
|---|---|---|
| `bubble` · `starters` · `corner` · `commandk` · `center` | ✅ | — |
| `drawer` | — |, |
| `anchored` (select-to-ask, `mode: "anchored"`) | ✅ | ✅ |
| `inline` · `expand` · `fullpage` · `sidebar` | — |, |
| any shape at phone width | — |, |
Eight handles: 10px edge bands with 20px corners. Floor 320×360, ceiling the
viewport less a margin.
**Drag is narrower than resize on purpose.** A corner bubble keeps its launcher
on screen while open (it morphs into the close control) so moving the panel
away would orphan that button. The anchored panel has no such tether and
deliberately covers the passage it is about, so moving it is the only way to
read the original words.
The chosen **size** survives a close; the **position** never does. Press the
launcher and the assistant comes back to its corner, at the size the visitor
picked. Both gestures are pointer-only.
The in-flow shapes are your layout, so they are left alone entirely.
### Select-to-ask
Highlighting a passage raises a pill above it. Taking that offer opens the
assistant **beside the words** (even when it normally lives in the corner)
and the passage arrives as a removable quote above the composer, which stays
empty for the question the visitor actually wants to ask. Send combines the
two. Nothing is ever asked on their behalf.
**If you would rather it stayed put**, set `selectionAnswers: "in-place"`
(`data-olotalk-selection-answers="in-place"`) and the panel opens where the
assistant lives instead of travelling to the highlight. Worth it when the
assistant is a fixture your visitors have already located and the flight across
the page costs more than the distance saves; the default is `"beside"`, because
usually the answer belongs where the question was asked.
**A second highlight while the panel is open seeds the conversation already
running**: new quote, composer focused, panel not moved, anything typed kept.
The passage replaces the previous quote rather than stacking.
On touch devices the pill is deliberately absent: the OS owns that gesture,
and the only way to suppress its own Copy / Look Up menu is to disable text
selection entirely.
Reach adds entry points, never panels. Nothing starts at page load, and
opening via reach counts exactly like opening via the shape's own launcher,
a session when the panel opens, a metered message when one is sent. One
pairing is refused with a warning: `commandk` reach over the `anchored`
shape, because a keystroke names no element for an anchored panel to position
from. Try an ensemble locally:
`demo/shapes.html?mode=bubble&reach=selection,commandk`.
---
## Distribution files
| File | Format | Use case |
|---|---|---|
| `dist/olotalk-assistant.js` | ESM | Dynamic `import()` from CDN or bundler |
| `dist/olotalk-assistant.iife.js` | IIFE | Legacy browsers (`