@ada-cx/messaging-bridge 1.0.0-setup.0

package/README.md

@@ -0,0 +1,328 @@
+# @ada-cx/messaging-bridge
+
+Build your own chat UI (a "custom app") on Ada Messaging's bridge contract.
+
+This package carries TypeScript types, test mocks, and a thin loader. The
+bridge runtime always loads from Ada's CDN at
+`https://messaging-assets.ada.support/bridge.js`. Ada patches the runtime
+continuously, so your installed package version never pins security logic.
+
+## Requirements
+
+- Your custom app runs inside an iframe that Ada's core frame mounts. The
+  core frame is served from Ada's asset host, and it sits inside the page
+  that embeds the widget. Both origins are in your app's ancestor chain.
+- You point the Web SDK at your app with its `appUrl` setting. Custom apps
+  are experimental. Contact your Ada team before you build on this feature.
+- If your app's responses send no `X-Frame-Options` header and no CSP
+  `frame-ancestors` directive, browsers permit framing, and no server change
+  is needed. If your app restricts framing, `frame-ancestors` must allow
+  Ada's asset hosts and every site origin that embeds the widget:
+
+```
+Content-Security-Policy: frame-ancestors https://messaging-assets.ada.support https://static.ada.support https://your-site.com
+```
+
+  Replace `https://your-site.com` with the origins of the pages that embed
+  the Ada widget. Browsers check `frame-ancestors` against every ancestor
+  frame, so a policy that lists only Ada's hosts blocks your app.
+
+## Quick start
+
+Install the package:
+
+```bash
+npm install @ada-cx/messaging-bridge
+```
+
+Load the runtime, complete the handshake, then render from state:
+
+```ts
+import { loadMessagingBridge } from "@ada-cx/messaging-bridge";
+
+const bridge = await loadMessagingBridge();
+const client = bridge.createBridgeClient();
+
+// REQUIRED: send app.initialize within 15 seconds of your frame loading.
+// If the handshake does not arrive, core unmounts your frame.
+client.sendEvent("app.initialize");
+
+// Subscribe to display-state updates from core.
+const unsubscribe = client.subscribe(() => {
+  const state = client.getState();
+  renderMessages(state?.["chat.messages"] ?? []);
+});
+
+// Send a user message through the operations layer.
+const handle = client.operations.sendMessage("Hello");
+const message = await handle.settled();
+
+// Tear down when your app unmounts.
+unsubscribe();
+client.destroy();
+```
+
+`loadMessagingBridge()` memoizes the load. Repeated calls return the same
+promise. A failed load is forgotten, so a later call retries.
+
+Use typed state keys through the loaded module:
+
+```ts
+const botName = client.getState()?.[bridge.STATE.CONFIG_BOT_NAME];
+```
+
+## Operations
+
+`client.operations` provides typed helpers over the raw event contract. Each
+helper carries the guards, debounces, and correlation logic that Ada's own
+app uses. Prefer them over hand-built `sendEvent` calls.
+
+```ts
+// Correlated send: the handle resolves with the message row.
+const handle = client.operations.sendMessage("Hello");
+const message = await handle.settled({ timeoutMs: 10_000 });
+
+// Read tracking: debounced, monotonic, reset per conversation.
+client.operations.markRead(message.cursor ?? "");
+
+// Correlated survey submit.
+const result = await client.operations
+  .submitCsat({ score: 5 }, { surveyType: "bot", conversationId })
+  .settled();
+```
+
+Highlights:
+
+- `sendMessage(body, { secret? })` returns a handle. `settled()` resolves
+  with the message once it appears in `chat.messages`, and rejects when core
+  reports a send error first (rate limit, over-length body, session not
+  ready, dispatch failure) — detected on the `chat.error.seq` advance, so a
+  repeat of the identical error text still rejects. A secret send writes
+  no transcript row, so its handle never resolves. Pass `timeoutMs` or skip
+  `settled()` for secret sends.
+- `submitCapture(value).settled()` reports the server verdict for the
+  active capture field.
+- `checkEndChatEligibility()` resolves with the End Chat survey decision.
+- `markRead(cursor)` debounces 400 ms and keeps a monotonic watermark. Do
+  not reimplement read tracking.
+- `startNewConversation()` applies a 5 second cooldown and returns `false`
+  while cooling down.
+- `startFileUpload(file)` retains the `{ file, uploadId }` pair so
+  `retry()` replays exactly it.
+- `notifyComposerChanged()` is payload-free and suppressed in secret mode.
+  Composer text never crosses the frame boundary.
+- Chrome and settings helpers: `close`, `minimize`, `dismissError`,
+  `setLanguage`, `setTheme`, `emailTranscript`, and more. See the
+  `BridgeOperations` type for the full surface.
+
+Use `outage.connectivityLost` as the connectivity signal. Do not substitute
+`navigator.onLine`. It reports false positives on VPN and virtual-adapter
+transitions.
+
+## Observation
+
+`client.subscribeKey(key, callback)` fires only when one key's value
+changes. `client.select(selector, callback)` does the same for a derived
+projection. Both default to `Object.is` equality and accept a custom
+`equals`. Core reuses references for unchanged keys, so identity equality
+is sound for every key except `chat.messages`.
+
+```ts
+client.subscribeKey("chat.isGenerating", (generating) => {
+  toggleTypingIndicator(generating === true);
+});
+```
+
+## Derivation helpers
+
+The loaded module exports pure helpers mined from Ada's reference app:
+`messageKey`, `isHistoricalRow`, `findFirstUnread`, `selectUnread`,
+`groupMessages`, `filterDisplayable`, `resolveBotName`, `isAgentTyping`,
+and `isConnectivityLost`.
+
+```ts
+const { messageKey, filterDisplayable, groupMessages } = bridge;
+const rows = filterDisplayable(messages, state?.["chat.isConversationActive"] ?? false);
+const grouping = groupMessages(rows);
+```
+
+Use `messageKey` as your render key. Raw message ids change twice: a
+streaming bubble swaps to its final id, and an optimistic send swaps to its
+durable id. Keying on the raw id replays animations and breaks unread
+anchors.
+
+### Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `cdnBase` | `https://messaging-assets.ada.support` | Asset origin for `bridge.js`. Must be an `https` URL. Plain `http` works only for loopback hosts such as `localhost` during local development. Override only for staging validation. |
+| `pinBuildSha` | none | Full 40-character git SHA of a deployed CDN build. Loads that build's immutable copy instead of the current root asset. Not recommended for production. See [Pin the CDN build](#pin-the-cdn-build). |
+
+Errors: `loadMessagingBridge` rejects with a `MessagingBridgeLoadError`. Its
+`code` property identifies the failure:
+
+| Code | Meaning |
+| --- | --- |
+| `invalid_cdn_base` | The `cdnBase` option is not a valid `https` URL. |
+| `invalid_build_sha` | The `pinBuildSha` option is not a full 40-character hex git SHA. |
+| `unstamped_build_sha` | The `pinBuildSha` option is the unstamped placeholder from a repository build. |
+| `bridge_import_failed` | The asset failed to load (network, CSP, 404). |
+| `bridge_module_invalid` | The loaded module is not an Ada bridge build. |
+
+### Pin the CDN build
+
+The package exports `CDN_BUILD_SHA`. The value is the git commit SHA of the
+monorepo commit this npm version was published from. Ada deploys each
+commit's bridge runtime as an immutable SHA-rooted copy on the CDN. The
+value therefore names the CDN build associated with this npm version.
+
+Pass the SHA as the `pinBuildSha` loader option. The loader then skips the
+root `bridge.js` asset and imports that build's immutable copy,
+`<cdnBase>/<sha>/bridge/bridge.js`, directly:
+
+```ts
+import {
+  CDN_BUILD_SHA,
+  isCdnBuildShaStamped,
+  loadMessagingBridge,
+} from "@ada-cx/messaging-bridge";
+
+if (isCdnBuildShaStamped()) {
+  await loadMessagingBridge({ pinBuildSha: CDN_BUILD_SHA });
+}
+```
+
+**Pinning is not recommended for production.** A pinned runtime misses Ada's
+fixes and the loader-fence rollout. A pinned runtime can also predate later
+core or server contract changes and stop working. Use a pin only to debug an
+issue, to validate a staged build, or to reproduce a report against a known
+runtime.
+
+The option accepts any full 40-character hex git SHA of a deployed main
+build. The loader rejects any other value with the `invalid_build_sha` error
+code. Only published packages carry a real SHA. In the repository, and in a
+locally built copy, `CDN_BUILD_SHA` is a 40-zero placeholder and
+`isCdnBuildShaStamped()` returns `false`. The loader rejects the placeholder
+with the `unstamped_build_sha` error code.
+
+The npm publish and the CDN deploy of the same commit run in parallel. In
+the first minutes after a release, a pin can fail with
+`bridge_import_failed` until the deploy completes. If the deploy of that
+commit failed, the pinned build never exists. The unpinned default is
+unaffected in both cases.
+
+`pinBuildSha` composes with `cdnBase`. The pinned copy resolves under the
+asset host you pass.
+
+## React
+
+The `./react` entry provides a provider and hooks. They delegate to a
+`BridgeClient` instance. They contain no runtime logic of their own.
+
+The simplest path handles loading, the `app.initialize` handshake, and
+teardown for you:
+
+```tsx
+import { createBridgeProvider, useBridgeState } from "@ada-cx/messaging-bridge/react";
+
+const AdaBridgeProvider = createBridgeProvider();
+
+function Root() {
+  return (
+    <AdaBridgeProvider fallback={<Spinner />}>
+      <MyChatUi />
+    </AdaBridgeProvider>
+  );
+}
+
+function MyChatUi() {
+  const state = useBridgeState();
+  return <MessageList messages={state?.["chat.messages"] ?? []} />;
+}
+```
+
+The provider accepts two more props for load failures. `errorFallback`
+renders when the runtime fails to load. `onError` receives the
+`MessagingBridgeLoadError`. Without them, the provider logs the error and
+keeps rendering `fallback`.
+
+To own the lifecycle yourself, pass a client you created:
+
+```tsx
+import { BridgeProvider } from "@ada-cx/messaging-bridge/react";
+
+<BridgeProvider client={client}>
+  <MyChatUi />
+</BridgeProvider>
+```
+
+With an injected client, you send `app.initialize` and call `destroy()`
+yourself.
+
+Hooks: `useBridgeClient()`, `useBridgeState()`, and `useBridgeStateKey(key)`.
+`useBridgeStateKey` re-renders only when its key's value changes.
+`useBridgeState` re-renders on every state update. Reach the operations
+layer through `useBridgeClient().operations`.
+
+## Testing
+
+The `./testing` entry provides a scriptable in-memory client for unit tests.
+It performs no postMessage and no network access.
+
+```ts
+import { createMockBridgeClient } from "@ada-cx/messaging-bridge/testing";
+
+const mock = createMockBridgeClient();
+render(<BridgeProvider client={mock}><MyChatUi /></BridgeProvider>);
+
+mock.updateState({ "chat.isSending": true });
+expect(mock.sentEvents).toContainEqual({
+  event: "chat.message.send",
+  payload: expect.objectContaining({ body: "Hello" }),
+});
+```
+
+Mock helpers: `setState`, `updateState`, `sentEvents`, `clearSentEvents`,
+`subscriberCount`, and `destroyed`.
+
+The mock implements the full client surface, `operations` included. Every
+operation records its events in `sentEvents`. A correlated handle resolves
+when your test scripts the answering state change:
+
+```ts
+const handle = mock.operations.sendMessage("Hello");
+mock.updateState({
+  "chat.messages": [
+    { type: "text", id: "m1", sender: "user", timestamp: 1,
+      body: "Hello", clientKey: handle.tempMessageUuid },
+  ],
+});
+await handle.settled();
+```
+
+## Contract notes
+
+- `AppDisplayState` is the full state shape core publishes. `AppEvents` maps
+  each sendable event to its payload type.
+- `app.initialize` is mandatory. Send it within 15 seconds of frame load.
+- The runtime derives the core origin from `document.referrer`, or locks it
+  on the first valid state message. It rejects state from other origins.
+- In Ada's custom-app frame, the first `app.initialize` hands core a
+  `MessagePort`. All later state and events ride that port. The port is
+  pinned to your first document, so your app must not navigate or reload its
+  own frame. A navigation disconnects the bridge permanently.
+- The runtime detects the custom-app frame by the frame name core sets
+  (`ada-custom-app`), or by an opaque origin under older core builds. Do not
+  change `window.name` inside your app document.
+- The custom-app frame keeps your real origin, so your own cookies and
+  storage work inside it. Browsers partition third-party storage by the
+  embedding site. Cookies need `Partitioned; Secure; SameSite=None`.
+- The custom-app frame needs `document.referrer` to target the handshake.
+  Core provides the referrer by default. If a browser extension or policy
+  strips the Referer header, the handshake cannot send. The runtime logs an
+  error, and core falls back to Ada's default app after 15 seconds.
+
+## Support
+
+This package supports Ada's custom app program. Open issues through your Ada
+support contact.

package/dist/bridge-client.d.ts

@@ -0,0 +1,69 @@
+import type { BridgeOperations, ObserveOptions } from "./operations.js";
+import type { AppDisplayState, AppEvents } from "./types.js";
+type Subscriber = () => void;
+/**
+ * Framework-agnostic client connecting a display layer (Ada's app, or a
+ * customer-built custom app) to the core business-logic frame via typed
+ * postMessage. Create one with {@link createBridgeClient}.
+ */
+export interface BridgeClient {
+    /** Current {@link AppDisplayState} snapshot, or `null` before first update. */
+    getState(): AppDisplayState | null;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(callback: Subscriber): () => void;
+    /**
+     * Dispatch a typed event to core business logic. Send `app.initialize`
+     * within 15 seconds of the frame loading, or core unmounts the app frame.
+     */
+    sendEvent<K extends keyof AppEvents>(event: K, ...args: AppEvents[K] extends undefined ? [] : [payload: AppEvents[K]]): void;
+    /**
+     * Subscribe to ONE state key. The callback fires only when that key's
+     * value changes (`Object.is` by default) — unlike {@link subscribe}, which
+     * fires on every state update. State arrives over postMessage (structured
+     * clone), which would mint a fresh identity for every object-valued key
+     * on every update, so the client restores the PREVIOUS snapshot's
+     * reference for each key that is structurally unchanged before notifying.
+     * Identity equality is therefore sound for every key: an object key's
+     * identity changes exactly when its content does (for `chat.messages`,
+     * that is every streaming delta). Returns an unsubscribe function.
+     */
+    subscribeKey<K extends keyof AppDisplayState>(key: K, callback: (value: AppDisplayState[K] | undefined, previous: AppDisplayState[K] | undefined) => void, opts?: ObserveOptions<AppDisplayState[K] | undefined>): () => void;
+    /**
+     * Subscribe to a derived projection of the state. The callback fires only
+     * when the selected value changes (`Object.is` by default; pass a shallow
+     * or structural `equals` for object/array selectors). Returns an
+     * unsubscribe function.
+     */
+    select<T>(selector: (state: AppDisplayState | null) => T, callback: (value: T, previous: T | undefined) => void, opts?: ObserveOptions<T>): () => void;
+    /**
+     * Typed helpers over the event/state contract — sends with their guards,
+     * debounces, and state-edge correlation mined from Ada's reference app.
+     */
+    readonly operations: BridgeOperations;
+    /**
+     * Remove all listeners and postMessage handlers, and reject every
+     * in-flight `operations` `settled()` promise with a
+     * `BridgeClientDestroyedError` (detect it by `error.name`).
+     */
+    destroy(): void;
+}
+/**
+ * Create a {@link BridgeClient} bound to the parent core frame.
+ *
+ * Declaration only (D21 dependency inversion): the implementation lives in
+ * the private `packages/bridge-runtime` workspace and ships exclusively as
+ * the CDN asset `bridge.js` — obtain it through `loadMessagingBridge()`.
+ * The runtime compiles against this signature (`MessagingBridgeModule` is
+ * pinned both ways by bridge-runtime's `cdn-contract.ts`), so the published
+ * type can never drift from the CDN implementation.
+ *
+ * Security model: the core origin is derived from `document.referrer` when
+ * available, otherwise locked on the first valid `core.state.update` message
+ * (trust-on-first-use); state from any other origin is rejected, and events
+ * only ever target the locked origin — never `"*"`. In a custom-app document
+ * the first `app.initialize` transfers a MessagePort to core and all later
+ * traffic rides that port. A native-injected `window.__ADA_INITIAL_STATE__`
+ * snapshot seeds the state when its timestamp is within a 10-minute TTL.
+ */
+export declare function createBridgeClient(): BridgeClient;
+export {};

package/dist/bridge-react.d.ts

@@ -0,0 +1,63 @@
+import type { BridgeClient } from "./bridge-client.js";
+import type { MessagingBridgeModule } from "./loader.js";
+import type { AppDisplayState } from "./types.js";
+export declare const BridgeContext: import("react").Context<BridgeClient | null>;
+/**
+ * Provide a {@link BridgeClient} to the React tree.
+ *
+ * Pure delegation: the caller owns the client lifecycle. The provider does not
+ * create, initialize, or destroy the client — obtain one from the CDN module
+ * returned by `loadMessagingBridge()` (or use {@link createBridgeProvider} to
+ * have loading, `app.initialize`, and teardown handled for you).
+ */
+export declare function BridgeProvider({ client, children, }: {
+    client: BridgeClient;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The active {@link BridgeClient}. Throws outside a `BridgeProvider`. */
+export declare function useBridgeClient(): BridgeClient;
+/**
+ * The full display-state snapshot, or `null` before the first
+ * `core.state.update`. Re-renders on every state change.
+ */
+export declare function useBridgeState(): AppDisplayState | null;
+/**
+ * Returns a single typed value from the bridge state, or `null` when the state
+ * is not yet available. Provides full TypeScript autocomplete for the key names
+ * and returns the exact type declared in AppDisplayState.
+ *
+ * Re-renders only when THIS key's value changes (delegating to the client's
+ * `subscribeKey`), not on every state update the way `useBridgeState` does.
+ */
+export declare function useBridgeStateKey<K extends keyof AppDisplayState>(key: K): AppDisplayState[K] | null;
+export interface LoadedBridgeProviderProps {
+    children: React.ReactNode;
+    /** Rendered while the bridge runtime is loading. Defaults to nothing. */
+    fallback?: React.ReactNode;
+    /**
+     * Rendered when the runtime fails to load (network, CSP, 404). Defaults
+     * to `fallback`, so without it a failure looks like loading forever.
+     */
+    errorFallback?: React.ReactNode;
+    /**
+     * Called when the runtime fails to load, with the rejection — a
+     * {@link MessagingBridgeLoadError} for every loader-detected failure.
+     * When omitted, the failure is logged with `console.error`.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Build a provider component that loads the bridge runtime from the CDN,
+ * creates a client, sends the required `app.initialize` handshake, and
+ * destroys the client on unmount.
+ *
+ * The returned component renders `fallback` (default: nothing) until the
+ * runtime has loaded, then renders `children` inside a {@link BridgeProvider}.
+ * When the load fails it renders `errorFallback` (default: `fallback`) and
+ * reports the error through `onError` (default: `console.error`).
+ *
+ * @example
+ * const AdaBridgeProvider = createBridgeProvider();
+ * root.render(<AdaBridgeProvider><MyChatUi /></AdaBridgeProvider>);
+ */
+export declare function createBridgeProvider(load?: () => Promise<MessagingBridgeModule>): (props: LoadedBridgeProviderProps) => React.JSX.Element;

package/dist/build-info.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Git commit SHA of the monorepo commit this npm version was published from.
+ * The CDN pipeline deploys each main commit's bridge runtime under an
+ * immutable SHA root, so this value names the CDN build associated with this
+ * npm version. Pass it as the `pinBuildSha` loader option to load exactly
+ * that runtime build — not recommended for production (see the README).
+ *
+ * In the repository, and in any locally built copy, the value is the
+ * unstamped 40-zero placeholder ({@link isCdnBuildShaStamped} returns
+ * `false`); only published tarballs carry a real SHA.
+ */
+export declare const CDN_BUILD_SHA: string;
+/**
+ * Whether `sha` (default {@link CDN_BUILD_SHA}) is a stamped full git commit
+ * SHA rather than the unstamped repo placeholder.
+ */
+export declare function isCdnBuildShaStamped(sha?: string): boolean;

package/dist/derive.d.ts

@@ -0,0 +1,115 @@
+import type { AppDisplayState, Message } from "./types.js";
+/**
+ * Pure derivation helpers mined from Ada's reference app (`packages/app`).
+ * Each function is a faithful port of logic the app validates in production,
+ * so a custom app does not have to rediscover the edge cases the hard way.
+ * No DOM, no client: every helper is a pure function of state or messages.
+ *
+ * Declarations only (D21 dependency inversion): the implementations live in
+ * the private `packages/bridge-runtime` workspace and ship exclusively on
+ * the CDN runtime, typed on `MessagingBridgeModule`. The runtime compiles
+ * against these signatures (pinned both ways by bridge-runtime's
+ * `cdn-contract.ts`), so the published types cannot drift from the CDN
+ * implementation.
+ */
+/**
+ * Stable identity for a message across both id swaps. A live stream bubble
+ * (`id: "stream:<correlationId>"`) and its authoritative final (`id: <server
+ * _id>`) are the same logical reply, and an optimistic user message and its
+ * server echo are the same logical send — keying "new message arrived"
+ * effects (alert sound, scroll, unread) on raw `id` treats each swap as a
+ * fresh arrival. `streamId` is identical across the first swap, `clientKey`
+ * across the second, so prefer them in that order and fall back to `id`.
+ * Use this as your render key and as the anchor for unread boundaries.
+ */
+export declare function messageKey(message: {
+    id: string;
+    streamId?: string;
+    clientKey?: string;
+}): string;
+/**
+ * Whether a rendered row belongs to a conversation the chatter has left.
+ *
+ * The transcript is deliberately preserved across a conversation change, so a
+ * row from the previous conversation stays on screen but must not stay
+ * actionable: answering an old interactive row sends its target into the
+ * current conversation. The fail-safe directions are asymmetric on purpose:
+ * an unstamped message (predates stamping, or optimistic) is treated as
+ * current, while a stamped row with no active conversation pin is historical
+ * (a light reset clears the pin but keeps the transcript, and a stamped row
+ * cannot belong to "no conversation"). Consult this before enabling any
+ * interactive row (quick replies, options, retry).
+ */
+export declare function isHistoricalRow(messageConversationId: string | null | undefined, state: AppDisplayState | null | undefined): boolean;
+/**
+ * The first message a returning user has not read yet — the first bot/agent
+ * message whose durable `_id` cursor sorts (lexically) past the persisted
+ * read watermark (`chat.lastReadCursor`). Skips the user's own messages and
+ * presence markers, so the unread divider sits before incoming content.
+ * Returns `null` when the watermark is unset or everything has been read.
+ * Returns the message (not an id) so callers pick the right key: anchor
+ * unread boundaries on {@link messageKey} (stable across id swaps); use the
+ * raw `id` for DOM lookup.
+ */
+export declare function findFirstUnread(messages: Message[], lastReadCursor: string): Message | null;
+export interface UnreadSelection {
+    /**
+     * {@link messageKey} of the first unread message (the unread-divider
+     * anchor), or `null` when nothing is unread.
+     */
+    firstUnreadId: string | null;
+    /**
+     * Unread messages from the boundary on: `sender !== "user"`, excluding
+     * rows that render nothing (presence events without a dedicated row and
+     * videos with an unrenderable source).
+     */
+    count: number;
+}
+/**
+ * Unread boundary and count derived from the transcript and
+ * `chat.lastReadCursor`. Pass the output of {@link filterDisplayable} (plus
+ * your own `chat.answeredInteractiveIds` filtering) as `messages` so the
+ * boundary anchors on a row your transcript actually renders and the count
+ * matches visible rows — the reference app derives from its filtered list.
+ * Defaults to the raw `chat.messages`; rows that render nothing (non-row
+ * presence events, unrenderable videos) are excluded from the count either
+ * way. Pass `boundaryId` (a {@link messageKey}) to keep an already-shown
+ * divider anchored while newer messages arrive; when the anchor is no longer
+ * in the list (a baseline resync replaced the transcript) the boundary falls
+ * back to the persisted watermark — the same recovery the reference app
+ * performs.
+ */
+export declare function selectUnread(state: AppDisplayState | null, opts?: {
+    messages?: Message[];
+    boundaryId?: string;
+}): UnreadSelection;
+export interface MessageGroupingEntry {
+    /** Render a date divider above this message (first message of its day). */
+    showDivider: boolean;
+    /**
+     * This message continues the previous sender's run — hide the avatar and
+     * sender attribution and tighten the spacing.
+     */
+    isGroupedWithPrev: boolean;
+}
+/** Per-index date-divider and sender-run grouping decisions. */
+export declare function groupMessages(messages: Message[]): MessageGroupingEntry[];
+/**
+ * The messages a transcript should actually render, in order. Drops:
+ * non-rendering presence events (see the event allowlist), `video` rows with
+ * an unrenderable source, superseded CSAT rows (only the latest survey per
+ * `(conversationId, surveyType)` renders), unsubmitted/unscored CSAT rows of
+ * an inactive conversation, and the positional Sign-In "Never mind" pair once
+ * it is stale. Pass `chat.isConversationActive` (default it to `false` when
+ * absent) as `isConversationActive`. Apply your own
+ * `chat.answeredInteractiveIds` filtering on quick-reply rows afterwards,
+ * then feed the result to {@link selectUnread} via its `messages` option so
+ * the unread boundary and count describe the rows you render.
+ */
+export declare function filterDisplayable(messages: Message[], isConversationActive: boolean): Message[];
+/** Display name for the bot: `config.botName`, else `config.handle`, else "Ada". */
+export declare function resolveBotName(state: AppDisplayState | null): string;
+/** Someone is composing a reply (core's typing verdict + active agent). */
+export declare function isAgentTyping(state: AppDisplayState | null): boolean;
+/** Core's connectivity verdict — never substitute `navigator.onLine`. */
+export declare function isConnectivityLost(state: AppDisplayState | null): boolean;