Known limitations
What does not work yet, what you have to wire up yourself, and how to work around it.
Known limitations
Every export is @experimental. @experimental exports are not bound by semantic versioning: they can change or be removed in any release, including a minor or patch release.
Data shapes
- Messages and conversations use OpenMax field names.
ChatMessage,ChatConversationandChatAttachmentare defined by the SDK with the same field names as the OpenMax gateway (sender_id,created_at,fallback_text, …). Another backend must map into them. Missing optional fields do not throw; the UI just shows less, so check each one. - Every message needs an integer
seq. It starts at 1 per conversation, increases and never repeats. Ordering and gap-fill after a disconnect depend on it; timestamps are not a substitute.
Default host (createChatHost)
- OpenMax only. For another backend, build the host with
createLocalPorts; see Connect your own backend. - Token auth only.
auth: { mode: "logto" }and{ mode: "cookie" }exist in the type but throwChatSdkConfigErrorat construction. - Edits carry no structured @mentions. Your own reactions, edits and recalls take effect at once; reactions, edits and recalls by others appear live, and a message removed by moderation is removed from the thread; changes others made while you were offline or away are caught up from the change log on reconnect or when you switch back to the conversation.
- Group management comes only from the adapter.
createChatHosttakes it from the adapter'sgroupManagement(the OpenMax adapter has it);portscannot add it. Profile cards needprofileson the adapter andprofileCardActionspassed tocreateChatHost, see Profile card. - Your own messages briefly look like someone else's on first render. The user id is
""until the current user loads;ChatProviderthen re-renders. - Drafts typed before the current user loads stay in memory and are not carried over.
- Drafts do not sync across tabs until the next read.
- With
realtime: "off", new messages from others and card action results do not appear on their own. - No request timeout.
- A conversation with read receipts off costs one refused request each time it opens. The host does not read the conversation's receipt setting first, so the read-cursors request is sent and answered with
412; no receipt is drawn and nothing is shown. - Realtime sync frames are not acknowledged, so a reconnect may redeliver a batch.
- Typing is received, not sent. The SDK's realtime connection decodes
typingframes andConversationHeadershows who else is typing; the composer does not send it, so on OpenMax the indicator only lights up when an Agent runtime sendstyping. With the component library alone you still computetypingTextforChatHeaderyourself. IfGET /menever resolves, no typing indicator is shown for the whole scope. - No connection status. Nothing tells the user about a dropped connection or a failed gap-fill. An expired session (including a refused ticket, after which the connection stops reconnecting) only gets one "session expired" notice through
attention.notify; there is no signed-out UI state, and a host that has not wiredattentionshows nothing. For your own handling, passonUnauthorizedon the{ adapter }form. - The one-line config does not take
onUnauthorized. Its type rejects it; passing it from JavaScript throwsChatSdkConfigErrorat host creation, so your code gets no callback to redirect to sign-in when the session expires. For the callback, usecreateChatHost({ adapter: createOpenMaxAdapter(config), onUnauthorized }); see Error model ·onUnauthorized. - The one-line config does not take
onEventeither. Passing it throwsChatSdkConfigErrorat host creation; to receive the events message-display plugins send, usecreateChatHost({ adapter: createOpenMaxAdapter(config), onEvent }). - Onboarding-card impressions seen before Analytics consent are not reported again by themselves. The SDK takes no "may send now" signal: for cards already on screen before the user consents, keep the
card.onboardingevents inonEventand report them once you can.cards.openCreateAgentis read once when the host is built; to give it only to some roles, rebuild the host when the role changes.
Data and caching
- By default messages live in memory only and are loaded again after a page reload. To keep them, use
localDatato store messages on the device; see@openmaxai/chat-sdk· Local data. Planned
Agents
- What an agent is doing is visible today through
agentActivity(read-only progress (experimental · transitional)): progress and tool steps, but no Stop button. An adapter that hands overagentActivitysignals on the realtime channel gets the run blocks, the orphan list and the header run summary; one that fillsagent_run_summaryon messages gets the summary bar on replies (OpenMax does both by default; the factory optionagentActivity: falseturns them off); nothing to declare. A run without a reply is gone after a refresh, and opening a conversation or reconnecting does not fetch runs in progress; a terminal frame can be lost, so a run is marked out of sync only by the frame'sttl_ms; observers receive no frames. Planned Agent runs will replace it. AGENT_STREAMmessages show as plain text, without incremental updates.- Choice cards are not linked to runs; the agent side has to match answers to questions itself.
These three are addressed by the planned agent runs: run progress, tool steps and the stop button come through agent_event frames, and cards can carry run_id, tool_call_id and expires_at to become approval cards. Streaming text: see Message thread · Streaming output; reasoning comes later. Planned
The planned version has one known limitation of its own: stopping a run that is executing in the agent's main session may interrupt the main session too; see Stop button. Planned
Components
- No error boundaries. A module that throws (for example
ConversationListwithoutconversations) unmounts the whole React tree. Add your own error boundary to isolate modules (a class component withcomponentDidCatch, or a library such asreact-error-boundary). Built-in boundaries per area are planned; see Errors and expired sessions · Render errors. - Some strings need react-i18next. A few panels (including the @mention panel) use
useTranslation, so wrap the tree in<I18nextProvider>from your ownreact-i18next, with an instance fromcreateChatI18n; insideChatProviderthe surfaces ask thei18ncapability first and useuseTranslationonly for keys it does not know, or when mounted outsideChatProvider. Some components call youri18n.twith{ ns }(agent,common); if yourtdrops that option, those labels are empty or show raw keys. See Internationalization. MessageThreadhas no header. With the SDK, placeConversationHeaderabove it; with the component library only, placeChatHeaderand pass its title, subtitle and badges.ConversationHeaderhas no "provisioning" state yet, and the Agent run summary appearing and disappearing is not announced to screen readers. Peer presence is drawn on avatars; in a DM with a person the dot appears only after a presence signal for that person (the OpenMax backend reports no status for people yet); Agent collaboration and observed titles show no presence dot per Agent. When the backend misses anoffline(the peer's server instance crashes or a presence update is lost), a wrong "online" lasts at worst about 105 seconds (the 60-second re-read period plus the 45-second lease TTL); when the server's shared presence store is unavailable REST also answers from a single instance, so the periodic re-read cannot correct it and there is no upper bound; out-of-orderpresenceframes are corrected at the next re-read. Withoutprofiles, presence waits for the firstpresencesignal. Changes in the subtitle line (typing, peer status) are not announced to screen readers.ConversationHeadermodel switching and the read-only model name rely onprofilesfor the owner. Withoutprofiles(or when the member data cannot be read) the owner is recognized only by the configuration'sconfigurable: until the configuration is read, or when it fails, the owner sees no "yours" name tag and no model entry. The model button does not recover by itself when an Agent goes from provisioning to ready (reopen the conversation); a model changed by someone else does not update live; the model name next to an Agent sender on message bubbles costs one member-profile read per Agent shown, besides its configuration read.- External / self-hosted Agents need
agentOriginin the member data. When the adapter's member data carries noagentOrigin/memberStatus, the SDK cannot tell whether the Agent is hosted and still decides the owner as usual: for an external / self-hosted Agent without these fields, its owner sees a disabled (grey) model button on every open, and each open sends oneGET …/model-configthe server rejects. When your adapter returns an Agent, giveagentOrigin(andmemberStatus: "departed"once it has left), see Adapter interface ·agentConfig. - The read position only advances if you handle
onVisibleSeqChange. Otherwise read conversations are unread again after a reload. - Group actions are callbacks. If
ChatInfoPanellacksonLeave,onDelete,onRemoveMembersoronAddMembers, the confirm dialog opens and then nothing happens. WithoutmemberStatus, every member shows as offline. - Without the
cardscapability, cards are read-only. The card plugin is not installed; the card body and result line show, buttons and choices cannot be clicked, and nobody can answer. A host built bycreateChatHostcan answer cards when the adapter hascards(the OpenMax one-line form takes nocardsoptions, so business cards draw no buttons there); answers by others (a form card already submitted by someone else included) appear live, but "superseded" and "expired" show only once the message is read again (there is no realtime frame for them). Form-card drafts live in the SDK's local storage, on this device only. - Draft attachments are lost on refresh. Text and the quoted reply are kept.
- File drop needs
ChatFileDropZone. Floating and docked surfaces do not accept drops. - The SDK's
ChatFloatingSurfaces/ChatDockColumnare not complete yet. Withstorage: "memory"windows do not survive a reload; nothing is restored until the current user is known; on removal or deletion the window closes silently, without a notice; windows in the dock are not rehydrated after a reload, so a conversation you lost access to keeps its title in the dock until opened. The window body is the same components as the main page with the same gaps, and has no China-region AI-generated content notice. Pop-out and dragging in and out are available (onPopOutonConversationHeader,dragOutonCwsConversationList); the conversation list leaves out conversations open in a window or tab. One of each per page. See Known gaps. - The reaction picker is a fixed list. Unknown reaction codes display but cannot be picked.
- Only agent replies are Markdown. The default
renderdraws agent replies (renderMarkdown) as Markdown; text messages from people (TEXT) are still drawn as plain text with links and mentions. Code blocks have no syntax highlighting. - Message actions are the five buttons on the action bar (copy, react, reply, edit, recall): no "More" menu or right-click menu, no pinning, and no way to add your own actions.
Styles and overlays
Inside ChatRoot the stylesheet applies only to the SDK components' own nodes (see Installation); content you put directly into ChatRoot or into an SDK component's slot is not touched by our base reset. Scoping uses class selectors, so a few things still cross the boundary in either direction:
- The SDK stylesheet and
ChatRootare both required. Without@openmaxai/chat-sdk/styles.css, or outside aChatRoot, the chat renders unstyled, with no error. - Your class rules with the same names as ours reach the chat. A rule of yours such as
.hidden,.borderor.collapsealso matches those classes inside the chat. - Your high-specificity rules win. Our utility classes are (0,2,0) (
.omx-chat .flex). Your rules at (0,2,0) or above, or with an id, such as#app buttonor.page a, still change elements inside the chat. - Classes you pass to SDK components lose to ours. A
classNameof yours (.my-x, (0,1,0)) does not override the chat's utility classes. Change the variables, or write.omx-chat .my-x; see Theming · Override component styles. - Your element and universal rules reach the chat for properties it does not set. The chat's own styles beat rules such as
* {},button {}ora {}only for the properties they set themselves (box sizing, margins, padding and borders, button background and font, link color, …). Any other property, such asletter-spacing,word-spacingortext-transform, still applies to the chat's elements from your rule:* { letter-spacing: 3px }on your page changes the letter spacing of almost every element in the chat, andbutton { text-transform: uppercase }changes its buttons.ChatShadowRootsolves this, see Shadow DOM. - Content in a slot inherits the SDK component's font and variables. A slot sits inside an SDK component: the font, font size, line height and color on the component root, and variables such as
--primary,--borderand--color-*, are inherited by the content you put in the slot. Utilities in the slot that use those same-named variables (such asbg-primaryorborder-border) get the chat's values, and a class with the same name as ours matches our rule (mostly with the same value). Our utilities with a descendant variant (such as[&_a]:underline, which applies to every<a>inside) also match your nodes in a slot, for example links in your custom message card inside a message bubble. What to do: inside slots, do not rely on variable classes that share names with the chat's; if you need them, set those variables to your own values on the outer element of the slot content. - With the quick-start layout, the SDK's built-in image viewer is unstyled. When
ChatProviderwrapsChatRootfrom outside, the viewer thatChatProviderbrings renders outsideChatRootand does not get the chat's styles. PutChatProviderinsideChatRoot, or pass your own viewer throughcreateChatHost({ ports: { mediaViewer } }). - Slots nested more than 3 levels deep get reset again. When an SDK component with slots goes into another SDK component's slot, and so on more than 3 levels deep, your nodes in the innermost slot are changed by our base reset (margins, borders and so on).
- Inherited properties you set on an ancestor reach the chat. The scope root sets font family, size, line height and color, but not
letter-spacing,word-spacing,text-align,font-style,text-transformand other inherited properties: set onbodyor another ancestor ofChatRoot, they apply inside the chat. - The chat changes
bodyat run time. A modal dialog in the chat locks page scrolling while it is open (Radix's default; there is no option to turn it off), and dragging a floating window setsbody.style.userSelect. Both are restored afterwards. - Ancestors of the container can clip overlays. Overlays land inside the
ChatRootcontainer. If an ancestor hastransform,filterorcontain, or creates a low stacking context, a dialog's backdrop covers only that area and overlays can end up under your page's elements or under the floating windows. PassoverlayContainerwith abody-level node; withChatFloatingSurfacesorChatDockColumnalways pass it (see Installation · Floating surfaces and overlayContainer). - Overlays use
bodyfor the first frame (ChatRootonly). Until the landing node is mounted (the first commit ofChatRoot), or while theoverlayContainerofChatRootisnull, overlays render intobodywithout the scope classes.ChatShadowRootdoes not have this limitation: its landing node exists beforechildrenfirst render, andoverlayContainerset tonullmeans the same as omitting it, so overlays land in the default landing node inside the shadow root and never go tobody(seeChatShadowRootProps). - Cursor and scrollbar details differ from OpenMax. In OpenMax the pointer cursor on buttons and the scrollbar colors come from base rules that beat utility classes on the same element; in the scoped stylesheet they lose to them, so a button with
cursor-defaultshows that cursor here. Layout and colors are the same. @propertyregistrations are page-wide. The stylesheet registers Tailwind v4's--tw-*properties and eight of its own (--scroll-fade-t,--scroll-fade-b,--scroll-fade-s,--scroll-fade-e,--scroll-fade-mask,--shimmer-angle,--shimmer-image,--shimmer-text-fill) on the whole page;@propertycannot be scoped. If your page registers the same names with a different definition (another Tailwind version, for example), the first registration wins.- Container-query breakpoints do not follow
--omx-rem. They are fixed pixel values computed at16.8px. - React events bubble through the React tree. An overlay rendered under
body(or underoverlayContainer) still sends its React events to the React ancestors ofChatRoot. - Hover enter handlers you put inside
ChatShadowRootcan miss the enter. When the pointer moves straight from a React-rendered node on your page onto an element insideChatShadowRoot, React does not fireonMouseEnter/onPointerEnteron it: the two halves of the enter (mouseoutandmouseover) reach different React listeners (your root container and the portal container inside the shadow root), and the root-side half sees the shadow host instead of the real target. The SDK's own components react to hover withonMouseOver; handlers you add insideChatShadowRootyourself are left as they are, so useonMouseOver/onPointerOverfor anything that should react to hover. See Write a composer plugin. - Escape with your own Radix layers open. The chat handles Escape first only when focus is inside one of its layers (see Installation · Escape inside your dialog). Otherwise your layer takes Escape first: it closes, and when it returns focus to its trigger an open chat layer then closes too because focus moved outside it. This happens when the emoji picker was opened with the mouse (focus stays on the button), when the @-mention list in the composer is open, when focus is in a floating window's composer while one of the chat's dialogs is open, and when focus is on
body. Inside a closed shadow root the chat cannot tell where focus is and behaves the same way;ChatShadowRootuses an open one. Content that a chat layer portals elsewhere without being a layer itself counts as outside it. With a modal dialog of yours, focus cannot move into the chat's layers at all; usemodal={false}.
Shadow DOM
With ChatShadowRoot (experimental) some of the limitations under Styles and overlays go away, some stay, and a few new ones come in.
Under ChatRoot |
Under ChatShadowRoot |
|---|---|
| Your class rules with the same names as ours reach the chat | Solved: your selectors do not match anything inside the shadow root |
| Your high-specificity rules win | Solved, for the same reason |
| Your element and universal rules reach the chat for properties it does not set | Solved, for the same reason. A universal rule such as * { letter-spacing: 3px } still matches <omx-chat-host> itself; the inherited part of its value is handled as in the next row |
| Inherited properties you set on an ancestor reach the chat | Solved by a reset layer, not by the shadow boundary: inherited values still flow in from your ancestors and from <omx-chat-host> itself, and a reset layer (all: initial) inside the shadow root stops them. The reset layer is only injected into shadow roots, never into your page. Custom properties and direction still inherit, on purpose |
| Classes you pass to SDK components lose to ours | Still there: the same specificity, and your class rules do not reach inside the shadow root at all |
The chat changes body at run time |
Still there: the scroll lock and dragging a floating window still change your page's body |
| Ancestors of the container can clip overlays | Still there for the main area, whose landing node is inside <omx-chat-host>: pass overlayContainer="body". Floating surfaces and an overlayContainer island at body level are not affected |
Overlays use body for the first frame |
Solved: the landing node exists before children first render |
@property registrations are page-wide |
Still there: @property only works in your page's own document. When two SDK versions on one page bring different registrations, the SDK appends the second copy and logs a console.warn |
New with ChatShadowRoot:
- React handlers on ancestors of
ChatShadowRootcan run twice for one click. In our tests one click on a message insideChatShadowRootran anonClickon the parent of<omx-chat-host>twice, the same in Chromium, WebKit and Firefox: first withe.targetthe element that was clicked, then withe.targetthe<omx-chat-host>element. The chat is portalled into the shadow root within your React tree, so the React event bubbles to the React ancestors ofChatShadowRoot, as with any portal; the native event also reaches your React root, retargeted to the shadow host, and React dispatches it once more. If it matters to you, skip the call whosee.targetis the<omx-chat-host>element. - Your
document-level listeners see<omx-chat-host>as the target. Events from inside the shadow root, such asfocusinandkeydown, reach listeners ondocumentretargeted to the shadow host. This is how Shadow DOM works; readevent.composedPath()[0]for the real target. - The fallback for older browsers needs inline styles. In browsers without constructable stylesheets the SDK writes a
<style>into the shadow root instead, and a Content Security Policy that blocks inline styles blocks that fallback. - Your Radix and the chat's keep separate layer stacks. The chat ships its own copy of Radix, so your dialogs and popovers and the chat's layers do not see each other. Outside clicks are judged by each layer on its own, as with a single copy; Escape goes to the chat first only while focus is inside one of its layers (see Installation · Escape inside your dialog and Escape with your own Radix layers open above).
- Popups you render into
ChatShadowRootyourself use your own Radix. The chat's own dialogs, sheets and drawers carry the SDK's fixes for Shadow DOM: they trap focus and hide the background both on your page and inside the shadow root. A popup your code renders insideChatShadowRoot(a dialog, a modal menu, aSelect) uses your copy of Radix without those fixes, so neither the focus trap nor hiding the background is guaranteed inside the shadow root. Open such popups in your page, outsideChatShadowRoot. - Rich-text selection in WebKit and Firefox is not guaranteed. In Chromium, typing, selecting text and pasting over it, pasting, @-mentions and IME composition in the composer all work inside the shadow root. In WebKit we ran the same steps with a simulated paste event and they passed (IME not tested); in our automated setup a keyboard paste in WebKit carries no HTML, so we have no reading with a real clipboard paste. In Firefox, with a real clipboard paste, the same steps passed with and without Shadow DOM (IME not tested). We make no promise for WebKit and Firefox.
- vaul adds one global stylesheet to your page. The drawer library the SDK uses appends a
<style>to your page'sheadas soon as the SDK loads, whether or not aChatShadowRoot(or any chat) is mounted; this also happens withChatRoot. Its rules only select[data-vaul-*]attributes and leave your elements alone, but it also declares unprefixed global@keyframes(fadeIn,fadeOut,slideFromBottomand others): if your page has keyframes with the same names, whichever comes later in the document wins. aria-hiddenis only applied inside the main area. While a modal chat dialog is open, the islands atbodylevel (the floating surfaces) stay reachable for screen readers; they are interactive surfaces and are meant to stay reachable.
Accessibility
- Conversation rows have no keyboard interaction. Selecting a conversation needs a pointer or touch; see Conversation list · Accessibility.
- The group info button has no accessible name. It is icon-only, so screen readers cannot tell what it does; see Header · Accessibility.
Packaging
The packages are on npm as 3.0.0 prereleases (3.0.0-beta.*) and are released together under one version. Every export is @experimental and may change between prereleases: pin an exact version and use the same one for every @openmaxai/chat* package (see Installation). A stable 3.0.0 follows once the interfaces are frozen.
