A Streaming UI State Machine: Close, Partial and Error States

Each state should have one observable definition, so a test can assert it and a developer can reason about it without reading the component.

Two details matter. First, receiving and partial are not the same thing: one says bytes are flowing, the other says the UI has something worth rendering. Conflating them means a skeleton screen stays up after the first field has arrived. Second, stalled is deliberately not error. The connection may still be alive, so you keep cancel available and reserve retry until you have actually torn the stream down. The WHATWG streams discussion of async iteration recommends checking an abort signal each iteration and throwing the signal's reason, which gives you a clean way to move from stalled to error deliberately as described in this streams issue.

The reducer should be small enough to read in one sitting, and its inputs should be exactly two event sources: the fetch stream and the parser.

type State =
  | { k: "idle" }
  | { k: "connecting"; attempt: number }
  | { k: "receiving"; attempt: number; raw: string }
  | { k: "partial"; attempt: number; raw: string; value: unknown }
  | { k: "closed"; value: unknown }
  | { k: "error"; attempt: number; reason: string; lastValue?: unknown }
  | { k: "stalled"; attempt: number; raw: string; value?: unknown };

type Event =
  | { t: "submit" }
  | { t: "chunk"; text: string }
  | { t: "parse"; value: unknown; complete: boolean }
  | { t: "done" }
  | { t: "fail"; reason: string }
  | { t: "watchdog" }
  | { t: "retry" };

The transition rules, stated as a decision table rather than a switch you have to trace:

• submit is only legal in idle or closed, and moves to connecting with the attempt counter reset or incremented.
• chunk is only legal in connecting, receiving, partial or stalled. From connecting it goes to receiving unless the same tick produced a parsed value. From stalled it goes back to receiving or partial, which is how a pause self-heals without user action.
• parse with complete: false moves to partial if a value was yielded, otherwise stays in receiving. With complete: true it moves to closed and ignores any later chunks.
• done from the reader moves to closed only if the final validation passes, otherwise to error with the validation message.
• fail always moves to error, keeping lastValue if one existed so the panel can show what it had.
• watchdog is only legal in receiving or partial and moves to stalled. It never moves to error on its own.

The one rule that pays for the whole design: ignore events that are illegal in the current state instead of trying to handle them. A late chunk after closed gets dropped. A fail after closed gets logged but does not repaint the panel. This eliminates the class of bug where a race between the abort and the final chunk flips the UI back to an error state after a successful render.

For the watchdog, pick the threshold from measured inter-chunk gaps rather than from the total response time. Timeouts are the failure mode people handle worst, and the guidance for retry logic is to distinguish connection timeouts from read timeouts, because a read timeout mid-stream means you may already have shown partial content per this error-handling guide. A useful starting point is three times the median inter-chunk gap you observe in staging, floored at a couple of seconds so a slow first token does not trigger a false stall.

The reason teams end up with stuck buttons is that each button gets its own boolean, set in four places. The fix is one function from state to a permissions object, memoized on the state value.

function controls(s: State) {
  const canSend = s.k === "idle" || s.k === "closed";
  const canCancel = s.k === "connecting" || s.k === "receiving" ||
                    s.k === "partial" || s.k === "stalled";
  const canRetry = s.k === "error";
  return { canSend, canCancel, canRetry };
}

Three rules make this survive contact with real users.

First, send is enabled in closed but not in partial. Letting someone fire a second request while the first is half-rendered produces two panels writing into one list. If your product genuinely supports queueing, model that as a separate queued state rather than loosening the rule.

Second, cancel must do two things and both must be idempotent. It aborts the request and it cancels the reader. fetch accepts an AbortSignal and controller.abort() cancels the in-flight request per this Stack Overflow answer. Separately, ReadableStream.cancel() returns a promise that resolves when the stream is canceled, and it throws a TypeError if the stream is locked, which is exactly what happens if your reader still holds it per the MDN cancel() reference. Disable the cancel button the instant it is pressed by moving to a state where canCancel is false, and keep that state until the abort settles.

Third, retry is only legal in error, and it must decide what happens to the partial. More on that in the recovery section.

Disabling a button is not the only affordance. Screen readers will still announce a disabled button, so pair the disabled attribute with an aria-describedby pointing at the reason text ("waiting for the current response to finish"). That is the cheapest accessibility win in a streaming panel and it costs one attribute.

Numbers make the case for treating partial as a first-class state. Take a 12 KB structured response and assume the provider emits tokens fast enough that the network is not the bottleneck; the figures below come from a published benchmark of a naive re-parse-per-chunk approach against a stateful incremental parser on that document size reported here.

The naive column is the one to internalize: it is not merely slow, it degrades superlinearly, and the report notes the approach became unusable around the 5 KB mark. Your prototype never sees 5 KB, so the bug ships.

For the state machine, that table translates into a concrete rule about what to render in each state:

• connecting: skeleton, one row per top-level field in the schema, so the layout does not jump when values land.
• receiving: same skeleton, plus a subtle activity indicator, because no value has settled yet.
• partial: real values for the fields that are decided, skeleton for the rest. Strings can render progressively if the field is human-read prose and must wait for the closing quote if the field is an identifier that will be used to make a call.
• closed: everything real, canSend true, focus returned to the input.
• error: whatever was parsed, clearly marked, with retry.
• stalled: last good partial, with a cancel button and a line of text saying the model went quiet.

That last distinction, prose streams but identifiers do not, comes from the parser design discussion of what to yield when a string is mid-character, and it is worth encoding in your schema rather than deciding per component per the same partial parser analysis. A half-typed argument passed into a tool call is worse than waiting one more chunk.

A dropped stream gives you three options and you should pick one per field type, not one per app.

Option A, discard. Move to error, empty the panel, offer retry. Correct for anything where a partial value would be dangerous to act on, such as a payment amount or a tool-call argument that triggers an external side effect.

Option B, show what parsed and label it. Keep lastValue, render it with a visible "incomplete" marker, and put retry beside it. This is the right default for read-only panels where the user can judge whether the partial is useful. The invariants of an incremental parser are enough to tell which values are complete and which are still growing, and libraries exist specifically to extract a best-effort object from whatever has arrived per jsonchunk's examples. Best-effort parsers do the same trick, returning the partial structure rather than throwing on the missing brackets per the best-effort-json-parser readme.

Option C, repair and continue. Close the open braces heuristically and treat the result as complete. Only do this for display, never for anything that writes.

Whichever you choose, validate at the boundary. Truncated model output is untrusted input, and the expensive failure is not the crash, it is the half-parsed object that flows downstream and corrupts something three steps later as this comment on truncated responses argues. A schema check on the final object, and in-flight type checks on fields whose type is already decided, let you catch a type violation the moment it is determined rather than after the last token, which matters because a retry before the rest of the document is generated is cheap per the partial parser write-up.

Retry itself should be bounded and it should not silently reuse a partial. Move to connecting with attempt + 1, clear lastValue unless you are deliberately offering "keep what we had," and stop offering retry after a small fixed number of attempts so a persistent 4xx does not turn into a retry loop. Client errors are your bug and retrying them cannot help; transient server errors and rate limits benefit from backoff with jitter per this error handling guide.

One more rule that saves support tickets: when retry succeeds, replace rather than append. The panel that shows a repaired response stacked under a broken one is a UI bug people report as "the model gave me two answers."

Four tests catch almost everything, and none of them need a browser.

1. Every legal transition has a test, and every illegal one is asserted to be a no-op. Enumerate the state and event cross product, assert the reducer output, and snapshot the controls object alongside it.
2. Fuzz the chunk boundaries. Take a corpus of valid responses, split each at every byte position, feed the chunks in order, and assert the final state is closed with a value deep-equal to JSON.parse on the whole string. This is the technique incremental parser authors use to claim their parser agrees with JSON.parse per the jsonriver discussion. Splitting at every position also catches mid-character string handling, which is where most hand-rolled parsers break.
3. Simulate a stall. Send two chunks, advance fake timers past the watchdog threshold, assert stalled, then send a third chunk and assert the state returns to partial or receiving without user action.
4. Simulate an abort at every state where cancel is legal. Assert no unhandled rejection, assert the panel does not flash to error, and assert the cancel button is disabled from the first click onward.

The value of running these in a reducer rather than through the component is that a failing test names the exact transition, and the fix is a one-line change to a table instead of a hunt through effects.

If you are building this against more than one provider, the transport layer is where the APIs differ and where a unified endpoint saves real work. Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI-compatible API key, so the stream handling you write once keeps working when the model changes underneath it: https://quantaintelligence.ai/inference.