Optimistic Chat Message Rendering Design

Goal

Render a submitted user message in the active chat during the same client interaction, before /api/chat returns response headers or model output. Keep that user message visible when generation fails or is stopped, and reconcile the optimistic state with the authoritative conversation and message IDs returned by the server without duplicates.

Scope

The change is limited to the existing corp-ui chat hook and composer boundary. The persistent /api/chat contract, database schema, Gateway, FinOps, authentication, and model protocol remain unchanged.

Optimistic rendering covers both text and already-uploaded attachment metadata. Attachment upload itself remains a prerequisite for submission.

Client Data Flow

1. ChatComposer passes the trimmed text and the complete metadata for every uploaded attachment to useChat.sendMessage.
2. sendMessage validates the turn, captures the current authoritative conversation ID when one exists, and creates stable client-only IDs for the optimistic conversation and user message.
3. Before starting authFetch, the hook commits the user message to React state. For a new chat it also creates and activates an optimistic conversation. For an existing chat it appends the message and moves that conversation to the top without changing its authoritative ID.
4. The request body remains unchanged. It contains attachment IDs only and omits conversationId for a new optimistic chat; client-only IDs never cross the API boundary.
5. When /api/chat returns X-Conversation-Id and X-User-Message-Id, the hook atomically replaces the client-only IDs with server IDs. It updates the active conversation ID only when the optimistic conversation is still active. Existing messages and attachment metadata are retained.
6. The assistant message is appended after response headers are available. Stream chunks then update only that assistant message as they do today.

React state updates remain immutable and use stable message IDs, consistent with React 19 list reconciliation guidance. Existing synchronous refs are updated in the same commit helper so async response callbacks operate on the latest optimistic state rather than a stale render snapshot.

Errors, Cancellation, and Retry

• A non-2xx response carrying the server conversation/message headers first reconciles the optimistic user message, then appends the authoritative assistant error. Existing retry behavior remains available.
• A network failure before any authoritative headers leaves the optimistic user message in place and appends a client-only assistant error. Retry is disabled for that client-only error because the client cannot safely know whether the server persisted the turn. A reload restores authoritative history; the user can also submit a new turn manually.
• Cancelling after the assistant stream starts preserves the user message and marks the assistant message stopped, matching existing behavior.
• A 401 continues to invoke the authentication boundary. No client-only ID is sent to another user session.
• Empty, over-limit, quota-exhausted, or already-generating submissions do not create optimistic state.

Attachment Behavior

ChatComposer retains the full upload response (id, name, contentType, and size) until submit. useChat renders that metadata immediately on the optimistic user message while deriving the unchanged list of attachment IDs for /api/chat. Reconciliation changes only the message ID; attachment IDs and metadata stay stable.

Testing

Hook tests use a deliberately unresolved /api/chat promise and assert that:

• the new user message and new conversation are visible before the promise resolves;
• an existing conversation receives the user message immediately;
• server headers reconcile IDs without creating a second user message;
• an error response retains the user message and appends one assistant error;
• cancellation retains the user message and marks the assistant response stopped;
• attachment metadata appears in optimistic state while the request sends only attachment IDs;
• invalid submissions create neither state nor a network request.

Composer tests bind the updated attachment metadata callback. Existing chat, quota, model preference, conversation switching, retry, lint, typecheck, and production build suites remain required regression checks.

Deployment Verification

After the minikube rollout, an authenticated browser or equivalent delayed request test must observe the user bubble before the model request completes. The completed response must contain exactly one user bubble and one assistant response, and the resulting server conversation must remain available after reload.