OpenMax
Free Trial

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, ChatConversation and ChatAttachment are 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 throw ChatSdkConfigError at 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. createChatHost takes it from the adapter's groupManagement (the OpenMax adapter has it); ports cannot add it. Profile cards need profiles on the adapter and profileCardActions passed to createChatHost, see Profile card.
  • Your own messages briefly look like someone else's on first render. The user id is "" until the current user loads; ChatProvider then 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 typing frames and ConversationHeader shows who else is typing; the composer does not send it, so on OpenMax the indicator only lights up when an Agent runtime sends typing. With the component library alone you still compute typingText for ChatHeader yourself. If GET /me never 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 wired attention shows nothing. For your own handling, pass onUnauthorized on the { adapter } form.
  • The one-line config does not take onUnauthorized. Its type rejects it; passing it from JavaScript throws ChatSdkConfigError at host creation, so your code gets no callback to redirect to sign-in when the session expires. For the callback, use createChatHost({ adapter: createOpenMaxAdapter(config), onUnauthorized }); see Error model · onUnauthorized.
  • The one-line config does not take onEvent either. Passing it throws ChatSdkConfigError at host creation; to receive the events message-display plugins send, use createChatHost({ 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.onboarding events in onEvent and report them once you can. cards.openCreateAgent is 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 localData to 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 over agentActivity signals on the realtime channel gets the run blocks, the orphan list and the header run summary; one that fills agent_run_summary on messages gets the summary bar on replies (OpenMax does both by default; the factory option agentActivity: false turns 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's ttl_ms; observers receive no frames. Planned Agent runs will replace it.
  • AGENT_STREAM messages 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 ConversationList without conversations) unmounts the whole React tree. Add your own error boundary to isolate modules (a class component with componentDidCatch, or a library such as react-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 own react-i18next, with an instance from createChatI18n; inside ChatProvider the surfaces ask the i18n capability first and use useTranslation only for keys it does not know, or when mounted outside ChatProvider. Some components call your i18n.t with { ns } (agent, common); if your t drops that option, those labels are empty or show raw keys. See Internationalization.
  • MessageThread has no header. With the SDK, place ConversationHeader above it; with the component library only, place ChatHeader and pass its title, subtitle and badges.
  • ConversationHeader has 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 an offline (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-order presence frames are corrected at the next re-read. Without profiles, presence waits for the first presence signal. Changes in the subtitle line (typing, peer status) are not announced to screen readers.
  • ConversationHeader model switching and the read-only model name rely on profiles for the owner. Without profiles (or when the member data cannot be read) the owner is recognized only by the configuration's configurable: 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 agentOrigin in the member data. When the adapter's member data carries no agentOrigin / 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 one GET …/model-config the server rejects. When your adapter returns an Agent, give agentOrigin (and memberStatus: "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 ChatInfoPanel lacks onLeave, onDelete, onRemoveMembers or onAddMembers, the confirm dialog opens and then nothing happens. Without memberStatus, every member shows as offline.
  • Without the cards capability, 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 by createChatHost can answer cards when the adapter has cards (the OpenMax one-line form takes no cards options, 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 / ChatDockColumn are not complete yet. With storage: "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 (onPopOut on ConversationHeader, dragOut on CwsConversationList); 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 render draws 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 ChatRoot are both required. Without @openmaxai/chat-sdk/styles.css, or outside a ChatRoot, 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, .border or .collapse also 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 button or .page a, still change elements inside the chat.
  • Classes you pass to SDK components lose to ours. A className of 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 {} or a {} only for the properties they set themselves (box sizing, margins, padding and borders, button background and font, link color, …). Any other property, such as letter-spacing, word-spacing or text-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, and button { text-transform: uppercase } changes its buttons. ChatShadowRoot solves 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, --border and --color-*, are inherited by the content you put in the slot. Utilities in the slot that use those same-named variables (such as bg-primary or border-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 ChatProvider wraps ChatRoot from outside, the viewer that ChatProvider brings renders outside ChatRoot and does not get the chat's styles. Put ChatProvider inside ChatRoot, or pass your own viewer through createChatHost({ 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-transform and other inherited properties: set on body or another ancestor of ChatRoot, they apply inside the chat.
  • The chat changes body at 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 sets body.style.userSelect. Both are restored afterwards.
  • Ancestors of the container can clip overlays. Overlays land inside the ChatRoot container. If an ancestor has transform, filter or contain, 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. Pass overlayContainer with a body-level node; with ChatFloatingSurfaces or ChatDockColumn always pass it (see Installation · Floating surfaces and overlayContainer).
  • Overlays use body for the first frame (ChatRoot only). Until the landing node is mounted (the first commit of ChatRoot), or while the overlayContainer of ChatRoot is null, overlays render into body without the scope classes. ChatShadowRoot does not have this limitation: its landing node exists before children first render, and overlayContainer set to null means the same as omitting it, so overlays land in the default landing node inside the shadow root and never go to body (see ChatShadowRootProps).
  • 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-default shows that cursor here. Layout and colors are the same.
  • @property registrations 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; @property cannot 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 at 16.8px.
  • React events bubble through the React tree. An overlay rendered under body (or under overlayContainer) still sends its React events to the React ancestors of ChatRoot.
  • Hover enter handlers you put inside ChatShadowRoot can miss the enter. When the pointer moves straight from a React-rendered node on your page onto an element inside ChatShadowRoot, React does not fire onMouseEnter / onPointerEnter on it: the two halves of the enter (mouseout and mouseover) 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 with onMouseOver; handlers you add inside ChatShadowRoot yourself are left as they are, so use onMouseOver / onPointerOver for 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; ChatShadowRoot uses 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; use modal={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 ChatShadowRoot can run twice for one click. In our tests one click on a message inside ChatShadowRoot ran an onClick on the parent of <omx-chat-host> twice, the same in Chromium, WebKit and Firefox: first with e.target the element that was clicked, then with e.target the <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 of ChatShadowRoot, 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 whose e.target is the <omx-chat-host> element.
  • Your document-level listeners see <omx-chat-host> as the target. Events from inside the shadow root, such as focusin and keydown, reach listeners on document retargeted to the shadow host. This is how Shadow DOM works; read event.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 ChatShadowRoot yourself 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 inside ChatShadowRoot (a dialog, a modal menu, a Select) 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, outside ChatShadowRoot.
  • 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's head as soon as the SDK loads, whether or not a ChatShadowRoot (or any chat) is mounted; this also happens with ChatRoot. Its rules only select [data-vaul-*] attributes and leave your elements alone, but it also declares unprefixed global @keyframes (fadeIn, fadeOut, slideFromBottom and others): if your page has keyframes with the same names, whichever comes later in the document wins.
  • aria-hidden is only applied inside the main area. While a modal chat dialog is open, the islands at body level (the floating surfaces) stay reachable for screen readers; they are interactive surfaces and are meant to stay reachable.

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.