UTD Chat Kit

Top-level entry to the chat kit, declared as an abstract final class exposing only static members. UTDChat.init mints, connects and starts sync from a UTDChatConfig and returns a live UTDChatClient the host owns (and must dispose). UTDChat.scope wraps any subtree so the built-in screens can read the client/theme/strings, and the screen-builder helpers build the kit's default screens already wrapped in that scope. Has no public constructor (cannot be instantiated).

Creates the session: constructs a UTDChatClient from the config, mints the per-user bearer and signal token, connects the signalling WebSocket and starts the local-first sync engine. The host owns the returned client and is responsible for calling UTDChatClient.dispose.

Returns: Future<UTDChatClient> — A connected, sync-started chat session the caller owns and must dispose.

Wraps child in a UTDChatScope so the default widgets can resolve the session, theme and strings from BuildContext. The theme and strings are taken from client.config. Used internally by all the screen-builder helpers and exposed for custom screens that need access to the scope.

Returns: Widget — A UTDChatScope wrapping child with the client and its configured theme/strings.

Builds the conversation-list screen (UTDConversationsListScreen) already wrapped in its scope. Drop the returned widget into a route as the chat home screen.

Returns: Widget — The scoped conversations-list screen.

Builds a single 1:1 chat thread screen (UTDChatScreen) wrapped in its scope for the given conversation and peer.

Returns: Widget — The scoped 1:1 chat screen.

Builds a group chat screen (UTDChatScreen with isGroup: true) wrapped in its scope. Peers' bubbles carry sender names and the header opens the group-info screen.

Returns: Widget — The scoped group chat screen.

Builds the create-group screen (UTDCreateGroupScreen) wrapped in its scope, optionally pre-selecting initial members.

Returns: Widget — The scoped create-group screen.

Builds the group-info screen (UTDGroupInfoScreen) — member list plus management — wrapped in its scope.

Returns: Widget — The scoped group-info screen.

InheritedWidget that carries the chat session's client, theme and strings down to the kit's built-in default widgets via the element tree. Routes pushed from the kit (e.g. the chat thread) re-wrap their subtree in a fresh UTDChatScope captured from the originating context so new routes can still read the session. Produced by UTDChat.scope and the screen-builder helpers; descendants read it with UTDChatScope.of / maybeOf.

The live chat session carried by this UTDChatScope.

Returns: UTDChatClient — The chat session.

The visual theme for the default UI carried by this scope.

Returns: UTDChatTheme — The theme.

The UI strings carried by this scope.

Returns: UTDChatStrings — The strings.

Resolves the nearest UTDChatScope from context, asserting that one exists. Used by the kit's default widgets to read the session/theme/strings.

Returns: UTDChatScope — The nearest enclosing scope (asserts non-null in debug).

Resolves the nearest UTDChatScope from context via dependOnInheritedWidgetOfExactType, returning null when none is present.

Returns: UTDChatScope? — The nearest enclosing scope, or null if there is none.

Notifies dependents when the client, theme or strings reference changes between the old and new scope.

Returns: bool — True if client, theme or strings differs from oldWidget.

The chat kit's session facade. Owns the REST client, the signalling WebSocket, the local Drift store and the sync engine, wiring them together: mint the per-user bearer, mint signal credentials, connect the WebSocket and start the sync engine. Controllers and UI read everything through database/sync/outbox and never touch the transport directly.

The immutable kit configuration this client was constructed with (credentials, identity, base URLs, push, theme/strings).

The local Drift store that is the source of truth; controllers watch this for conversations and messages.

Returns: ChatDatabase — The local-first store backing all reads.

The sync coordinator that handles history pull (REST), live pushes (signalling WebSocket) and reconnect, draining everything into the local store.

Returns: SyncEngine — The sync engine instance.

The optimistic-send pipeline that queues and sends outgoing messages, surviving offline resends.

Returns: Outbox — The optimistic outbox instance.

The realtime signalling client, exposing connection state and force-exit handling.

Returns: UTDSignalClient — The underlying signalling WebSocket client.

The live signalling connection state as a ValueListenable, so UI can react to connect/reconnect/force-exit transitions.

Returns: ValueListenable<UTDConnectionState> — Listenable connection lifecycle state.

The high-level engine REST API wrapper used for session minting and privileged calls.

Returns: UTDApi — The REST API facade.

The push deep-link router (process-wide singleton). Register a navigation handler via its setHandler so a notification tap opens the chat screen; deep-links are queued until the client is connected.

Returns: UTDNotificationRouter — The shared notification router instance.

Connect the signalling WebSocket (which mints + applies the per-user bearer) and start the sync engine. Idempotent. Marks the notification router ready so queued push deep-links flow, then best-effort registers this device's push token when config.push.enabled. Throws on a hard auth/connect failure.

Returns: Future<void> — Completes once connected and sync has started.

Tear down the session: mark the notification router not-ready, stop push, dispose the sync engine, disconnect the signalling socket, close the REST client and close the local database.

Returns: Future<void> — Completes once all resources are released.

Routes push deep-links to the host's navigation, guarded behind chat-client readiness. A process-wide singleton accessed via UTDNotificationRouter.instance. A deep-link is delivered only once BOTH a handler is set AND the router is ready; otherwise the latest deep-link is queued (most-recent wins). Use no public constructor; obtain via instance.

The process-wide singleton notification router instance.

Whether the chat client is connected/authenticated and able to open a conversation.

Returns: bool — True when ready to navigate to a conversation.

Register the host's navigation callback that opens the chat screen for a deep-link. Flushes any pending deep-link if the router is already ready. Pass null to clear.

Mark the chat client ready (connected) and flush any queued deep-link. Called internally by UTDChatClient.connect.

Mark the chat client not ready (e.g. on dispose/logout); subsequent deep-links queue until the next markReady. Called internally by UTDChatClient.dispose.

Route a deep-link: deliver it immediately if ready and a handler is set, otherwise queue it (overwriting any previously queued link).

Parse a chat deep-link from an FCM data map, or return null if it is not a {type:'message', conversation_id, ...} payload.

Returns: UTDChatDeepLink? — The parsed deep-link, or null when the payload is not a chat message.

An immutable deep-link target parsed from a {type:'message', ...} push payload, identifying the conversation (and optionally the message/sender) to open.

Parse a deep-link from an FCM data map. Returns null if it is not a chat message payload or carries no conversation_id.

Returns: UTDChatDeepLink? — The parsed deep-link, or null when not a chat message payload.

A host-supplied callback that navigates to the chat screen for a deep-link.

Signalling connection lifecycle exposed by connectionState. Values: disconnected (initial / after normal leave), connecting (attempt in flight), connected (live), reconnecting (dropped, auto-reconnecting), forceExit (server removed the session or reconnection failed — the host should leave/re-authenticate).

Everything the chat kit needs to authenticate and render: publishable credentials (appId/appKey), the caller identity (userId/userName), optional engine/mint base URLs and device id override, and the push/theme/strings customization hooks. Immutable and Equatable.

Publishable project id (`X-App-Id`).

Publishable project key (`X-App-Key`), sent only to the mint host.

The caller's stable identity (engine `identity`).

The caller's display name.

Engine host for privileged REST (Bearer); null means the kit's built-in origin.

Mint host (`X-App-Key`); null means the kit's built-in origin.

Explicit device id override; null falls back to the persisted per-install id.

Background message push (FCM) configuration.

Visual theme for the default UI.

Resolved UI strings: the supplied custom instance, or the English defaults (UTDChatStrings.en()) when none was provided.

Returns: UTDChatStrings — The custom strings or the English fallback.

Configuration for background message push (FCM) + deep-linking. Push is opt-out (enabled defaults to true), and is also gated server-side until the engine's FCM/APNs env is provisioned. Immutable and Equatable.

Whether the kit wires up FCM at all. Default true.

Whether PushBridge requests notification permission on connect. Default true.

Optional fixed title for the foreground banner; null uses the sender's name from the payload.

Color tokens for the chat kit's default UI (conversation list, chat thread, message bubbles, composer). Every field has a light, WhatsApp-flavoured default, so const UTDChatTheme() is a complete usable theme; override individual tokens via copyWith. Immutable.

A ready-made light theme, identical to the default constructor.

A ready-made dark theme with dark backgrounds, surfaces, bubbles, and divider.

Returns a copy of this theme with the given color tokens overridden; unspecified tokens keep their current values.

Returns: UTDChatTheme — A new theme with the requested overrides applied.

User-facing strings for the chat kit's default UI (conversation list, chat thread, composer, groups, presence, typing, media). Pass a custom instance (or a factory) to UTDChatConfig.strings to translate/relabel. The const constructor requires every label; factories provide complete sets.

Factory returning the complete English default string set.

Returns: UTDChatStrings — All labels populated with English defaults.

Factory returning the complete Arabic default string set.

Returns: UTDChatStrings — All labels populated with Arabic defaults.

Builds the group-typing line for one named member by substituting `{name}` in typingNamed.

Returns: String — The localized single-member typing line.

Builds the group-typing line for several members by substituting `{count}` in typingMany.

Returns: String — The localized multi-member typing line.

An immutable single message projected from the local store for rendering in a chat thread. Carries the local row id, the optimistic client id and the server message id, sender info, content/type, parsed group-system-event and media-attachment payloads, delivery status, timestamp, and an isMine flag.

Factory that builds a UTDChatMessage from a Drift Message row and the local self identity, parsing the system event for system_message rows and the media attachment for media rows, and deriving isMine by comparing the sender against selfIdentity.

True when status is recalled (the message was unsent by its sender).

Returns: bool — Whether the message has been recalled.

True when status is failed (the optimistic send exhausted its retries or hit a hard error).

Returns: bool — Whether the send failed.

True when status is sending (queued in the outbox, not yet acked).

Returns: bool — Whether the message is still being sent.

True when type is system_message (a centered group-lifecycle note).

Returns: bool — Whether this is a system message.

True when type is image, file, audio, or video.

Returns: bool — Whether this is a media message.

An immutable conversation list item projected from the local store for list rendering. Carries the conversation id and type (peer/group), display title, 1:1 peer identity, avatar, last-message preview and timestamp, unread count, and mute flag.

True when type equals 'group' (UTDConversationSummary).

Returns: bool — Whether this conversation is a group.

A media attachment projected from a message's metadata payload. The url is the R2 object_url once uploaded, or a local file path while a send is still optimistic, plus optional descriptors (name, size, mime, dimensions, duration).

True when url points at a local file (starts with file:// or /), i.e. an optimistic, not-yet-uploaded attachment.

Returns: bool — Whether the attachment url is a local path.

Parse an attachment from an already-decoded message metadata map; returns null when there is no usable url.

Returns: UTDMediaAttachment? — The parsed attachment, or null when no url is present.

Parse an attachment from a raw metadata JSON string (the Drift metadata column); returns null when absent or malformed.

Returns: UTDMediaAttachment? — The parsed attachment, or null on absent/malformed input.

The delivery lifecycle of a message as stored locally. Values: sending (local-only, queued in the outbox, not yet acked), sent (acked, server message_id stamped), delivered (peer device received it; reserved, no engine webhook yet), read (peer read past this message via message.read_receipt), failed (optimistic send exhausted retries or hard error; still in the outbox for manual resend), recalled (content cleared by its sender). The status enum is unchanged by media/typing/group milestones.

Re-export alias for UTDMessageStatus so callers can pattern-match message status without importing the store layer.

A ChangeNotifier that drives one conversation thread. Watches the local-first Drift message stream, eagerly pulls the newest page and marks the thread read on open, sends via the optimistic outbox, recalls, debounces outbound typing and tracks inbound typing, and pages older history. Surfaces messages (oldest→newest), loadingOlder/reachedStart state, and a typingIdentities notifier.

The current message list, oldest→newest (the natural top-to-bottom render order), updated as the Drift stream emits.

Returns: List<UTDChatMessage> — Messages in render order.

True when this thread is a group (no single peer, i.e. peerIdentity is null).

Returns: bool — Whether the thread is a group.

Whether an older-history page is currently being fetched.

Returns: bool — True while paging older history.

Whether the start of history has been reached (no more older pages remain).

Returns: bool — True when there is no older history left.

A ValueNotifier of the set of OTHER identities currently typing in this conversation; self is never included and entries auto-expire after the typing-expiry window.

Optimistically send a text message. Trims the body and ignores empties, ends the local typing burst, and enqueues via the outbox so the bubble appears immediately with status sending and flips to sent on the engine ack.

Returns: Future<void> — Completes once the message is enqueued.

Recall (unsend) one of your own sent messages: optimistically clears it locally then asks the engine; on failure the next history pull restores truth. No-op unless the message is mine and has a server message id.

Returns: Future<void> — Completes once the recall is attempted.

Retry failed messages by re-arming their backoff and draining the outbox (delegates to the outbox resendAll).

Returns: Future<void> — Completes once the outbox has been re-drained.

Mark this conversation read: clears the local unread count and notifies the engine; offline read clears persist locally and re-assert on the next connected send/read.

Returns: Future<void> — Completes once read is recorded locally and attempted on the engine.

Page older history before the oldest local message; updates loadingOlder/reachedStart. No-op when already loading or the start has been reached.

Returns: Future<void> — Completes once the older page has been fetched (or no-op).

Report a composer change: sends a single typing.start on the first change of a burst and re-arms the idle timer that auto-sends typing.stop. No-op while disconnected; empty/whitespace input clears typing.

Stop the local typing burst immediately (idempotent). Called on send, on a cleared composer, and on dispose.

A ChangeNotifier that watches the conversation list from the local Drift store (most-recent-first) and exposes it as a local-first list that renders instantly and updates as the sync engine refreshes the cache.

The current conversation list, most-recent-first.

Returns: List<UTDConversationSummary> — Conversation summaries in display order.

Total unread message count summed across all conversations.

Returns: int — Aggregate unread count.

Force a refresh of the conversation list from the engine (the live socket already keeps it current; this is for pull-to-refresh).

Returns: Future<void> — Completes once the conversation list has been pulled.

The optimistic-send pipeline (advanced/headless use). enqueueText/enqueueMedia perform a two-step write (a local message row plus a sync_outbox row); drain flushes due rows through the signalling client, stamping the server message_id and flipping status to sent on the ack then deleting the outbox row. Failed attempts back off exponentially with jitter and are retried; after maxAttempts the message is left failed for manual resend.

Maximum number of send attempts before a queued message is left failed (default 8).

Optimistically enqueue a text send and return the client_msg_id (also the dedup key). The local message appears in the conversation stream immediately with status sending; pass toIdentity for a 1:1 peer send or leave it null for a group send routed by conversation_id.

Returns: Future<String> — The client_msg_id of the optimistic local row.

Optimistically enqueue a media send (image/file/audio/video) after the R2 upload completed. metadata carries the url (object_url) plus optional descriptors; the local row appears immediately as sending with the metadata so the bubble renders right away, and the engine ack stamps the message_id like the text path.

Returns: Future<String> — The client_msg_id of the optimistic local row.

Flush every due outbox row once through the signalling client. Safe to call repeatedly or concurrently; re-entrant calls are coalesced.

Returns: Future<void> — Completes once all due rows have been attempted.

Retry every queued row immediately (used on reconnect): clears the backoff gate, resets failed messages back to sending, then drains.

Returns: Future<void> — Completes once all queued rows have been re-attempted.

A member's role within a group conversation, mirroring the engine's conversation_members.role. Values: owner (created the group or was promoted on owner-leave handoff; can delete, add/remove members, rename), admin (can add/remove members and rename, but not delete), member (regular participant; can only leave). Unknown/absent wire values degrade to member so the local gate never over-grants.

Parses a wire role string into a UTDGroupRole; unknown or null values degrade to the least-privileged member role.

Returns: UTDGroupRole — The matching role, or UTDGroupRole.member for unknown/null input.

The wire string for this role (the enum value's name).

Returns: String — 'owner', 'admin', or 'member'.

Whether this role can add/remove members and rename the group (owner or admin).

Returns: bool — True for owner and admin.

Whether this role can update the group's name/avatar (owner or admin; equal to canManageMembers).

Returns: bool — True for owner and admin.

Whether this role can delete the whole group (owner only).

Returns: bool — True only for owner.

An immutable projection of a group member from the local store, used by the group-info UI. Carries the member's identity, role, optional nickname and join time.

The member's stable identity.

The member's role within the group (owner/admin/member).

A per-conversation display nickname, when set; null otherwise.

When the member joined the group, when known.

Display label for the member: the nickname when set, otherwise the identity.

Returns: String — The nickname, or the identity as a fallback.

Builds a UTDGroupMember from a Drift ConversationMember store row, parsing the wire role and converting joinedAt from epoch milliseconds.

Returns: UTDGroupMember — The projected member.

A ChangeNotifier that drives one group's membership and management actions for the group-info UI. Watches the local member cache, exposes the live member list and the local user's role, and performs server-authoritative mutations; each mutation throws a UTDStreamException on engine rejection (e.g. ack code 3 'Only owner/admin …'). Live conversation.* pushes keep the cache and myRole current. Use the static create() for the create-group flow where no conversation exists yet.

The id of the group conversation this controller manages.

The current member list (owner/admin/member, in join order), kept live from the local member cache.

Returns: List<UTDGroupMember> — The cached group members.

The local user's role in this group; defaults to UTDGroupRole.member until the cache resolves so the UI gate never over-grants.

Returns: UTDGroupRole — The local user's role, or member when unknown.

Whether the local user is a member and may add/remove members and rename the group.

Returns: bool — True when the user is an owner or admin member.

Whether the local user is a member and may delete the whole group (owner only).

Returns: bool — True when the user is the owner.

Adds members (invites identities) to the group, then refreshes the authoritative member set. Throws UTDStreamException if the engine rejects (e.g. a concurrent demotion stripped manage rights — ack code 3).

Returns: Future<void> — Completes once the add is acked and the member cache is refreshed.

Removes a member from the group, then refreshes the member set. Throws on rejection (caller not owner/admin, or the target is the owner).

Returns: Future<void> — Completes once the removal is acked and the cache is refreshed.

Leaves this group. The engine excludes the leaver from the member_left push, so the local thread is evicted here on a successful ack.

Returns: Future<void> — Completes once the leave is acked and the conversation is evicted locally.

Renames and/or re-avatars the group. Throws on rejection when the caller lacks update rights.

Returns: Future<void> — Completes once the update is acked.

Mutes or unmutes the group for the local user and updates the local conversation cache.

Returns: Future<void> — Completes once the mute state is applied.

Deletes the whole group (owner only). Throws on rejection. The engine excludes the deleter from the conversation.deleted push, so the local thread is evicted here on a successful ack.

Returns: Future<void> — Completes once the delete is acked and the conversation is evicted locally.

Creates a new group and returns its conversation id. Static because there is no conversation to bind to yet; the resulting conversation.group_created push (handled by the sync engine) materializes the local thread and members.

Returns: Future<String> — The new group's conversation id.

Cancels the member-cache subscription and disposes the ChangeNotifier.

A create-group screen with a name field and a comma-separated member-id entry. On submit it creates the group via UTDGroupsController.create; the resulting conversation.group_created push materializes the thread, and when openOnCreate is set the screen replaces itself with the new group's UTDChatScreen. The kit owns no contact directory, so hosts with one should pass initialMembers or wrap their own picker around the controller's create.

Presents the create-group screen as a modal bottom sheet. Returns the new conversation id, or null if cancelled.

Returns: Future<String?> — The new conversation id, or null if the sheet was dismissed.

A group-info screen showing the member list with roles plus management actions: add/remove members, rename, leave, and (owner only) delete. Management controls are gated on the local user's role via a UTDGroupsController, but the server is authoritative — a racing rejection (ack code 3) is caught and surfaced as a snackbar while the live member-list refresh re-asserts the truth.

A ChangeNotifier that tracks online/offline presence of peers the UI cares about. It subscribes over the signalling socket (`presence.subscribe`, which also returns current statuses), folds live `presence.changed` pushes into a local cache, derives a best-effort `last_seen` on each online→offline transition, re-queries on reconnect, and expires snapshots not refreshed within `staleAfter` (degrading them to `UTDPresenceStatus.unknown`).

How long a presence snapshot stays trusted without a refresh before its status degrades to UTDPresenceStatus.unknown.

Returns the current presence snapshot for the given identity, or null if it is not tracked.

Returns: UTDPresenceSnapshot? — The cached snapshot, or null if the identity is not tracked.

Convenience accessor for an identity's status, defaulting to UTDPresenceStatus.unknown when it is not tracked.

Returns: UTDPresenceStatus — The cached status, or UTDPresenceStatus.unknown if not tracked.

Whether the given identity is currently known to be online.

Returns: bool — True only when the cached status is UTDPresenceStatus.online.

Subscribes to and immediately fetches presence for the given identities, folding the returned statuses into the cache. No-ops on an empty list and ignores blank identities; errors are swallowed (best-effort) and a later reconnect re-queries.

Returns: Future<void> — Completes after the subscribe request resolves (or is swallowed when disconnected/rate-limited).

Stops watching the given identities: removes them from the watched set and the cache and best-effort unsubscribes over the socket, then notifies listeners.

Returns: Future<void> — Completes after the unsubscribe request resolves or is swallowed.

Cancels the sweep timer and presence subscription, detaches the connection-state listener, and disposes the controller.

Online/offline status of an identity on the signalling plane. Values: online, offline, unknown. Exposes the static helper `UTDPresenceStatus.fromWire(String? s)` which maps the wire strings 'online'/'offline' to the matching value and anything else to unknown.

A point-in-time presence snapshot for one identity as cached by a kit. The engine's presence plane is binary and timestamp-less, so lastSeen is a best-effort local marker (the local clock at the observed online→offline transition) and updatedAt is when the snapshot was last touched (used to expire stale entries).

Whether this snapshot's status is UTDPresenceStatus.online.

Returns a copy of this snapshot with the given fields replaced (identity is preserved).

Returns: UTDPresenceSnapshot — A new snapshot with the overrides applied.

A presence transition pushed over the WebSocket (`presence.changed`), carrying the identity and its new status. Constructed from wire data via the `UTDPresenceChange.fromData(Map<String, dynamic> d)` factory.

An ephemeral typing transition pushed over the WebSocket (`typing`). The engine relays start/stop to other conversation members and never persists or bills it. `typing` is true on typing.start and false on typing.stop. Constructed from wire data via the `UTDTypingEvent.fromData(Map<String, dynamic> d)` factory.

A small colored dot indicating an identity's presence: green when online, the theme's muted color otherwise, and nothing at all when status is unknown. Intended to overlay an avatar or sit beside a name.

Broadcast stream on the signalling client of presence transitions (`presence.changed`) for subscribed identities. The UTDPresenceController listens to this to update its cache.

Signalling-client method to subscribe to presence for 1–100 identities and return their current statuses; subscriptions are restored automatically after a reconnect.

Returns: Future<Map<String, UTDPresenceStatus>> — Current status per identity at subscribe time.

Signalling-client method to stop receiving presence for the given identities.

Returns: Future<void> — Completes when the unsubscribe request resolves.

Signalling-client method to query current presence for the given identities without subscribing. Used by the presence controller to reconcile after reconnect.

Returns: Future<Map<String, UTDPresenceStatus>> — Current status per identity.

Broadcast stream on the signalling client of ephemeral typing transitions (`typing`) from other conversation members. The UTDChatController listens to this to maintain its typingIdentities set.

Signalling-client method to signal that you started typing in a conversation; relayed to the other members.

Returns: Future<void> — Completes when the typing.start request resolves.

Signalling-client method to signal that you stopped typing in a conversation.

Returns: Future<void> — Completes when the typing.stop request resolves.

On UTDChatController: a ValueNotifier holding the set of OTHER identities currently typing in this conversation. Self is never included; entries auto-expire after the typing-expiry window. Drives the chat header/footer typing line.

On UTDChatController: report that the local user changed the composer input. Sends a single typing.start on the first change of a burst and re-arms a ~4s idle timer that auto-sends typing.stop. A no-op while disconnected; an empty/whitespace body stops immediately.

On UTDChatController: stop the local typing burst immediately (idempotent), sending typing.stop. Called on send, on a cleared composer, and on dispose.

Top-level FCM background message handler that MUST be registered by the host before runApp (annotated @pragma('vm:entry-point')). FCM invokes it in a separate isolate when a data message arrives while the app is backgrounded/terminated. It parses a chat deep-link from the message data (returning early if it isn't a chat-message payload), initializes Firebase + flutter_local_notifications in the isolate, and renders a local notification (title = sender name or 'New message', body = the payload 'preview') so the user can tap it; the tap is later routed via FirebaseMessaging.onMessageOpenedApp / getInitialMessage.

Returns: Future<void> — Completes once the local notification has been shown (or immediately if the payload is not a chat message).

Bridges Firebase Cloud Messaging to the chat kit: registers the device push token with the engine, keeps it fresh on refresh, renders foreground/background banners, and routes notification taps to a deep-link. Driven by UTDChatClient. It never throws into the connect path — a Firebase/permission failure degrades gracefully and is reported via debugPrint.

Initializes FCM and wires the receive surfaces: inits local notifications + the Android channel, optionally requests notification permission (iOS / Android 13+), resolves and registers the FCM token (resolving the APNs token first on iOS), then subscribes to token refresh and the three receive surfaces (foreground, opened-from-background, cold start). Idempotent and a no-op when push is disabled; never throws.

Returns: Future<void> — Completes once initialization and registration have been attempted.

Tears down the bridge on dispose/logout: cancels the token-refresh and message listeners and unregisters the push token with the engine so a signed-out device stops receiving pushes. Never throws.

Returns: Future<void> — Completes once listeners are cancelled and the token unregister has been attempted.

Configuration for background message push (FCM) + deep-linking. Push is opt-out (enabled defaults to true). Extends Equatable.

The push platform the engine keys a token by, mirroring the engine contract for POST /api/v1/devices/push-token. Values: ios ('ios'), android ('android'), web ('web'). Each value carries a `wire` String (the exact value the engine expects in the platform field). Re-exported from utd_signaling.

Registers this device's push token with the engine (POST /api/v1/devices/push-token, Bearer). The engine binds the token to the bearer's identity, so a session must already be minted. Pass fcmToken (Android/web/data) and/or voipToken (iOS VoIP) as available. Returns true when the engine confirms ({registered:true}). Defined on UTDApi (from utd_signaling) and used by PushBridge.

Returns: Future<bool> — True when the engine confirms registration.

Unregisters this device's push token (DELETE /api/v1/devices/push-token, Bearer), called on logout/dispose so a signed-out device stops receiving pushes for this identity. Returns true when the engine confirms ({removed:true}). Defined on UTDApi (from utd_signaling) and used by PushBridge.stop().

Returns: Future<bool> — True when the engine confirms removal.

An immutable deep-link target parsed from a {type:'message', ...} push payload, identifying the conversation (and optionally the message/sender) to open.

Static factory that parses a deep-link from an FCM data map. Returns null if it is not a chat message payload (type != 'message') or carries no non-empty conversation_id.

Returns: UTDChatDeepLink? — The parsed deep-link, or null if the payload is not a chat message.

A host-supplied callback that navigates to the chat screen for a deep-link. Signature: void Function(UTDChatDeepLink link).

Process-wide router that delivers push deep-links to the host's navigation, guarded behind chat-client readiness. dispatch QUEUES the latest deep-link and only delivers it once both a handler is set AND the router is ready; the most-recent deep-link wins. Accessed via the static `instance` singleton (no public constructor).

The process-wide UTDNotificationRouter singleton.

Static helper that parses a chat deep-link from an FCM data map, or returns null if it isn't a {type:'message', conversation_id, ...} payload. Tolerates the Map<String, dynamic> shape FCM delivers.

Returns: UTDChatDeepLink? — The parsed deep-link, or null.

Whether the chat client is connected/authenticated and able to open a conversation. On UTDNotificationRouter.

Registers the host's navigation callback (or clears it with null). Flushes any pending deep-link if the router is already marked ready. On UTDNotificationRouter.

Marks the chat client ready (connected) and flushes any queued deep-link. On UTDNotificationRouter.

Marks the chat client not ready (e.g. on dispose/logout); subsequent deep-links queue until the next markReady. On UTDNotificationRouter.

Routes a deep-link: delivers it immediately if the router is ready and a handler is set, otherwise queues it (most-recent wins). On UTDNotificationRouter.

Process-wide static tracker of the conversation the user is currently viewing, used so the push layer can suppress the foreground banner for a message that arrives in the conversation the user is already reading. A single process-wide value (abstract final, all-static). The chat thread sets it while on screen and clears it on dispose/background.

The conversation id currently on screen, or null if none. Static, on UTDActiveConversation.

True when the given id is the conversation currently being viewed. Static, on UTDActiveConversation.

Returns: bool — True if id matches the active conversation.

Marks the given conversation id as the one now on screen. Static, on UTDActiveConversation.

Clears the given conversation id as active, but only if it is still the active one (so a fast A→B→dispose-A ordering doesn't clobber B). Static, on UTDActiveConversation.

Immutable color tokens for the kit's built-in default UI (conversation list, chat thread, message bubbles, composer). Every field has a light, WhatsApp-flavoured default, so const UTDChatTheme() is a complete, usable theme. Notable fields: background, surface, onSurface, onSurfaceMuted, primary, onPrimary, danger, bubbleMine, bubbleMineText, bubbleTheirs, bubbleTheirsText, tick, tickRead, divider, composerFill. Provides ready-made `light` and `dark` static themes and copyWith for rebranding.

A ready-made light UTDChatTheme (identical to the default constructor). Static const on UTDChatTheme.

A ready-made dark UTDChatTheme with dark background/surface, white foregrounds and a dark peer bubble. Static const on UTDChatTheme.

Returns a copy of this UTDChatTheme with the given color tokens overridden, leaving the rest unchanged — used to rebrand without replacing whole widgets.

Returns: UTDChatTheme — A new theme with the supplied overrides applied.

Immutable set of user-facing strings for the kit's built-in default UI. Notable fields include conversationsTitle, noConversations, emptyChatHint, messageHint, recalledPlaceholder, recall, retry, cancel, sendFailed, reconnecting, offline, online, lastSeen, group labels (newGroup, groupName, groupInfo, membersLabel, addMembers, removeMember, leaveGroup, deleteGroup, renameGroup, create, save, roleOwner, roleAdmin, actionFailed), typing indicators (typing, typingNamed with {name}, typingMany with {count}), and media labels (attach, attachPhoto, attachCamera, attachVideo, attachFile, mediaPhoto, mediaVideo, mediaAudio, uploading, uploadFailed, uploadsUnavailable). All fields are required in the const constructor; use the UTDChatStrings.en()/ar() factories for defaults. Pass an instance to UTDChatConfig.strings to translate/relabel.

Factory returning the full set of English default strings (e.g. 'Chats', 'Message', 'typing…', 'Upload failed').

Returns: UTDChatStrings — English-localized strings.

Factory returning the full set of Arabic default strings (e.g. 'المحادثات', 'رسالة', 'يكتب…', 'فشل الرفع').

Returns: UTDChatStrings — Arabic-localized strings.

Returns the group-typing line for one named member, substituting {name} in typingNamed.

Returns: String — The formatted typing line.

Returns the group-typing line for count members, substituting {count} in typingMany.

Returns: String — The formatted typing line.

InheritedWidget that carries the chat session's client, theme and strings down to the kit's built-in default widgets via the element tree. Routes pushed from the kit re-wrap their subtree in a fresh UTDChatScope so a new route can still read the client/theme/strings.

Returns the nearest UTDChatScope from the context, asserting one exists. Static on UTDChatScope. (See also maybeOf for a nullable lookup.)

Returns: UTDChatScope — The enclosing scope (asserts non-null).