Streaming Response Rules — Mobile
What it does
Streaming LLM responses (Server-Sent Events or chunked HTTP) requires careful handling on mobile clients. A chat response for a 5-page NDA draft may be 3,000+ tokens; on a 3G connection in a MENA market that can take 15–30 seconds. Without correct buffering, reconnection logic, and RTL-aware rendering, the user experience degrades significantly. This skill defines the rules mobile engineers must follow when implementing the streaming layer.
Setup / auth
The backend streaming endpoint:
POST /api/chat/stream — returns Content-Type: text/event-stream
- Requires
Authorization: Bearer <session_token>
- Emits SSE events:
data: { type: "delta", content: "..." } per token chunk, then data: { type: "done", usage: {...} }
For React Native, use fetch with ReadableStream; do not use EventSource (React Native does not implement it natively — use react-native-sse or a polyfill).
For Flutter, use http.Client.send() with a StreamedResponse.
Capabilities
Buffering rules
| Rule |
Reason |
| Buffer incoming delta chunks into a string accumulator; render to UI every 50 ms (not on every token) |
Prevents excessive React re-renders on fast connections |
Flush buffer immediately on \n\n (paragraph break) |
User sees complete paragraphs progressively, not mid-sentence |
Flush buffer immediately on --- (Markdown HR) |
Section breaks in legal docs should be visible early |
| Never flush mid-word |
Partial words in legal text look like garbled output |
On type: "done", flush remaining buffer and mark response as complete |
Ensures the last partial paragraph is displayed |
Reconnection logic
Mobile connections drop. The streaming endpoint must support reconnection:
- On every SSE event, emit
id: <sequence_number>.
- Client stores
lastEventId in memory (not persisted — session-scoped).
- On disconnect, client waits 1s then reconnects with
Last-Event-ID: <lastEventId> header.
- Server resumes from that sequence number (buffer the last 200 events in Redis/memory for 5 min).
- Maximum 3 reconnection attempts; after 3 failures, display an error with a "Resume" button that re-triggers the full request.
Do not attempt to resume a stream that has been idle > 5 minutes — the session context may have expired.
RTL rendering for Arabic responses
- Arabic LLM output is detected by the presence of Arabic Unicode characters in the first 30 chars of the buffer.
- On detection, set
writingDirection: "rtl" on the text container before appending further tokens. Switching direction mid-stream causes visual glitching.
- Use a dedicated
<RTLTextView> (React Native) or Text(textDirection: TextDirection.rtl) (Flutter) that is pre-configured; do not set direction dynamically on a shared component.
- Arabic legal text requires
lineHeight ≥ 1.8× the font size; ensure this is set before streaming begins.
- Do not apply
textAlign: "right" independently of writingDirection; they interact and can produce double-alignment bugs.
Mobile-specific UX rules
| Rule |
| Show a typing indicator for the first 500 ms before any tokens arrive |
Show a "Stop generating" button that calls DELETE /api/chat/stream/<requestId> |
| Long-form document drafts (>1000 tokens): show a progress indicator ("Drafting clause 3 of 7…") derived from heading-detection in the stream |
| Do not auto-scroll while the user is scrolling upward; resume auto-scroll when they scroll back to the bottom |
| On background (app minimized): pause rendering updates; on foreground: replay from buffer — do not drop tokens |
Haptic feedback on stream completion (iOS: UIImpactFeedbackGenerator, Android: Vibrator) |
Token budget display
Integrate with [[eng-token-budget-by-tier]]:
- Display remaining token budget in a small pill near the input bar: "~2,400 tokens remaining this month".
- When budget < 20%, show warning color.
- When budget = 0, disable the send button before the request is made (don't let the user send and get an error mid-stream).
Network quality adaptation
| Signal |
Action |
Connection type = 2g or slow-2g |
Warn user: "Slow connection detected — response may take longer" |
RTT > 500 ms (from Network Information API) |
Increase reconnection backoff to 3 s |
downlink < 0.5 Mbps |
Suggest switching to "Summary mode" (shorter output) |
Permissions & safety
- The streaming endpoint must validate the session token on every reconnection, not just the initial connection. A session revoked mid-stream must result in a
401 event and stream termination.
- Never cache streaming responses in HTTP caches. Set
Cache-Control: no-store.
- Do not log the full streamed content on the client. Log only
{ requestId, tokensReceived, latencyMs, reconnections }.
Failure modes
| Failure |
Impact |
Mitigation |
No lastEventId support on server |
User gets duplicate content on reconnect |
Implement sequence numbers from day one |
| Direction not set before Arabic tokens arrive |
Visual RTL flip mid-sentence |
Detect language in first 30 chars; set direction pre-emptively |
| Buffer flushed on every token |
UI janks at 30 fps on low-end Android |
50 ms flush interval via setInterval |
Stream hangs after type: "done" never arrives |
UI stuck in "thinking" state |
Set a 60 s hard timeout; if no done after 60 s, mark complete and show retry |
| Stop button ignored |
User can't cancel long draft |
Implement AbortController on the fetch; send DELETE to cancel server-side LLM call |
Related skills
- [[eng-supabase-edge-functions-patterns]] — the Edge Function that serves the streaming endpoint
- [[eng-token-budget-by-tier]] — token budget integration in the streaming UI
- [[eng-remotion-explainer-video-generator]] — alternative output format for long explanations
1---2name: eng-streaming-response-rules-mobile3description: Use when implementing or debugging the LLM token-streaming pipeline on iOS or Android clients. Defines buffering rules, reconnection logic, RTL rendering constraints, and mobile-specific UX patterns for streaming legal AI responses — including how to handle long-form document drafts that arrive over slow or intermittent mobile connections.4license: MIT5metadata:6 id: eng.streaming-response-rules-mobile7 category: eng8 jurisdictions: [__multi__]9 priority: P210 intent: [__eng__, streaming, mobile, sse, real-time]11 related: [eng-supabase-edge-functions-patterns, eng-token-budget-by-tier, eng-remotion-explainer-video-generator]12 source: https://skillmd.com/skills/sboghossian-mini-claude-for-legal/eng-streaming-response-rules-mobile13 upstream: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)14 version: "1.0"15---1617# Streaming Response Rules — Mobile1819## What it does2021Streaming LLM responses (Server-Sent Events or chunked HTTP) requires careful handling on mobile clients. A chat response for a 5-page NDA draft may be 3,000+ tokens; on a 3G connection in a MENA market that can take 15–30 seconds. Without correct buffering, reconnection logic, and RTL-aware rendering, the user experience degrades significantly. This skill defines the rules mobile engineers must follow when implementing the streaming layer.2223## Setup / auth2425The backend streaming endpoint:26- `POST /api/chat/stream` — returns `Content-Type: text/event-stream`27- Requires `Authorization: Bearer <session_token>`28- Emits SSE events: `data: { type: "delta", content: "..." }` per token chunk, then `data: { type: "done", usage: {...} }`2930For React Native, use `fetch` with `ReadableStream`; do **not** use `EventSource` (React Native does not implement it natively — use `react-native-sse` or a polyfill).3132For Flutter, use `http.Client.send()` with a `StreamedResponse`.3334## Capabilities3536### Buffering rules3738| Rule | Reason |39|---|---|40| Buffer incoming delta chunks into a string accumulator; render to UI every 50 ms (not on every token) | Prevents excessive React re-renders on fast connections |41| Flush buffer immediately on `\n\n` (paragraph break) | User sees complete paragraphs progressively, not mid-sentence |42| Flush buffer immediately on `---` (Markdown HR) | Section breaks in legal docs should be visible early |43| Never flush mid-word | Partial words in legal text look like garbled output |44| On `type: "done"`, flush remaining buffer and mark response as complete | Ensures the last partial paragraph is displayed |4546### Reconnection logic4748Mobile connections drop. The streaming endpoint must support reconnection:49501. On every SSE event, emit `id: <sequence_number>`.512. Client stores `lastEventId` in memory (not persisted — session-scoped).523. On disconnect, client waits 1s then reconnects with `Last-Event-ID: <lastEventId>` header.534. Server resumes from that sequence number (buffer the last 200 events in Redis/memory for 5 min).545. Maximum 3 reconnection attempts; after 3 failures, display an error with a "Resume" button that re-triggers the full request.5556Do not attempt to resume a stream that has been idle > 5 minutes — the session context may have expired.5758### RTL rendering for Arabic responses5960- Arabic LLM output is detected by the presence of Arabic Unicode characters in the first 30 chars of the buffer.61- On detection, set `writingDirection: "rtl"` on the text container **before** appending further tokens. Switching direction mid-stream causes visual glitching.62- Use a dedicated `<RTLTextView>` (React Native) or `Text(textDirection: TextDirection.rtl)` (Flutter) that is pre-configured; do not set direction dynamically on a shared component.63- Arabic legal text requires `lineHeight` ≥ 1.8× the font size; ensure this is set before streaming begins.64- Do not apply `textAlign: "right"` independently of `writingDirection`; they interact and can produce double-alignment bugs.6566### Mobile-specific UX rules6768| Rule |69|---|70| Show a typing indicator for the first 500 ms before any tokens arrive |71| Show a "Stop generating" button that calls `DELETE /api/chat/stream/<requestId>` |72| Long-form document drafts (>1000 tokens): show a progress indicator ("Drafting clause 3 of 7…") derived from heading-detection in the stream |73| Do not auto-scroll while the user is scrolling upward; resume auto-scroll when they scroll back to the bottom |74| On background (app minimized): pause rendering updates; on foreground: replay from buffer — do not drop tokens |75| Haptic feedback on stream completion (iOS: `UIImpactFeedbackGenerator`, Android: `Vibrator`) |7677### Token budget display7879Integrate with [[eng-token-budget-by-tier]]:80- Display remaining token budget in a small pill near the input bar: "~2,400 tokens remaining this month".81- When budget < 20%, show warning color.82- When budget = 0, disable the send button before the request is made (don't let the user send and get an error mid-stream).8384### Network quality adaptation8586| Signal | Action |87|---|---|88| Connection type = `2g` or `slow-2g` | Warn user: "Slow connection detected — response may take longer" |89| `RTT > 500 ms` (from Network Information API) | Increase reconnection backoff to 3 s |90| `downlink < 0.5 Mbps` | Suggest switching to "Summary mode" (shorter output) |9192## Permissions & safety9394- The streaming endpoint must validate the session token on every reconnection, not just the initial connection. A session revoked mid-stream must result in a `401` event and stream termination.95- Never cache streaming responses in HTTP caches. Set `Cache-Control: no-store`.96- Do not log the full streamed content on the client. Log only `{ requestId, tokensReceived, latencyMs, reconnections }`.9798## Failure modes99100| Failure | Impact | Mitigation |101|---|---|---|102| No `lastEventId` support on server | User gets duplicate content on reconnect | Implement sequence numbers from day one |103| Direction not set before Arabic tokens arrive | Visual RTL flip mid-sentence | Detect language in first 30 chars; set direction pre-emptively |104| Buffer flushed on every token | UI janks at 30 fps on low-end Android | 50 ms flush interval via `setInterval` |105| Stream hangs after `type: "done"` never arrives | UI stuck in "thinking" state | Set a 60 s hard timeout; if no `done` after 60 s, mark complete and show retry |106| Stop button ignored | User can't cancel long draft | Implement `AbortController` on the fetch; send DELETE to cancel server-side LLM call |107108## Related skills109110- [[eng-supabase-edge-functions-patterns]] — the Edge Function that serves the streaming endpoint111- [[eng-token-budget-by-tier]] — token budget integration in the streaming UI112- [[eng-remotion-explainer-video-generator]] — alternative output format for long explanations