In the Flutter chat interface for our tkstock project, a ghost was haunting the UI. The AI's typewriter effect would freeze mid-sentence. New data wasn't appearing, but the backend hadn't stopped sending it.
Was it a network blip? A crashed thread? No—it was a silent logic error in how we handled state updates.
The Problem: Asynchronous Ambiguity
Streaming UI bugs are tricky because of the "asynchronous illusion." When the interface freezes, it's hard to tell immediately if the SSE (Server-Sent Events) stream broke or if the frontend state merge logic failed.
If we didn't fix this thoroughly, users would face truncated content during critical information retrieval. Worse, an over-aggressive fix (like showing only the first line) would break the feature entirely.
Root Cause Analysis
1. Flawed State Append Logic
When streaming data arrived, the state update logic failed to correctly concatenate the new string with the old one. New chunks were either discarded or overwritten.
2. Boundary Misjudgment
When processing text streams containing newlines (\n), the string slicing or regex matching logic deviated, triggering an incorrect truncation branch.
3. The Regression Trap
Our first fix missed the core issue. We introduced aggressive truncation logic that discarded all subsequent content, keeping only the first line.
The Solution: Log-Driven Debugging
Core Idea: Print the full state text before and after each chunk arrives. Compare the difference with the UI display to confirm if it's a data loss or a render block.
Instead of guessing, we let the logs speak. Here is the logic shift:
// Before: Blind concatenation
onData: (chunk) {
currentText = chunk; // Wrong: Overwriting
setState(() {});
}
// After: Strict log comparison
onData: (chunk) {
print('Before: ${currentText.length}');
print('Chunk: ${chunk.length}');
currentText += chunk; // Correct: Appending
print('After: ${currentText.length}');
setState(() {});
}
These few lines helped us pinpoint the exact moment of data loss in a black-box scenario.
Minimalist Fix
Once the logs identified the problem, we applied the most minimal fix possible: remove the complex splitting logic and return to basic string appending.
// Before: Over-truncation shows only the first line
final lines = currentText.split('\n');
setState(() {
displayText = lines.first; // Wrong logic
});
// After: Atomic append
setState(() {
displayText = currentText + incomingChunk;
});
Architecture Decisions
| Decision | Alternative | Rationale |
|---|---|---|
| Chosen: Log comparison / Rejected: Blind guessing | Streaming bugs often reproduce under specific chunk sequences. Only by comparing Before/After states can we catch non-linear logic errors. | |
| Chosen: Keep existing pipeline / Rejected: Rewrite StreamBuilder | To control risk, we only fixed the core Append logic, avoiding unknown side effects from a framework rewrite. |
Key Takeaways
- The Iron Law of Streaming UI Debugging: When the UI freezes, always check if the backend is still sending data before checking if the frontend buffer is growing.
- Principle of Convergence: When fixing append bugs, never modify truncation or formatting logic simultaneously. Control changes with a single variable.
- Production Ready: Verified through 3 rounds of quality gates.
