DEV Community: babycat

A Stream Retry Needs a Fresh Announcement, Not a Rewritten Transcript

babycat — Thu, 24 Sep 2026 17:55:41 +0000

While I was keyboard-testing this single-file demo, I retried a chat answer that had stalled after one short clause. I pressed Escape to cancel, then activated Retry, and I expected a clean announcement of a new attempt. Instead the reader spoke the cancelled fragment and the new sentence as if they were one paragraph. The primary button still announced Stop, even though the request had already failed and the composer was idle.

Have you ever watched a status line look correct while the spoken version told an older story? That gap is what I chased through this reproduction, not through a production incident I am quoting. The pixels showed a tidy replacement, but the accessibility tree still carried the previous generation of text. If the transcript looks replaced, why am I still hearing the sentence I cancelled?

The failure I could hear but not see

I had built a small streaming panel for a browser chat, the kind of control I keep keyboard-operable on purpose. The transcript lived in one paragraph, and that same paragraph carried a polite live region. On retry I cleared the text and wrote the next tokens into that identical node, which looked like a reset. I trusted the visual reset for too long, because my eyes could not hear the glued sentence.

A live region is closer to a public-address microphone than to an ordinary text editor on the page. If you rewrite the card already sitting on that microphone, some listeners hear the rewrite as a continuation. Why would clearing the text not count as a brand new message for every assistive technology you test? Several readers decide what to speak from node identity, not from the string you wish they would forget.

The second symptom showed up on the button, not inside the paragraph I had been staring at. Stop and Retry were the same element, and its accessible name came from a closure captured at start. After cancel, focus stayed on that button, which is exactly the behavior I wanted to keep. The name did not update until a later paint, so the next Enter still meant Stop while the label claimed Retry.

What else should a focused button be allowed to mean, if its name and its action disagree? I do not want a keyboard user to activate Stop on an attempt that has already ended. I also do not want focus thrown back to the composer, because that hides the control they just used. The repair had to keep focus put, and it had to change the name in the same turn.

A state table before any more guesses

I stopped poking the DOM and wrote the phases down before I changed another line of the demo. Guessing inside the accessibility tree is how I usually make this class of bug harder to hear. The table below is the contract I tested against, not a description I invented after the fix already worked.

Phase	Visible name	Focus target	What may be announced
idle	Retry answer	Retry answer	Nothing new
streaming	Stop generating	Stop generating	Generating, spoken once
cancelled	Retry answer	Retry answer	Cancelled. Retry is available.
failed	Retry answer	Retry answer	The error, then Retry is available.

Each row is one generation, and a retry must increment that generation before any token is allowed to arrive. If the generation does not change, I treat the interface as still sitting on the old attempt. That single integer saved me from arguing with the screen reader about which sentence it should forget.

idle --start--> streaming --token--> streaming
streaming --cancel--> cancelled --start--> streaming
streaming --fail--> failed --start--> streaming
streaming --done--> idle
late token whose generation mismatches --> ignored

How I traced the stale node

I reproduced the race with a local timer first, because I did not want a network sitting in the loop yet. The sequence was start, one token, cancel, retry, and then a token that belonged to the new attempt. I logged the phase, the generation, and the announcer text after every single dispatched event. The log showed generation two while the live node still held generation one text plus the new clause.

Three checks, in the order I ran them

Three checks told me the root cause, and none of them required a framework profiler or a production trace. I am listing them in the order I ran them, so you can repeat the same narrowing on your own page. Have you tried comparing node identity before you start adding more ARIA attributes to a noisy region?

I compared the announcer reference after retry, and it never changed, so assistive tech had no new node to treat as a fresh message.
I read the button text in the same turn as cancel, and it still said Stop because the name update waited on a stale closure.
I set aria-atomic on the growing transcript, which made the duplication louder, so that attribute was not the missing fix.

Was the bug a screen reader quirk, or was it the tree I had built with my own hands? Both can be true on a given browser, and I still owned the tree I was shipping in the demo. I was mutating one polite region and hoping a deletion would be announced as a deletion, which often does not happen. Adding more roles would have decorated the bug instead of removing the shared node.

The fix: split the transcript from the announcement

I separated the visual transcript from a dedicated announcer, and I replace that announcer node on every phase change. The transcript can update freely, because it is explicitly not a live region and it does not ask to be spoken. The announcer receives one short sentence per transition, and I drop that node so the next sentence cannot glue itself on.

<section aria-labelledby="thread-label">
  <h2 id="thread-label">Answer</h2>
  <div id="transcript" aria-live="off"></div>
  <div id="announcer" aria-live="polite" aria-atomic="true"></div>
  <button id="primary" type="button">Retry answer</button>
</section>

function reduce(state, event) {
  if (event.type === "start" && state.phase !== "streaming") {
    return {
      phase: "streaming",
      generation: state.generation + 1,
      partial: "",
      error: "",
    };
  }
  if (event.type === "token" && state.phase === "streaming") {
    return { ...state, partial: state.partial + event.text };
  }
  if (event.type === "cancel" && state.phase === "streaming") {
    return { ...state, phase: "cancelled" };
  }
  if (event.type === "fail" && state.phase === "streaming") {
    return { ...state, phase: "failed", error: event.message };
  }
  if (event.type === "done" && state.phase === "streaming") {
    return { ...state, phase: "idle" };
  }
  return state;
}

function announce(message) {
  const region = document.getElementById("announcer");
  const fresh = region.cloneNode(false);
  fresh.id = "announcer";
  fresh.setAttribute("aria-live", "polite");
  fresh.setAttribute("aria-atomic", "true");
  fresh.textContent = message;
  region.replaceWith(fresh);
}

function render(state) {
  const button = document.getElementById("primary");
  const transcript = document.getElementById("transcript");
  const streaming = state.phase === "streaming";
  transcript.textContent = state.partial;
  button.textContent = streaming ? "Stop generating" : "Retry answer";
  button.setAttribute("aria-pressed", streaming ? "true" : "false");
}

Names, focus, and what I refuse to announce

The reducer is the part I trust under test, because the DOM is where I previously lied to myself about state. The announce helper clones the region so the next polite message has a new identity instead of an edited one. Render writes the button name in the same turn as the phase, which keeps a focused control from telling two stories. I also refuse to push every incoming token into the announcer, because token spam is how a polite region falls behind.

A backlog that arrives after you cancel is just the old bug wearing a slightly more polite voice. Phase changes and the final failure are enough speech for this control, and the transcript can stay visual. You can force the broken path in the console if you expose a lab-only dispatcher and then remember to remove it. This check is a lab assertion for the page, not a recorded production test from a customer session.

let state = { phase: "idle", generation: 0, partial: "", error: "" };

function onChunk(generation, text) {
  if (generation !== state.generation || state.phase !== "streaming") {
    return;
  }
  state = reduce(state, { type: "token", text });
  render(state);
}

function assert(condition, label) {
  if (!condition) throw new Error(label);
}

state = reduce(state, { type: "start" });
state = reduce(state, { type: "token", text: "Old clause. " });
state = reduce(state, { type: "cancel" });
const cancelledGen = state.generation;
state = reduce(state, { type: "start" });
assert(state.generation === cancelledGen + 1, "retry bumps generation");
assert(state.partial === "", "retry clears the cancelled clause");
onChunk(cancelledGen, "late");
assert(state.partial === "", "old generation chunks are ignored");

const button = document.getElementById("primary");
let controller = new AbortController();

button.addEventListener("click", () => {
  if (state.phase === "streaming") {
    controller.abort();
    state = reduce(state, { type: "cancel" });
    announce("Cancelled. Retry is available.");
  } else {
    controller = new AbortController();
    state = reduce(state, { type: "start" });
    announce("Generating a new answer.");
    startStream(controller.signal, state.generation);
  }
  render(state);
});

document.addEventListener("keydown", (event) => {
  if (event.key === "Escape" && state.phase === "streaming") {
    event.preventDefault();
    button.click();
  }
});

python3 -m http.server 4173
# Open http://127.0.0.1:4173/retry-announcer.html
# Start a stream, press Escape, activate Retry, and listen once.

Where a slow first byte made the race obvious

A local timer of a few dozen milliseconds hid the stale closure, because the next paint often won the race. I needed a genuinely late first chunk, without pretending I had measured a product benchmark or a quota. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I hosted this single-file page on MonkeyCode's free server option and pointed the stream at their free model access, then treated the endpoint as an opaque fetch.

I did not record a hardware shape, a duration promise, or an allotment you should plan a launch around. Those details change, so you should read the current product page before you depend on any free option. What I logged in the page was only a client timestamp for start and another timestamp for the first chunk. I am not publishing that gap as a benchmark, because one afternoon on one network is not a measurement.

When the first chunk was slow enough that I could cancel and retry, the fast timer's hidden race showed up. The button must already say Stop before the await resolves, or a late response can land in a cancelled generation. Would I ship this against any remote stream, free or paid, without that generation guard in the chunk handler? No, because a slow accept is exactly when people cancel, and late bytes love that moment.

async function startStream(signal, generation) {
  const started = performance.now();
  const response = await fetch("/api/stream", {
    method: "POST",
    signal,
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ generation }),
  });
  if (!response.ok || !response.body) {
    state = reduce(state, {
      type: "fail",
      message: "The answer did not start.",
    });
    announce("The answer did not start. Retry is available.");
    render(state);
    return;
  }
  console.info("first-chunk-ms", Math.round(performance.now() - started));
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const step = await reader.read();
    if (step.done) break;
    onChunk(generation, decoder.decode(step.value, { stream: true }));
  }
  if (state.generation === generation && state.phase === "streaming") {
    state = reduce(state, { type: "done" });
    announce("Answer complete.");
    render(state);
  }
}

I ignore chunks whose generation does not match the generation I started, even if the bytes are otherwise well formed. A slow accept is exactly when people cancel, and a slow accept is also when late bytes love to arrive. That real network wait only made the race easier to practice, and the guard is what made the wait safe. The announcer still speaks the cancel sentence from the click handler, not from the late response.

A QA matrix you can run this afternoon

I keep the matrix next to the demo, because a passing happy path is how this bug survived the first review. Run it with the browser, the operating system, and the assistive technology versions written down beside the result. I am not claiming conformance, and I am not claiming these listeners behave the same way on your machine.

Transitions that must not glue

Keyboard only, no reader: Escape cancels, focus stays on the primary button, and the visible name becomes Retry answer before the next Enter.
A reader plus Firefox, or VoiceOver plus Safari: cancel is spoken once, and the following retry does not repeat the cancelled clause inside the same utterance.
Failure before tokens: force a non-OK response, confirm the composer is not left busy, and confirm Retry remains reachable by Tab.
Late chunk: dispatch a token after cancel and confirm the transcript does not grow, and confirm the announcer stays silent for that chunk.
Reduced motion: the button name still changes, because this bug is not an animation problem and a motion setting must not be the only fix.
Zoom at 200 percent: the primary button remains in view after the transcript grows, so a keyboard user is not activating an off-screen Stop.

Who should skip this pattern

This split is for a chat-style answer that should speak phase changes, not for captions that must speak every token. If your users edit the streaming region, do not replace nodes out from under a selection they are still moving. If you need a certified audit, hire that audit, because a passing matrix on my laptop is not a conformance claim. Do not use a free server option as a capacity plan, and do not treat free model access as a fixed allotment I measured for you.

I am not covering mobile gesture patterns or research interviews in this note, because those are different jobs. The clone-and-replace trick can get noisy if you announce on every token instead of on each phase change. Some readers still coalesce polite updates when two messages arrive too close together on a busy main thread. Leave a short idle gap between the cancel sentence and the generating sentence, and do not treat a microtask as a timing promise.

What I want you to reproduce

Fork the single file, break the clone so retry writes into the old node, and then listen to Escape followed by Retry. Write down the browser, the operating system, and the assistive technology version next to the exact transition that glued. Then restore the clone, repeat that same transition, and confirm the cancelled clause is not spoken again. If a late chunk still appears, the generation guard is the next line I would inspect.

If you want a free place to host the file and a free model stream for that slow first chunk, check MonkeyCode's current docs, then run this same Escape-then-Retry path. I would rather hear which reader version glued the two sentences than collect another happy-path screenshot. That is the repair I trust: a new announcement node, a button name written in the same turn, and a generation check that drops late bytes. The transcript can stay visually calm, and the spoken control should not have to guess which attempt you meant.

A Quiet Stream Close Needs a Focusable Diagnostics Panel, Not Console Logs

babycat — Wed, 23 Sep 2026 15:56:10 +0000

Have you ever watched a chat spinner keep spinning after DevTools already marked the fetch as complete? I have seen that exact spinner, and the keyboard path felt worse than the visual lie. I tabbed to Stop, pressed Enter twice, and nothing in the composer then moved at all. The screen reader stayed completely silent, so I assumed the remote model was still thinking hard.

It was not thinking in any useful sense, because the response body had already closed itself. The streamed body finished with zero tokens and without an error payload I could parse. That failure is not a stall, because a stall still owns an open reader on the client. This is a quiet close: the connection is gone, aria-busy stays true, and cancel is already dead.

Why did Stop refuse a perfectly timed Enter? Because disabled={!isStreaming} flipped false in the same tick that cleared the reader. The turn looked busy in CSS, looked finished in the network waterfall, and looked like nothing at all to VoiceOver.

The interaction that actually failed

I was wiring a browser agent prototype to a remote origin so I could test cancel and retry without a paid key. The visual chrome looked industrious. The waterfall said the request was done. VoiceOver on macOS said nothing after the first “Generating” announcement. Escape did not abort, because the AbortController had already settled, and the control was disabled.

Here is the failure in the order I felt it:

Focus sits in the composer after I submit a short prompt with Enter.
A CSS spinner replaces the status text, and no later live update ever arrives.
The remote origin closes the stream without an error event and without a token.
Stop becomes disabled, Retry never appears, and the live region never speaks a dead-end.
Tab order still includes the composer, which feels editable, even though we still treat the turn as in flight.

If you only test a local mock that always yields tokens, you will never see this path. Quiet close shows up on free remote origins, flaky proxies, and HTTP 200 responses whose bodies end empty.

I guessed the wrong layer first

I did what most of us do under time pressure, and I guessed in the wrong layer first. I blamed a React remount that dropped focus. I blamed a polite live region that swallowed the update. I blamed the model for being “slow” when it was already gone.

Those guesses were reasonable, and they were still wrong. The assistant message node never remounted during the hang. The live region was polite, empty, and honest about having nothing to say. The model never produced a byte of data:.

What actually failed was a four-bucket state machine: idle, streaming, complete, and error. A quiet close is none of those buckets. The fetch fulfilled, response.body existed, and the first read() returned { done: true }. We mapped that to complete with empty text. Complete disabled Stop. Empty text did not look like an error. The only diagnostics lived in console.debug.

The state table I wish I had drawn on day one

Draw this before you style a spinner. Complete must mean the reader has something to read.

State	Tokens	Connection	Stop	Retry	Live announcement	Focus target
`idle`	n/a	none	hidden	hidden	none	composer
`submitting`	0	opening	enabled	hidden	“Submitting prompt”	status
`streaming`	waiting or growing	open	enabled	hidden	throttled status, never raw tokens	status or Stop
`quiet_close`	0	closed	hidden	enabled	“The model closed without a reply”	diagnostics heading
`network_error`	any	closed	hidden	enabled	specific error text	diagnostics heading
`aborted`	any	closed	hidden	enabled	“Generation cancelled”	composer
`complete`	> 0	closed	hidden	hidden	“Reply complete”	composer

Notice quiet_close is not complete. Complete means a person can read a reply. Quiet close means the turn ended with nothing to read and nothing to blame. If your UI only has success and thrown errors, this row falls on the floor.

Enter in composer
  -> submitting  (aria-busy=true, Stop enabled)
      -> streaming (chunks arrived)
          -> complete  (busy=false, focus composer)
      -> read done, tokens === 0
          -> quiet_close  (busy=false, focus diagnostics, Retry)
      -> fetch throw
          -> network_error
      -> abort()
          -> aborted  (focus composer)

The analogy I use now is a train that arrives with no cars. The platform board should not say “On time.” It should say “This service ended empty,” and it should point you at a station desk you can actually walk to. The diagnostics panel is that desk. It is not a toast, and it is not a console line.

Minimal reproduction

The file below is a labeled demo, not a vendor SDK, and it does not parse every SSE dialect. It fakes a reader that can finish empty, which is the quiet-close path I kept missing in mocks that always streamed “Hello.” Point fetch at a real remote origin later if you want production-shaped headers. Keep the state names stable when you do that swap.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. I used their free model access and free server option as a no-key remote origin while I reproduced the empty-body close, not as a magic accessibility fix. The panel below is still your UI problem even if the origin is local.

<!doctype html>
<meta charset="utf-8" />
<title>Quiet-close diagnostics demo</title>
<style>
  :root { font: 16px/1.45 system-ui; color: #102a43; }
  body { max-width: 40rem; margin: 2rem auto; }
  #status[aria-busy="true"] { outline: 2px dashed #1864ab; outline-offset: 4px; }
  #diag:focus { outline: 3px solid #d9480f; }
  button:disabled { opacity: .45; }
  pre { background: #f1f3f5; padding: 1rem; overflow: auto; }
</style>

<form id="form">
  <label for="prompt">Prompt</label>
  <textarea id="prompt" rows="3">Explain quiet close in one sentence.</textarea>
  <div>
    <button type="submit" id="send">Send</button>
    <button type="button" id="stop" hidden>Stop</button>
  </div>
</form>

<p id="status" aria-live="polite"></p>

<section id="panel" hidden aria-labelledby="diag">
  <h2 id="diag" tabindex="-1">Stream diagnostics</h2>
  <dl>
    <dt>Origin</dt><dd id="d-origin"></dd>
    <dt>Request id</dt><dd id="d-id"></dd>
    <dt>Last event</dt><dd id="d-event"></dd>
    <dt>Decoded bytes</dt><dd id="d-bytes"></dd>
  </dl>
  <button type="button" id="copy">Copy diagnostics</button>
  <button type="button" id="retry">Retry same prompt</button>
  <button type="button" id="edit">Edit prompt</button>
</section>

<pre id="reply" hidden></pre>

<script>
const $ = (id) => document.getElementById(id);
/** @typedef {'idle'|'submitting'|'streaming'|'quiet_close'|'network_error'|'aborted'|'complete'} TurnState */

let state = 'idle';
let controller = null;
let lastPrompt = '';
let diag = { origin: 'demo://quiet-close', requestId: '', lastEvent: '', bytes: 0 };

function announce(text) { $('status').textContent = text; }

function setBusy(busy) { $('status').setAttribute('aria-busy', busy ? 'true' : 'false'); }

function render(next) {
  state = next;
  const streaming = next === 'submitting' || next === 'streaming';
  $('send').disabled = streaming;
  $('stop').hidden = !streaming;
  $('stop').disabled = !streaming;
  $('panel').hidden = !(next === 'quiet_close' || next === 'network_error');
  $('reply').hidden = next !== 'complete';
  setBusy(streaming);
}

function showDiag() {
  $('d-origin').textContent = diag.origin;
  $('d-id').textContent = diag.requestId;
  $('d-event').textContent = diag.lastEvent;
  $('d-bytes').textContent = String(diag.bytes);
  $('diag').focus();
}

async function fakeQuietClose(signal) {
  // Labeled demo: a 200-shaped stream that ends on the first read.
  await new Promise((r) => setTimeout(r, 400));
  if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
  return { type: 'quiet_close', lastEvent: 'done', bytes: 0 };
}

async function runTurn(prompt) {
  lastPrompt = prompt;
  controller = new AbortController();
  diag = { ...diag, requestId: crypto.randomUUID(), lastEvent: 'open', bytes: 0 };
  render('submitting');
  announce('Submitting prompt');
  try {
    render('streaming');
    announce('Waiting for tokens');
    const result = await fakeQuietClose(controller.signal);
    diag.lastEvent = result.lastEvent;
    diag.bytes = result.bytes;
    if (result.type === 'quiet_close') {
      render('quiet_close');
      announce('The model closed without a reply. Diagnostics are focused.');
      showDiag();
      return;
    }
    render('complete');
    announce('Reply complete');
    $('prompt').focus();
  } catch (err) {
    if (err.name === 'AbortError') {
      render('aborted');
      announce('Generation cancelled');
      $('prompt').focus();
      return;
    }
    diag.lastEvent = 'throw';
    render('network_error');
    announce('The request failed. Diagnostics are focused.');
    showDiag();
  }
}

$('form').addEventListener('submit', (e) => {
  e.preventDefault();
  const prompt = $('prompt').value.trim();
  if (!prompt || state === 'submitting' || state === 'streaming') return;
  runTurn(prompt);
});

$('stop').addEventListener('click', () => controller && controller.abort());
$('retry').addEventListener('click', () => runTurn(lastPrompt));
$('edit').addEventListener('click', () => { render('idle'); $('prompt').focus(); });
$('copy').addEventListener('click', async () => {
  const text = Object.entries(diag).map(([k, v]) => `${k}: ${v}`).join('\n');
  await navigator.clipboard.writeText(text);
  announce('Diagnostics copied');
});
</script>

Three bugs stacked, which is why the UI felt haunted instead of merely empty. First, we treated done: true as success even when the decoder had never emitted a token. Second, Stop used disabled={!isStreaming}, so the control vanished in the same frame the reader died. Third, failure details went to console.debug, so keyboard and screen-reader users had no object they could land on.

What I changed in the real control

I kept Stop enabled through submitting and streaming, then I swapped it for Retry without a hidden gap. I moved origin, request id, last event, and decoded byte count into a section with a heading that is programmatically focused. I throttled the polite live region so it speaks state names, not a token firehose that drowns Escape. I set aria-busy only while the reader is actually owned.

Practical rules I now refuse to violate:

Diagnostics are a section labelled by a heading, never a role="alert" toast that steals context.
The heading uses tabindex="-1" so I can move focus without inserting a surprise tab stop.
Copy, Retry, and Edit prompt are real button elements, not clickable divs with keydown folklore.
Pointer users and keyboard users get the same recovery actions. Hover is not a requirement.
Token text never goes into an assertive live region. Assertive firehoses make cancel announcements impossible to hear.
A new retry gets a new request id. Re-announcing the whole transcript is its own accessibility bug.

When you later replace fakeQuietClose with fetch, keep the mapping explicit. read() returning { done: true } with zero decoded bytes is quiet_close. A thrown TypeError is network_error. AbortError is aborted. HTTP 200 is not a personality trait of the model. It is just a status code.

async function readSse(response, signal) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let bytes = 0;
  let lastEvent = 'open';
  while (!signal.aborted) {
    const { done, value } = await reader.read();
    if (done) {
      lastEvent = 'done';
      break;
    }
    bytes += decoder.decode(value, { stream: true }).length;
    lastEvent = 'chunk';
  }
  if (bytes === 0) return { type: 'quiet_close', lastEvent, bytes };
  return { type: 'complete', lastEvent, bytes };
}

Keyboard and screen-reader regressions I now run

I do not trust a green network waterfall anymore. I run these in order, and I write down the exact transition that failed.

Keyboard-only send: Tab to the textarea, type, Enter, confirm focus is not lost on submit.
Stop while submitting: activate Stop before the first chunk; expect aborted and composer focus.
Quiet close: force an empty 200 body; expect diagnostics heading focus and a Retry tab stop.
Screen reader: confirm one polite announcement for the dead-end, not a replay of the prompt.
Copy diagnostics: activate Copy, then paste into the textarea; expect a short “copied” announcement.
Retry: activate Retry; expect a new request id and no second copy of the old transcript.
Edit prompt: activate Edit prompt; expect focus in the textarea with the original text intact.
Pointer independence: repeat 3–7 with only the keyboard. If a path needs a mouse, it is not done.

Environment matrix

Please reproduce with versions, not vibes. The transition I care about is streaming → quiet_close with zero tokens.

Environment	What I check
Chrome latest, Windows, NVDA	Diagnostics heading takes focus; NVDA speaks the dead-end once
Firefox latest, Windows, NVDA	Stop does not disable before Retry is present
Safari latest, macOS, VoiceOver	Rotor still finds the diagnostics `section`
Keyboard only, any browser	Tab order is composer → Send/Stop → diagnostics actions
Reduced motion	Spinner is optional; the text status still changes

If your quiet close only “works” in a mouse-driven Chromium session, you have a demo, not a control.

Limitations, and who should not copy this blindly

This approach detects a heuristic: the stream ended and we decoded nothing. It cannot explain why the origin stayed silent, and it will mislabel a model that legitimately answers with an empty string as a transport failure. It also does not replace server-sent error events, request tracing, or a real SSE parser for your vendor.

Do not ship this as production incident response if you need contractual uptime, authenticated billing, or guaranteed model routing. Do not hide legal or privacy failures inside the same panel as a quiet close. Do not use an assertive live region “so users notice”; they will notice so hard that they cannot hear Stop. Teams that never test with a screen reader should not claim the panel is accessible just because a heading exists in the DOM.

If you want a no-key remote origin to reproduce the empty-body path I hit, MonkeyCode’s free model access and free server option are enough to stand up the same demo. Bring a browser, an assistive-technology version, and the exact streaming → quiet_close transition, not a screenshot of a happy-path spinner.

An In-Browser Agent Needs a Consent Gate You Can Tab Through, Not a Silent Fetch

babycat — Tue, 22 Sep 2026 14:14:00 +0000

I was keyboard-deep in a chat composer, waiting on a suggested patch, when the network panel blinked twice. The in-browser agent had already attached the open buffer before I could refuse the request. No dialog moved focus, and no status text named the file that just left the tab. Have you ever only learned about a context leak because DevTools had the Request tab open?

That silent-fetch failure is not a model-quality problem, and it is not a streaming-markdown problem either. It is a consent control that never became a tab stop, then lost the race against the first tool call. I treated it as a debugging retrospective, from the silent fetch back to a typed state machine you can actually operate with a keyboard.

The interaction that failed

I reproduced the bug in a single-file chat shell that can optionally send the current editor selection to a local completion endpoint. The pointer path looked fine because a tiny toast said "Using page context" for about two seconds. Keyboard users never reached that toast, while screen-reader users only heard the transcript tokens update instead. If you only test with a mouse, you will ship this exact race.

Here is the exact transition that broke, and I still use it as the first replay in the debugger:

Focus sits in the composer after Enter, with the caret blinking on an empty follow-up line.
The agent decides it needs page context, then POSTs the current selection without waiting.
A toast renders in the corner with a pointer-only Dismiss control that is not a tab stop.
Tokens arrive in an aria-live region, so the toast copy never wins the speech queue.
Escape still maps to "stop generating," which cannot undo the buffer that already left the tab.

Would a checklist that only asks "is there a message" have caught any of that? It would not, because the message never became operable.

State table before any ARIA

I write the state table before I reach for a dialog role, because a role cannot invent states that the reducer does not own. This is the machine I should have drawn on the first pass, before the toast CSS went in.

State	Visible UI	Focus owner	Announcement	Network
`idle`	composer only	composer	none	none
`requesting`	modal consent	Deny first	"The agent wants the current selection."	blocked
`allowed`	context chip plus composer	composer restored	"Selection attached. You can remove it."	may send
`denied`	composer plus retry hint	composer restored	"Page context was not sent."	no body
`failed`	error plus retry	Retry	"Context consent failed. Retry or continue without it."	aborted

Notice that allowed is not the default, and denied is not a disabled composer. Why would we punish a refusal by trapping someone outside the input they still need?

stateDiagram-v2
  [*] --> idle
  idle --> requesting: NEED_CONTEXT
  requesting --> allowed: ALLOW
  requesting --> denied: DENY / Escape
  requesting --> failed: FAIL
  failed --> requesting: retry
  denied --> requesting: NEED_CONTEXT
  allowed --> denied: RESET / remove chip

Symptom to root cause

I debug this class of bug with the same four probes every time, because they fail in different layers and they do not need a new tracing product. Each probe answers one question the toast never could.

Probe 1: keyboard-only, mouse unplugged

Tab order never entered the toast, which I confirmed by watching the focus ring stall in the textarea. The Dismiss control was a <div onClick>, so it was not a tab stop at all. Have you shipped a "message" that a keyboard user cannot even land on?

Probe 2: `document.activeElement` on every transition

I logged document.activeElement from the reducer subscriber, then printed the tag name beside each state change. Focus stayed in the textarea while the fetch started, which is how a silent send feels snappy and also how it becomes invisible. Snappy is not the same as operable, right?

Probe 3: screen-reader speech log

VoiceOver spoke each streamed token from the live region and skipped the toast entirely, which the speech log made painfully obvious. NVDA did the same once the polite live region started batching those tokens into a queue. The consent copy never had a chance to win that queue, so privacy UI became decoration.

Probe 4: the consent flag race

localStorage still held pageContext: true from a previous demo session on the same origin, which I only noticed after wiping cookies failed to change the POST body. The UI treated that flag as durable consent, even though the selection hash had changed under it. Did we consent to this buffer, or to some other buffer last Tuesday?

Root cause, in one line you can put on a sticky note: consent was a boolean side effect, not a blocking, focus-managed, scope-limited state with a deny path.

The fix: a consent gate with an abort owner

The analogy I use is a locked door between the composer and the network stack, and it has to stay locked during the first tool call. Tokens may wait in the hallway, but they do not walk through until a person operates that door. Cancellation still belongs to the in-flight request, yet deny has to win if the dialog is still open. Who owns abort if Escape means two different things?

Below is a proposed single-file reducer you can paste into a React demo, and I am labeling it as a reproduction rather than a conformance claim. I have not certified it against every browser and assistive-technology pair, so please treat the matrix later as a hunt list.

type Scope = "selection" | "file";

type ConsentState =
  | { status: "idle" }
  | { status: "requesting"; scope: Scope; returnFocusTo: HTMLElement | null }
  | { status: "allowed"; scope: Scope; selectionHash: string }
  | { status: "denied"; scope: Scope }
  | { status: "failed"; message: string; returnFocusTo: HTMLElement | null };

type ConsentEvent =
  | { type: "NEED_CONTEXT"; scope: Scope; returnFocusTo: HTMLElement | null }
  | { type: "ALLOW"; selectionHash: string }
  | { type: "DENY" }
  | { type: "FAIL"; message: string }
  | { type: "RESET" };

function consentReducer(state: ConsentState, event: ConsentEvent): ConsentState {
  switch (state.status) {
    case "idle":
    case "denied":
    case "failed":
      if (event.type === "NEED_CONTEXT") {
        return {
          status: "requesting",
          scope: event.scope,
          returnFocusTo: event.returnFocusTo,
        };
      }
      return state;
    case "requesting":
      if (event.type === "ALLOW") {
        return {
          status: "allowed",
          scope: state.scope,
          selectionHash: event.selectionHash,
        };
      }
      if (event.type === "DENY") return { status: "denied", scope: state.scope };
      if (event.type === "FAIL") {
        return {
          status: "failed",
          message: event.message,
          returnFocusTo: state.returnFocusTo,
        };
      }
      return state;
    case "allowed":
      if (event.type === "RESET" || event.type === "DENY") {
        return { status: "denied", scope: state.scope };
      }
      return state;
    default:
      return state;
  }
}

The dialog markup has to match those states, or the reducer is just theater with extra TypeScript. Deny is the first tab stop because accidental Enter should not upload a file.

function ConsentGate(props: {
  state: ConsentState;
  onAllow: () => void;
  onDeny: () => void;
  onRetry: () => void;
}) {
  const denyRef = useRef<HTMLButtonElement>(null);
  const headingId = useId();
  const descId = useId();

  useEffect(() => {
    if (props.state.status === "requesting" || props.state.status === "failed") {
      denyRef.current?.focus();
    }
  }, [props.state.status]);

  if (props.state.status !== "requesting" && props.state.status !== "failed") {
    return null;
  }

  const isFailed = props.state.status === "failed";

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby={headingId}
      aria-describedby={descId}
      className="consent-gate"
    >
      <h2 id={headingId}>Share page context with the agent?</h2>
      <p id={descId}>
        {isFailed
          ? props.state.message
          : `The agent wants the current ${props.state.scope}. Deny stays the default.`}
      </p>
      <button ref={denyRef} type="button" onClick={props.onDeny}>
        Deny
      </button>
      {!isFailed ? (
        <button type="button" onClick={props.onAllow}>
          Allow once
        </button>
      ) : (
        <button type="button" onClick={props.onRetry}>
          Retry consent
        </button>
      )}
    </div>
  );
}

Restore focus in the parent, not inside the dialog, because the dialog unmounts on allow and deny. I keep returnFocusTo on the requesting state so a later render cannot guess the composer.

useEffect(() => {
  if (state.status === "allowed" || state.status === "denied") {
    queueMicrotask(() => composerRef.current?.focus());
  }
}, [state.status]);

useEffect(() => {
  function onKey(event: KeyboardEvent) {
    if (event.key === "Escape" && state.status === "requesting") {
      event.preventDefault();
      dispatch({ type: "DENY" });
    }
  }
  window.addEventListener("keydown", onKey);
  return () => window.removeEventListener("keydown", onKey);
}, [state.status]);

A few implementation rules I now refuse to skip, because each one maps to a probe that already failed:

Deny is the first tab stop, so a leftover Enter from the composer cannot allow by accident.
Escape calls the same DENY event as the button, so pointer and keyboard share one abort owner.
"Allow once" stores a selection hash, and it never writes a durable boolean for a different buffer.
The composer region is inert while the dialog is open, which keeps Tab from wandering into streamed links.
After allow or deny, focus returns to the composer, not to a toast, and not to the transcript.
A separate polite live region announces only the state change, never the token stream that is still painting.

What I wired around the fetch

The network function has to ask the gate, not the other way around, which is the inversion the original toast never made. This is the proposed client wrapper, still labeled as a reproduction you should run locally.

async function completeWithConsent(opts: {
  prompt: string;
  selection: string;
  selectionHash: string;
  getState: () => ConsentState;
  dispatch: (event: ConsentEvent) => void;
  signal: AbortSignal;
}) {
  const state = opts.getState();
  const allowed =
    state.status === "allowed" && state.selectionHash === opts.selectionHash;

  if (opts.selection && !allowed) {
    opts.dispatch({
      type: "NEED_CONTEXT",
      scope: "selection",
      returnFocusTo: document.activeElement as HTMLElement,
    });
    throw new DOMException("Consent required", "AbortError");
  }

  const body = allowed
    ? { prompt: opts.prompt, selection: opts.selection }
    : { prompt: opts.prompt };

  const response = await fetch("/complete", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: opts.signal,
  });

  if (!response.ok) {
    opts.dispatch({ type: "FAIL", message: `HTTP ${response.status}` });
    throw new Error("completion failed");
  }

  return response.body;
}

Throwing AbortError on missing consent looks aggressive, and that is the point of a gate that owns the body. The composer stays enabled, the dialog owns focus, and a later Allow can re-enter the same prompt without rewriting history. Is a disabled composer really recovery, or is it just a locked door with no handle?

Where a free completion endpoint actually helped

I needed slow streams and fast streams of the same prompt so the dialog could not hide behind a skeleton. Paid keys make that rehearsal annoying when you are iterating on focus restoration, not on model quality.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

I rehearsed the gate against MonkeyCode's free model access and free server option so consent still blocked the body when the first token was delayed. That is the only product dependency in this write-up, and you can replace the endpoint with any local completion server if you already have one. If you want a throwaway host for the same consent rehearsal, that free server option is one convenient path.

Expected UI states

These are the states I now screenshot beside the reducer, because a passing unit test still will not show you the focus ring.

Idle: the composer is the only tab stop in the transcript footer, and no chip claims context is attached.
Requesting: the dialog is centered, the background is inert, Deny is focused, and the fetch has not started.
Allowed: a chip reads "Selection attached," focus is back in the composer, and Remove is a real button.
Denied: there is no chip, a polite announcement fires once, and the prompt stays editable.
Failed: Retry consent and Continue without context are both tab stops, and neither disables the input.

If the chip is a non-focusable span, you have reintroduced the toast with better copy. Can a keyboard user remove the selection without hunting through the transcript?

Keyboard and screen-reader regressions

I keep this matrix next to the demo, and I record the exact transition that failed instead of writing "tested with a screen reader." Please reproduce with your browser, operating system, and assistive-technology versions.

Environment	Transition	Expected	Failure I am hunting
Chromium + NVDA / Windows	`idle` → `requesting`	Deny spoken with the dialog name	live region stealing the speech queue
Safari + VoiceOver / macOS	`requesting` + Escape	deny, then composer focus	Escape stopping the wrong abort owner
Firefox + keyboard only	`allowed` → remove chip	composer focus, chip gone	chip is a non-focusable span
Mobile Safari + VoiceOver	`failed` → retry	focus moves to Retry	focus lost to the browser chrome

Name the transition in the bug, not just the control, or the next patch will "fix" the toast color and leave the race.

Limitations, and who should not copy this

This gate is not a privacy program, a contract review, or a substitute for ignoring sensitive buffers in the editor. It will not help you if the model already lives in a privileged desktop process that can read files without the page. Do not use a modal consent pattern for every token; use it when scope changes, not when the caret moves inside the same hash.

Skip this approach when your agent never sends page context, when legal consent already happens before the editor loads, or when you are writing research strategy instead of a control. Also skip it if your "dialog" is a slide-over without aria-modal, because that pattern reintroduces the toast bug with extra CSS. A pretty overlay that you cannot tab into is still a silent fetch.

What I would check tomorrow morning

Does Deny receive focus before any network byte leaves the tab, including preflight?
Does Escape deny even while a generating label is visible behind the inert background?
Does Allow once die with the current selection hash, instead of surviving a file switch?
Does the live region announce one sentence per state, not one sentence per streamed token?
After deny, can you still submit the prompt with an empty context body and an enabled composer?

If any answer is no, you do not have a consent control that a keyboard user can operate. You have a toast that lost a race, and the model is already holding a buffer nobody agreed to share. I still catch myself wanting to just send the selection because the answer gets sharper, then I tab once with the mouse unplugged and leave the buffer where it belongs.

Hidden-Tab Streams Need a Visibility Abort, Not a Frozen Generating Label

babycat — Mon, 21 Sep 2026 12:16:29 +0000

I hid the chat tab to answer Slack, came back thirty seconds later, and the interface still said Generating. The Stop button looked pressed, the composer stayed disabled, and my screen reader repeated a status that was already dead. Had the remote stream finished, stalled, or silently aborted while the page sat frozen in the background? That stuck Stop control is the failure I want to walk through, from the first symptom to a typed recovery.

The frozen Stop I came back to

Browser agents are having a loud week, and too many demos assume the tab stays focused like a stage light. Mine did not stay focused, and the remote completion kept the React tree in streaming after the socket was already gone. I had been reading chunks from a remote endpoint, switched away for a short reply, and the Page Lifecycle freeze cut the network without notifying my state machine. When I returned, keyboard users could not reach the composer, because a dead Stop button still owned the only enabled tab stop.

The pointer story was ugly, but the keyboard story was worse, because Tab died on a disabled textarea. The remaining control called abort() on an AbortController that had already finished its useful life. VoiceOver kept saying “Generating,” which is a lie, not an announcement strategy. Why do we treat document.visibilityState as a performance footnote when it is a stream lifecycle event?

Here is the interaction I keep reproducing in a single-file demo.

Start a remote stream with focus in the composer, then Tab once so Stop is a real tab stop.
Hide the tab for about thirty seconds, or longer if the browser discards a frozen background page.
Return with the keyboard only, and notice that Stop still claims the stream is live.

Expected states should have been on the whiteboard before anyone reached for aria-live.

State table before any ARIA

State	Composer	Primary control	Live status	Focus origin
`idle`	enabled	none	none	composer
`connecting`	disabled	Cancel	Connecting to the model.	Cancel
`streaming`	disabled	Stop	Generating.	Stop
`hidden_aborted`	disabled	Retry banner	Generation stopped because the tab was hidden.	Retry
`failed`	disabled	Retry banner	Specific network or HTTP error.	Retry
`complete`	enabled	none	Response complete.	composer
`cancelled`	enabled	none	Generation cancelled.	composer

Notice that hidden_aborted is not failed and is not streaming either. Mixing those three phases is how you ship a Stop button that never unlocks for keyboard users. Also notice the focus origin is a real tab stop, not a polite live region pretending to be a button. Live regions announce a change; they do not receive Tab, Enter, or a screen-reader swipe.

Reproducing the death without a mock stream

A setTimeout token pump will not die when you hide the tab, which is why this bug survives unit tests. I needed a real remote completion so the browser could freeze the page, drop the connection, and leave my state machine behind. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I pointed the demo at MonkeyCode's free model access and free server option, because that gave me a remote stream I could cancel, stall, and lose without standing up my own inference box.

I am not going to quote quotas, model names, or uptime claims I cannot verify from a primary source in this draft. The only fact this reproduction needs is a free remote endpoint, so fetch plus AbortController fail the way production fails. If you already have another completion URL, paste it into the demo config instead. The visibility owner does not care who owns the socket, only that the socket can actually die.

The reproduction stays small on purpose: typed states, a composer, a transcript region, and a banner that becomes the next tab stop. There is no design-system chrome and no remount of the chat tree when status changes. Remounting is how you drop focus, and focus loss is the second bug hiding under the frozen label.

Root cause: generating outlived the network

I logged three timestamps while the tab was hidden: visibilitychange, the fetch abort or error, and the React phase that still said streaming. The first two timestamps moved. The third never moved, which is the whole incident in one sentence. My effect had subscribed to chunks and to user-initiated abort, but not to the page becoming hidden, and Chrome can freeze a background tab hard enough that your progress handler simply never runs again.

There is a second trap sitting next to that missing listener. Some browsers fire visibilitychange but keep the socket alive until a later freeze or a full discard. If you abort on the first hidden event, you might cancel a stream the user still wants after a one-second glance away. If you never abort, you lie for the entire Slack detour. The durable approach is to treat hidden as “make the UI honest immediately,” then abort only if the page is still hidden after a short, documented grace period.

I also found a privacy bug sitting under the lifecycle bug, and it was easier to miss. After I finally flipped the phase to an error, an effect retried the same prompt automatically as if recovery meant resend. That resend is a consent failure, not a convenience feature. The user hid the tab. They did not ask the product to ship the prompt a second time.

Debugging sequence I will keep reusing on the next stream owner:

Log document.visibilityState, document.wasDiscarded when it exists, and your stream enum on every transition.
Confirm Stop and the visibility owner cancel the same AbortController instance for this turn.
Prove no useEffect auto-retries on hidden_aborted; retry must be an explicit user action.
Check that the banner button sits in tab order before the disabled composer, not after it.

A typed visibility owner

Here is the state machine from the reproduction. Treat it as demo code, not production telemetry from a shipped app.

type StreamPhase =
  | "idle"
  | "connecting"
  | "streaming"
  | "hidden_aborted"
  | "failed"
  | "complete"
  | "cancelled";

type StreamState = {
  phase: StreamPhase;
  prompt: string;
  text: string;
  error: string | null;
  hiddenAt: number | null;
};

The owner is a small class so React is not the source of truth for abort. React renders the phase. The owner owns the socket.

const HIDDEN_GRACE_MS = 4000;

class VisibilityStreamOwner {
  private controller: AbortController | null = null;
  private graceTimer: number | null = null;

  constructor(
    private onPhase: (phase: StreamPhase, error?: string) => void,
    private onChunk: (chunk: string) => void
  ) {}

  start(url: string, prompt: string, token?: string) {
    this.cancelTimers();
    this.controller = new AbortController();
    this.onPhase("connecting");

    // Example fetch. Wire your own parser. This is not a vendor SDK.
    fetch(url, {
      method: "POST",
      signal: this.controller.signal,
      headers: {
        "Content-Type": "application/json",
        ...(token ? { Authorization: `Bearer ${token}` } : {}),
      },
      body: JSON.stringify({ prompt, stream: true }),
    })
      .then(async (response) => {
        if (!response.ok || !response.body) {
          this.onPhase("failed", `HTTP ${response.status}`);
          return;
        }
        this.onPhase("streaming");
        const reader = response.body.getReader();
        const decoder = new TextDecoder();
        while (true) {
          const { value, done } = await reader.read();
          if (done) break;
          if (this.controller?.signal.aborted) return;
          this.onChunk(decoder.decode(value, { stream: true }));
        }
        this.onPhase("complete");
      })
      .catch((error: unknown) => {
        if (this.controller?.signal.aborted) return;
        const message = error instanceof Error ? error.message : "Network failed";
        this.onPhase("failed", message);
      });
  }

  watchDocument() {
    document.addEventListener("visibilitychange", this.onVisibility);
  }

  unwatchDocument() {
    document.removeEventListener("visibilitychange", this.onVisibility);
    this.cancelTimers();
  }

  private onVisibility = () => {
    if (document.visibilityState !== "hidden") {
      this.cancelTimers();
      return;
    }
    // Honest UI first: the tab is gone, so Stop is already a lie.
    this.graceTimer = window.setTimeout(() => {
      if (document.visibilityState === "hidden") {
        this.controller?.abort();
        this.onPhase("hidden_aborted");
      }
    }, HIDDEN_GRACE_MS);
  };

  userCancel() {
    this.cancelTimers();
    this.controller?.abort();
    this.onPhase("cancelled");
  }

  private cancelTimers() {
    if (this.graceTimer !== null) window.clearTimeout(this.graceTimer);
    this.graceTimer = null;
  }
}

The grace period is a product choice, not a law, and it belongs in the banner copy. Four seconds was long enough for a misclick onto another tab, and short enough that a frozen Generating label did not survive a Slack detour. Tune the constant, then tell the same number in the UI, because mismatched copy is how QA files “sometimes it waits, sometimes it does not.”

[visible] idle -> connecting -> streaming -> complete
                 \-> cancelled (Stop / Escape)
                 \-> failed (HTTP / network)
[hidden > 4s]    streaming -> hidden_aborted -> (explicit Retry) connecting

Focus, announcements, and a retry that does not auto-fire

When the phase becomes hidden_aborted, render a banner that is a heading plus buttons, then move focus to Retry. Do not steal focus if the user is already elsewhere in your chrome, such as a history panel they opened before hiding the tab. The test is pointer-independent: hide the tab from the keyboard, return with Alt+Tab or Command+Tab, then Tab once into the banner.

function RecoveryBanner({
  phase,
  onRetry,
  onDismiss,
  bannerRef,
}: {
  phase: StreamPhase;
  onRetry: () => void;
  onDismiss: () => void;
  bannerRef: React.RefObject<HTMLButtonElement>;
}) {
  if (phase !== "hidden_aborted" && phase !== "failed") return null;

  const title =
    phase === "hidden_aborted"
      ? "Generation stopped because the tab was hidden"
      : "Generation failed";

  return (
    <div role="region" aria-labelledby="stream-recovery-title">
      <h2 id="stream-recovery-title">{title}</h2>
      <p>
        The remote stream ended while this page was in the background.
        Nothing was resent. Retry is a separate, explicit action.
      </p>
      <button ref={bannerRef} type="button" onClick={onRetry}>
        Retry this prompt
      </button>
      <button type="button" onClick={onDismiss}>
        Dismiss and edit
      </button>
    </div>
  );
}

Pair that region with a status node that is aria-live="polite" and aria-atomic="true", and only update it when the phase changes, not on every token. Token-level live regions are how you backlog a screen reader, which is a different incident than this freeze. This demo announces transitions only. The banner remains the operable control. The live region is the rumor mill, not the steering wheel.

Composer rules for the hidden-abort phase are boring on purpose, and boring is what keeps focus stable.

Keep the textarea in the DOM, disabled, so the layout does not jump and drop a virtual cursor.
Do not remount the transcript. In-place text is fine; a new tree is how focus evaporates.
Retry copies the last prompt into an explicit confirmation, then starts a new AbortController. Never reuse the aborted one.
Escape still cancels while connecting or streaming, but after hidden_aborted Escape should land on Dismiss, not on a zombie Stop.

Environment-specific QA matrix

Please run the exact hidden transition, not a mocked visibilityState in JSDOM. JSDOM will not freeze your fetch, and that is the entire point of this bug.

Environment	Assistive tech	Transition	What must happen
Chrome current / macOS	VoiceOver	Hide for 4+ seconds, return	Announces stopped-because-hidden; focus on Retry
Firefox current / Windows	NVDA	Same hide-and-return	Stop is gone; composer is not auto-focused if Retry exists
Safari current / iOS	VoiceOver	Switch apps, return	Banner is a heading in the rotor; Retry is a button
Chrome current / Android	TalkBack	Recents, return	No auto resend; swipe hits Retry before the composer

If Retry is missing from the rotor or from tab order, you shipped a tooltip, not a recovery. If the Generating label survives the return, your owner never left streaming. If the prompt fires again without a click or Enter on Retry, you shipped a privacy incident with extra tokens on the bill.

I want the matrix filled with versions, not vibes. Send the browser, OS, and assistive-technology versions plus the exact hide-and-return transition that failed. Did the page freeze, discard, or merely blur? Those three are not the same lifecycle event, and they do not deserve the same banner copy.

What this will not save you from

This pattern will not keep generating while the tab is discarded by the browser. If you need a job to finish in the background, you need a server-side run and a notification, not a hidden fetch that you hope will survive. It will not fix model stalls that happen while the tab is visible; that is a different timer and a different control. It will not make an inaccessible composer suddenly keyboard-operable, and it will not replace consent copy either. If your product sends prompts to a remote server, say that before the first request, not after a freeze.

Skip this approach when you are building a native shell that already owns lifecycle events, or a local-only model with no network to drop. Skip it when the agent must keep running in a worker with explicit background-sync consent from the user. And please skip any conformance badge in the README, because this is a recovery mechanism, not a certificate.

I still want the interface to remain keyboard-operable through loading, error, cancellation, and this newly honest hidden death. If the Generating label outlives the socket, the Stop button is not a control anymore. It is a locked door with a green light.

Test Streaming Markdown for Transient Headings and Half-Written Links

babycat — Sun, 20 Sep 2026 10:29:05 +0000

This write-up reconstructs a debugging session against a single-file chat transcript, not a production incident with traffic numbers. I had NVDA running beside a streaming answer when the voice said heading level two, To. The model was still generating Token budgets, and my renderer had already promoted that first word into a real heading. Have you ever tabbed onto a link whose href was still https://api. and then followed it into a dead tab?

That is the failure this article fixes, and it shows up whenever markdown is parsed on every token. Visual users see a heading jump, then collapse, then jump again as characters arrive. Keyboard users get a tab stop that should not exist yet, and screen reader users hear structure that the author has not committed. I want a renderer that keeps incomplete syntax in a draft block until the block is actually closed.

The interaction that actually broke

I was checking a transcript the way a keyboard user would, not the way a mouse user would. The final screenshot looked fine, because the finished markdown was valid, pretty, and fully linked. The problem lived in the transitions, which is where assistive technology spends most of its time. If you only audit the completed answer, you will ship a stream that shouts fake structure for several seconds.

Here is the sequence I could reproduce on every slow stream:

The model emitted # then a space, and the DOM grew an empty heading.
NVDA announced heading level one, with no accessible name worth hearing.
Later tokens filled in Retry UX, so the heading name changed under the reading cursor.
A later chunk opened [guide](https://examp and a focusable link appeared with a truncated URL.
I pressed Tab from the composer, landed on that link, and activated a navigation that 404ed.

Does your streaming preview run markdown(buffer) on each onmessage? Then you already own this class of bug, even if the happy path looks polished.

State table before any ARIA

I put the states on one card before touching attributes, because attributes cannot rescue a wrong tree. If a state cannot explain what Tab does, it is not finished work.

State	Buffer shape	DOM	Screen reader	Keyboard
`idle`	empty	no article body	silent	only the composer
`streamingDraft`	open block	plain text draft, `aria-busy="true"`	polite "still writing" once	draft contains no links or headings
`blockCommitted`	closed block	real heading, list, or link	announce the new block once	committed links enter tab order
`streamFailed`	frozen buffer	draft plus error status	assertive error	focus moves to Retry
`complete`	full document	parsed markdown	"answer complete"	normal reading order

I kept streamingDraft from minting headings on purpose, even when the draft started with a hash character. A hash is a character until a blank line, a closing fence, or the stream itself says the block is done. Why should # To become a landmark before the model has finished the title?

Debugging technique: freeze the chunk, not the screenshot

Happy-path screenshots lie, because they capture the committed document after the ugly transitions have vanished. I needed the in-flight buffer, the live DOM, and the utterance log at the same timestamp. The reusable part is not markdown lore. It is a loop you can run on any streaming widget.

Dump headings after every token

After each chunk I printed every heading and link, then compared the dump with the previous one. The smoking gun was a heading whose textContent changed five times without leaving the accessibility tree. A link node appeared at one chunk with href="https://examp" and only later became a real URL.

// Proposed probe: paste into DevTools while a stream is running.
window.__mdProbe = setInterval(() => {
  const nodes = [...document.querySelectorAll("h1,h2,h3,a[href]")];
  console.table(nodes.map((el) => ({
    tag: el.tagName,
    text: (el.textContent || "").slice(0, 48),
    href: el.getAttribute("href"),
    tabIndex: el.tabIndex
  })));
}, 200);

Replay at rude cadences

Local setInterval pumps often emit whole words, which hides the bug. I replayed the same recorded chunks at 50ms, 400ms, and a "wait three seconds then flush" cadence. Mid-token splits are the interesting case, because that is where parsers invent structure. Record the raw chunk list, including delays, instead of concatenating immediately in the view.

Reusable steps I will keep using on other streaming widgets:

Record the raw chunk list, including delays, instead of concatenating in the view.
Replay those chunks at fast, slow, and stall-then-flush cadences.
After every chunk, dump headings and links and diff them against the previous dump.
Tab from the composer after each dump, and note whether focus landed inside the transcript.
Repeat with the screen reader running, and write down the exact utterance after each chunk.

Root cause: a full parser on an incomplete buffer

The renderer looked innocent. It stored tokens in a string and re-parsed the whole string on every chunk. That is a document parser being asked to parse a sentence that is still being typed.

// Broken: proposed anti-pattern, do not ship this.
function renderBroken(buffer) {
  article.innerHTML = markdownToHtml(buffer);
}

Markdown parsers are document parsers. They will treat # To as a heading because that is valid CommonMark so far. They may treat [n](http://x as a link if the implementation is hungry, or as odd text if it is strict, and you cannot QA both with a final snapshot. InnerHTML replacement also destroys any reading cursor that was inside the article, which is a second bug stacked on the first.

I did not need a new ARIA pattern here. I needed to stop emitting semantic HTML for syntax the model had not closed. Copy buttons, citation chips, and source links make it worse when they mount on that half-written HTML, because they add extra tab stops to a moving target.

The fix: commit closed blocks, keep a non-semantic draft

Think of the stream as a conveyor, not as a document. Closed blocks fall off the conveyor into real HTML. The open tail stays in a paragraph or preformatted node that is not a heading, not a list, and not a link. Keyboard users should not be able to tab into a URL the model is still spelling.

/**
 * Proposed splitter for a demo transcript, not a CommonMark implementation.
 * Commit when we see a blank line, a closed fence, or stream completion.
 */
function splitCommitted(buffer, streamOpen) {
  const fence = (buffer.match(/```
{% endraw %}
/g) || []).length;
  const insideFence = fence % 2 === 1;
  if (insideFence && streamOpen) {
    const lastOpen = buffer.lastIndexOf("
{% raw %}
```");
    return {
      committed: buffer.slice(0, lastOpen),
      draft: buffer.slice(lastOpen)
    };
  }

  const parts = buffer.split(/\n{2,}/);
  if (streamOpen && !buffer.endsWith("\n\n")) {
    const draft = parts.pop() ?? "";
    return { committed: parts.join("\n\n"), draft };
  }

  return { committed: buffer, draft: "" };
}

The view then has two regions with different contracts. Committed HTML may contain headings and links. Draft text must remain characters.

<article aria-labelledby="answer-label">
  <h2 id="answer-label">Assistant answer</h2>
  <div data-committed></div>
  <p data-draft aria-busy="true"></p>
  <p class="sr-only" data-live aria-live="polite" aria-atomic="true"></p>
</article>

Rules I encoded in the renderer, then tested by Tab and by utterance:

Parse markdown only for committed, never for draft.
Render draft with textContent, so hashes and brackets stay characters.
Keep aria-busy="true" on the draft while the stream is open, then remove it.
Announce a block once on commit, through a polite live region, not per token.
Do not put aria-live on the committed markdown itself, or you will queue every list item.
On streamFailed, freeze both regions, expose an assertive error, and move focus to Retry.
Mount copy buttons and citation chips only on committed blocks.

Expected UI states

I wrote the visual and non-visual states as a checklist, because a screenshot cannot show Tab order. Walk these states with the keyboard before you argue about typography.

Idle: transcript empty, composer focused, no busy state, no live text.
First tokens: draft paragraph shows characters, no heading in the accessibility tree, Tab skips the draft.
Blank line arrives: last draft promotes into committed HTML, live region speaks once, draft starts the next tail.
Fenced code: the opening fence stays in draft until the closing fence, so a copy button cannot appear on a half pre.
Failure: draft remains readable text, Retry is the next tab stop after the error, composer is not silently cleared.
Complete: draft node empty or removed, aria-busy gone, "Answer complete" announced once.

If a citation chip appears during streamingDraft, keyboard users will activate a control whose target is still being invented. That is the same family of failure as the half-written link, just wearing a prettier costume.

A slow stream is the test fixture, not a luxury

Local token pumps hide this bug, because they often emit whole words or whole lines. Real model streams split in the middle of ##, in the middle of a URL, and in the middle of a fence. You want a network that is a little rude, so your splitter is forced to hold an open tail.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project that currently offers free model access and a free server option, which is relevant here only as a remote chunk source with uneven cadence. Point the demo stream URL at that free server when you want delays and split tokens you did not hand-author, then rerun the heading dump after every chunk.

I am not attaching model names, quotas, hardware, or uptime claims, because those change and I cannot freeze them in a blog post. The workflow is the point: replay real chunks, dump headings and links after each chunk, and refuse to parse the open tail. If you already buffer markdown until the stream completes, you do not need a free remote server for this particular bug.

Minimal reproduction

The proposed demo below is a single-file page. It is labeled proposed because I am not publishing a lab audit with assistive-technology certificates. Serve it from any static directory, then toggle USE_BROKEN to watch the heading tree appear too early.

npx --yes serve .

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Committed-block streaming markdown</title>
  <style>
    :root { font-family: system-ui, sans-serif; max-width: 42rem; }
    [data-draft] { opacity: 0.82; white-space: pre-wrap; }
    .sr-only {
      position: absolute; width: 1px; height: 1px; overflow: hidden;
      clip: rect(0 0 0 0);
    }
    .error { color: #8b1e1e; }
    button:focus, textarea:focus { outline: 3px solid #222; outline-offset: 2px; }
  </style>
</head>
<body>
  <h1>Streaming markdown transcript</h1>
  <form id="composer">
    <label for="prompt">Prompt</label>
    <textarea id="prompt" rows="2">Explain retry UX.</textarea>
    <button type="submit">Send</button>
    <button type="button" id="cancel" hidden>Cancel</button>
  </form>
  <p id="status" role="status"></p>
  <article aria-labelledby="answer-label">
    <h2 id="answer-label">Assistant answer</h2>
    <div id="committed"></div>
    <p id="draft" data-draft hidden></p>
    <p id="live" class="sr-only" aria-live="polite" aria-atomic="true"></p>
  </article>
  <p id="fail" class="error" hidden tabindex="-1"></p>
  <button id="retry" type="button" hidden>Retry last prompt</button>
  <script>
    const USE_BROKEN = false; // true = parse the whole buffer on every token
    const $ = (id) => document.getElementById(id);
    let abortOwner = null;
    let lastPrompt = "";

    function splitCommitted(buffer, streamOpen) {
      const fence = (buffer.match(/```
{% endraw %}
/g) || []).length;
      if (fence % 2 === 1 && streamOpen) {
        const lastOpen = buffer.lastIndexOf("
{% raw %}
```");
        return { committed: buffer.slice(0, lastOpen), draft: buffer.slice(lastOpen) };
      }
      const parts = buffer.split(/\n{2,}/);
      if (streamOpen && !buffer.endsWith("\n\n")) {
        const draft = parts.pop() ?? "";
        return { committed: parts.join("\n\n"), draft };
      }
      return { committed: buffer, draft: "" };
    }

    function escapeHtml(s) {
      return s.replace(/[&<>"']/g, (c) => ({
        "&": "&amp;", "<": "&lt;", ">": "&gt;",
        '"': "&quot;", "'": "&#39;"
      }[c]));
    }

    function committedToHtml(md) {
      return escapeHtml(md)
        .replace(/^## (.+)$/gm, "<h3>$1</h3>")
        .replace(/^# (.+)$/gm, "<h3>$1</h3>")
        .replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '<a href="$2">$1</a>')
        .replace(/\n\n/g, "</p><p>")
        .replace(/^/, "<p>")
        .replace(/$/, "</p>");
    }

    function render(buffer, streamOpen) {
      if (USE_BROKEN) {
        $("committed").innerHTML = committedToHtml(buffer);
        $("draft").hidden = true;
        return;
      }
      const { committed, draft } = splitCommitted(buffer, streamOpen);
      $("committed").innerHTML = committed ? committedToHtml(committed) : "";
      $("draft").hidden = !draft;
      $("draft").textContent = draft;
      $("draft").setAttribute("aria-busy", streamOpen ? "true" : "false");
    }

    async function* fakeSlowStream(signal) {
      const text =
        "## Retry UX\n\nUse a recoverable error, not a disabled composer.\n\n" +
        "Read the [guide](https://example.com/retry).\n\nDone.";
      let buffer = "";
      for (const ch of text) {
        if (signal.aborted) throw new DOMException("Aborted", "AbortError");
        buffer += ch;
        await new Promise((r) => setTimeout(r, 40));
        yield buffer;
      }
    }

    async function runStream(prompt) {
      lastPrompt = prompt;
      const controller = new AbortController();
      abortOwner = controller;
      $("cancel").hidden = false;
      $("retry").hidden = true;
      $("fail").hidden = true;
      $("status").textContent = "Streaming";
      $("live").textContent = "Answer streaming";
      let lastCommitted = "";
      let buffer = "";
      try {
        // Swap fakeSlowStream for fetch(STREAM_URL) when you have a remote free server.
        for await (buffer of fakeSlowStream(controller.signal)) {
          render(buffer, true);
          const { committed } = splitCommitted(buffer, true);
          if (!USE_BROKEN && committed && committed !== lastCommitted) {
            $("live").textContent = "New block committed";
            lastCommitted = committed;
          }
        }
        render(buffer, false);
        $("status").textContent = "Complete";
        $("live").textContent = "Answer complete";
        $("draft").removeAttribute("aria-busy");
      } catch (err) {
        if (err.name === "AbortError") {
          $("status").textContent = "Cancelled";
          $("live").textContent = "Generation cancelled";
        } else {
          $("fail").hidden = false;
          $("fail").textContent = "The answer stopped before the last block committed. Retry is available.";
          $("fail").focus();
          $("retry").hidden = false;
        }
      } finally {
        $("cancel").hidden = true;
        abortOwner = null;
      }
    }

    $("composer").addEventListener("submit", (e) => {
      e.preventDefault();
      runStream($("prompt").value);
    });
    $("cancel").addEventListener("click", () => abortOwner?.abort());
    $("retry").addEventListener("click", () => runStream(lastPrompt));
  </script>
</body>
</html>

The tiny committedToHtml helper is a demo subset, not a sanitizer and not a markdown library. Treat any HTML built from model text as untrusted, even after you escape, if you later expand the subset. I kept headings as h3 under the labeled article so the page outline does not grow fake h1 nodes during a commit.

Proposed QA matrix

I did not run a certified assistive-technology lab for this post, so the matrix is a proposed checklist rather than a result table. Fill the last column with pass or fail only after you hear the utterance yourself.

Environment	Assistive tech	Transition to fail on purpose	Pass if
Windows, Chrome current	NVDA current	first `#` character arrives	no heading announcement until the title block commits
Windows, Firefox current	NVDA current	truncated `https://examp` in an open link	Tab from composer does not land on that URL
macOS, Safari current	VoiceOver current	innerHTML replacement of committed region	reading cursor is not thrown to the top of the page
iOS, Safari current	VoiceOver current	stream error after a half fence	Retry takes focus, draft stays readable text
Keyboard only, any desktop	none	copy button or citation chip	those controls exist only after the block commits

Invite yourself to be unkind. The interesting transition is not "answer complete." It is the first hash, the first open parenthesis of a URL, and the first backtick run that has no closing fence yet.

Limitations, and who should skip this

This splitter is a teaching artifact. It does not implement CommonMark, GFM tables, setext headings, indented code, or nested fences inside fences. It will mis-commit if a model streams one huge paragraph with no blank lines, because the open tail stays draft until completion. That is safer than inventing headings, but it is not a full streaming markdown engine.

Who should not use this approach:

Teams that only ever render plain text transcripts, because there is no heading tree to invent.
UIs that already buffer the full answer and parse once, because they already avoided this bug.
Anyone who needs a certified markdown implementation, because this subset will lie on edge cases.
Voice-only agents, because barge-in and speech cancellation are a different state machine.
Production apps that would treat this snippet as a sanitizer, because it is not one.

The free remote stream is also optional. If your recorded chunks already split inside headings and URLs, you can replay them from a fixture file and skip the network. I would rather have a mean fixture than a pretty live demo that always emits whole lines.

What I want you to reproduce

If you try the page, do not send me a screenshot of the finished answer. Send the browser, OS, and assistive-technology versions, plus the exact chunk where a heading or link appeared too early. Did Tab leave the composer before a blank line arrived? Did the live region stay quiet until a block actually committed?

Streaming markdown is not a visual polish problem. It is a state machine that must refuse to publish structure the model has not finished saying.

An Empty Model Handshake Needs a Recoverable Error, Not a Disabled Composer

babycat — Sat, 19 Sep 2026 08:47:13 +0000

I tabbed to Send, hit Enter, and watched the composer go grey like a locked door. The status pulse kept moving, yet nothing useful was spoken, which is how you know the interface has already decided you do not matter. Was the free server asleep, or did the browser swallow an empty 200 as a finished reply? This walkthrough is a constructed reproduction on a tiny harness, not a production war story with fake metrics.

I had wired one chat surface to two backends so I could watch failures change costume. One path was remote free-model access; the other was a free server I could restart between runs. The pointer path looked almost fine: a spinner, a blank bubble, then I clicked the field and typed again. The keyboard path was a different product, and that gap is the whole article.

The failure, without the happy path

After Enter, focus vanished into a textarea that had become disabled. Tab skipped Retry because Retry was not in the tree until error became truthy. The live region stayed quiet because we only announced token deltas, never handshake outcomes. Does that sound like a flaky network? It presented as one. It was a state-machine bug wearing a network costume, and booleans made it easy to ship.

I ignored my own state table until the composer stopped accepting Tab. Do not do that. Put the table above the CSS, then actually follow it when the first byte never arrives.

Expected UI states

State	Composer	Primary control	Status text	Live region	Focus owner
`idle`	enabled	Send	Ready	polite	composer
`handshaking`	readonly	Cancel	Connecting	polite	status or Cancel
`streaming`	readonly	Cancel	Receiving	polite, throttled	Cancel or composer
`empty`	enabled	Send	No content returned	assertive	composer
`timeout`	enabled	Retry	Connection never started	assertive	Retry
`http_error`	enabled	Retry	Visible status code	assertive	Retry

The bug lived between handshaking and streaming. An empty, successful body never became empty. A missing done event never became timeout. finally did not save us, because the reader loop ended “cleanly” with zero frames.

Debugging order I now refuse to skip

If you only steal one thing, steal the order. Tools are optional; sequence is not.

Reproduce with keyboard only, then with a screen reader, and never with the pointer first.
Snapshot the accessibility tree the moment Send is pressed, not after you get bored.
Log every phase transition with timestamps, including the ones you are sure are impossible.
Inspect the network row: status, content-type, time to first byte, and whether any data: frame arrived.
Ask whether disabled on the composer or a wrapping fieldset is removing Tab stops.

Keyboard reproduction

I put the mouse out of reach, which is theatrical and strangely effective for frontend work. Tab to the composer, type a short prompt, Tab to Send, press Enter. Composer locks. Tab again. Focus jumps to a skip link because Retry is hidden until we feel ready to admit failure. Why do we hide recovery until the object model is embarrassed? Because we modeled only streaming success.

Turn on a screen reader and repeat the same transition without peeking at the spinner. If the rotor finds an old heading inside a prior assistant bubble, your status node is decorative. Have you ever trusted a pulse animation as if it were an announcement? Sighted teams do this constantly, then call the result “simple.”

Network truth versus UI truth

One run returned 200 with Content-Type: text/event-stream, a comment preamble, and then a close. No data: frame. No event: done. fetch resolved. The read() loop exited. We set streaming = false without assistant text, and left aria-busy="true" because busy meant !text && !error. Empty text plus no error is the lie.

A second run died earlier: the preflight never finished, fetch rejected, and catch stored nothing. The latch stayed true. Two endpoints, two costumes, one boolean that could not name silence. If your mock always emits a token, you will never see this. Break the first byte on purpose.

# Proposed checks against a local harness, not a claimed production capture.
curl -i -N "$ENDPOINT" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"prompt":"ping"}'

Look at three boring facts before you touch ARIA. Did the socket open? Did a frame arrive? Did the UI name that outcome? If you cannot answer from logs, you are decorating a spinner.

Root cause

The composer used a boolean latch instead of a typed phase. Booleans cannot represent “handshake started but no first token.” They also cannot represent “HTTP success with zero events.” Search your tree for this shape before you blame the model.

// Broken: two booleans cannot name an empty handshake.
let streaming = false;
let error: string | null = null;

async function send(prompt: string) {
  streaming = true;
  error = null;
  const res = await fetch(endpoint, {
    method: "POST",
    body: JSON.stringify({ prompt }),
    signal,
  });
  if (!res.ok) throw new Error(String(res.status));
  const reader = res.body!.getReader();
  const decoder = new TextDecoder();
  // A clean close with no frames still looks like success here.
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    append(decoder.decode(value, { stream: true }));
  }
  streaming = false;
}

When streaming is true, the textarea gets disabled. Disabled form controls leave the tab order in common desktop browsers. Retry renders only when error is truthy. Empty success sets neither flag. Where does focus go after Send? Anywhere except the control the person just used.

The fix: name the handshake

I replaced the booleans with a discriminated union and a timer that owns the first byte, not the full generation. This is not a stall detector for tokens that pause mid-sentence; that clock is a different bug. This timer only answers whether a handshake produced a stream event, an HTTP error, or silence.

type ChatPhase =
  | { kind: "idle" }
  | { kind: "handshaking"; startedAt: number }
  | { kind: "streaming"; receivedBytes: number }
  | { kind: "empty" }
  | { kind: "timeout" }
  | { kind: "error"; message: string; status?: number };

type PhaseEvent =
  | { type: "send" }
  | { type: "first-byte"; bytes: number }
  | { type: "end" }
  | { type: "tick"; now: number }
  | { type: "fail"; message: string; status?: number }
  | { type: "retry" };

const HANDSHAKE_MS = 8000; // demo default, measure your own endpoint

function reduce(phase: ChatPhase, event: PhaseEvent): ChatPhase {
  switch (event.type) {
    case "send":
    case "retry":
      return { kind: "handshaking", startedAt: Date.now() };
    case "first-byte":
      return { kind: "streaming", receivedBytes: event.bytes };
    case "end":
      if (phase.kind === "streaming" && phase.receivedBytes > 0) return { kind: "idle" };
      return { kind: "empty" };
    case "tick":
      if (
        phase.kind === "handshaking" &&
        event.now - phase.startedAt > HANDSHAKE_MS
      ) {
        return { kind: "timeout" };
      }
      return phase;
    case "fail":
      return { kind: "error", message: event.message, status: event.status };
    default:
      return phase;
  }
}

What the DOM must do when the first byte never comes

handshaking: composer is readonly, never disabled; Send becomes Cancel; status text exists for assistive tech.
empty: assertive “The endpoint returned no content.”; focus returns to the composer; Retry sits next to Send.
timeout: abort the fetch you still own; announce that the connection never started; move focus to Retry.
http_error: put the status code in visible text, not only in DevTools.

Readonly still participates in tab order. Disabled does not. That attribute choice is the difference between recovery and a spinner that ate your keyboard. Escape should cancel only while handshaking or streaming. After timeout, Escape must not poke a dead AbortController.

<form id="chat">
  <p id="status" role="status" aria-live="polite" aria-atomic="true">Ready.</p>
  <label for="composer">Message</label>
  <textarea id="composer" rows="3"></textarea>
  <div class="actions">
    <button type="submit" id="primary">Send</button>
    <button type="button" id="retry" hidden>Retry last message</button>
  </div>
</form>

function render(phase: ChatPhase) {
  const composer = document.querySelector<HTMLTextAreaElement>("#composer")!;
  const primary = document.querySelector<HTMLButtonElement>("#primary")!;
  const retry = document.querySelector<HTMLButtonElement>("#retry")!;
  const status = document.querySelector("#status")!;

  const busy = phase.kind === "handshaking" || phase.kind === "streaming";
  composer.readOnly = busy;
  composer.removeAttribute("disabled");

  const recoverable =
    phase.kind === "timeout" || phase.kind === "error" || phase.kind === "empty";
  retry.hidden = !recoverable;
  status.setAttribute("aria-live", recoverable ? "assertive" : "polite");

  if (phase.kind === "handshaking") {
    status.textContent = "Connecting to the model endpoint.";
    primary.textContent = "Cancel";
  } else if (phase.kind === "empty") {
    status.textContent = "The endpoint returned no content. You can retry or edit.";
    primary.textContent = "Send";
    composer.focus();
  } else if (phase.kind === "timeout") {
    status.textContent = "The connection never started. Retry is available.";
    retry.focus();
  } else if (phase.kind === "error") {
    status.textContent = phase.status
      ? `Request failed with ${phase.status}. Retry is available.`
      : `Request failed. ${phase.message}`;
    retry.focus();
  }
}

Have you logged whether Retry starts a second fetch before the first abort settles? Do that once. Duplicate owners produce two bubbles and a live region that cannot decide which failure to read.

Why two real endpoints made the bug honest

Mocks rarely close a stream in the ugly way a quiet gateway does, so I wanted disposable targets I could break on purpose. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I pointed the harness at MonkeyCode’s free model access and its free server option, then compared an empty preamble with a connection that never left handshake. The product is not the fix. The phase table is the fix. The endpoints only made silence reproducible without inventing a fake gateway or a quota story.

If you already have a server you can crash, use that and keep the same table. The open-source repo is optional scaffolding, not a requirement for the accessibility behavior.

Proposed QA matrix

Treat this as a checklist for the demo, not a conformance certificate. I am not claiming WCAG, and a blog post should not either.

You record	Transition	Must observe
Browser, OS, screen reader versions	`idle` → `handshaking` → `empty`	assertive empty message, composer focused, Send enabled
Same, keyboard only	`idle` → `handshaking` → `timeout`	Retry focused, readonly lifted, Escape unbound
Same, throttled network	`http_error`	visible status code, Retry before footer in tab order
Pointer and keyboard	double activate Send	one request, one abort owner

Dump document.activeElement on every phase change. If it is body after Send, you already lost the plot. Record the exact transition that failed, not a vibe that “chat felt broken.”

Limitations, and who should skip this

This pattern does not diagnose token stalls after the first byte; those need a different clock and a different announcement policy. It does not replace authentication, rate-limit copy, or content filtering. Eight seconds is a demo handshake budget, not a service promise, and you should measure your own endpoints before copying the constant.

Skip this approach if your composer is contenteditable with custom Tab stops you cannot inventory. Skip it if you cannot abort the fetch you started. Skip it if you still dump every token into a live region, because that backlog will bury the empty-success message. Skip the “just disable the form” shortcut, which is how this whole mess presented as a spinner.

What I want you to reproduce

Clone the state table, not the styling. Break the server so it returns an empty stream, then tab through Send without a mouse. If focus dies, your booleans are lying. If nothing is announced, your status node is decoration. If Retry appears only after a hover, you shipped mouse-only recovery and called it shipping.

I still catch myself trusting a pulse that never learned to speak. Do you?

Build an Accessible Waiting-for-Tokens Control With Stall Recovery

babycat — Fri, 18 Sep 2026 06:51:02 +0000

I tabbed into a tiny chat composer, typed one short prompt, and pressed Enter the way a keyboard-only user actually would. Three bouncing dots slid in under my message and looked extremely sure of themselves. Nothing spoke. I sat there for a long beat, still parked on a control that had just vanished, wondering whether the request had even left the browser. Have you ever watched a typing indicator and felt the whole interface go mute?

That mute stretch is the first-token gap. It shows up the moment a chat pane talks to a real remote server instead of a mocked stream that starts instantly.

The failure I was actually debugging

I was not chasing model quality, prompt style, or a cleverer system message. I was chasing a product failure that only existed after submit. The visual story said we were generating something useful. The accessibility story said absolutely nothing, and then a whole paragraph arrived at once. By then my focus had wandered into the browser chrome because the send button had unmounted. Does that sound like a streaming demo you have shipped on a happy path?

Here is the state table I should have drawn before I ever animated bouncing dots.

Phase	Visual	Focus	Live region
`idle`	Composer enabled, Send available	Composer	Silent
`waiting`	Status plus elapsed seconds, Stop available	Stay on Stop	Throttled “Waiting for the first token, N seconds”
`streaming`	Tokens append in place	Stop stays tabbable	One “Response started”, never per token
`stalled`	Recovery banner with Retry and Cancel	Move to Retry	“No tokens after N seconds. Retry available.”
`error`	Error text plus Retry	Retry	The error, once
`complete`	Composer enabled again	Restore composer	“Response complete”

If your machine only knows idle, streaming, and error, you are missing the state keyboard and screen-reader users actually get stuck in. Empty streaming is not streaming. It is a wait with no owner.

Symptom: the dots lied

I reproduced it with a single-file pane and a handler that slept before the first data: line. That delay is what a cold remote process feels like in the browser. The dots kept bouncing, so pointer users had motion to stare at. I had no motion in the accessibility tree.

What I observed, in order:

A decorative typing indicator with no accessible name and no status text
A Send button that disabled and then disappeared, so Tab lost its origin
No elapsed time, so a two-second think looked identical to a dead socket
A live region that stayed empty until tokens arrived, then spoke a novel

I kept asking one rude question out loud: is this loading, stalled, or broken? The UI refused to answer. That refusal is the bug, not the model.

Hypotheses I wrote down before touching CSS

I write hypotheses first because it stops me from “fixing” the spinner color. Debugging pixels is comforting. Debugging ownership is slower and usually correct.

The request never fired, and the composer submit handler was the real villain.
The request fired, but the first byte was slow because the remote process was cold.
Tokens arrived, but a remount made the live region miss the opening chunk.
The live region updated on every token and the speech queue fell behind.
Focus escaped to document.body when Send unmounted during the wait.

Number four is a real class of bugs, and I have chased it on other panes. This time it was not the backlog. Number two and number five were the actual faults. The dots were a costume over a missing waiting phase.

Root cause: no owner for “nothing has streamed yet”

Most streaming tutorials start at token zero as if the socket is already warm. Remote servers are often cold, especially when you are not paying for a dedicated box. The browser sits in waiting with zero tokens, and that is a real state. It has duration. It needs a cancel action. It needs a stall timeout that does not pretend to be a design flourish.

I had treated waiting as streaming with an empty string. Empty streaming looks identical to a hung fetch if you cannot see animation. Screen readers cannot see animation. Pointer users can at least glare at motion and wait. Keyboard users get a disabled control, silence, and a growing sense that the tab is dead. Why do we keep shipping that and calling it a chat UI?

The Send button also unmounted the moment the request started. That is how focus fell into the chrome. A Stop control that never receives focus is not a Stop control. It is a poster.

The typed states I should have started with

Treat the following as a reproduction, not a production SDK. I am showing the machine I used to debug the silent gap, including the stall threshold I picked for the harness.

type ChatPhase =
  | { status: "idle" }
  | { status: "waiting"; startedAt: number; elapsedMs: number }
  | { status: "streaming"; startedAt: number; text: string }
  | { status: "stalled"; elapsedMs: number; reason: "first-token-timeout" }
  | { status: "error"; message: string; recoverable: true }
  | { status: "complete"; text: string };

const FIRST_TOKEN_STALL_MS = 12_000;
const ANNOUNCE_EVERY_MS = 4_000;

Twelve seconds is a product choice, not a law of physics. Four seconds between wait announcements is also a choice, and it exists so you do not rebuild a live-region backlog. If you announce every tick, you will recreate a different failure and call it progress.

A runnable wait-state harness

This single file is enough to feel the bug and the fix. Serve it locally. Make the mock stream sleep before the first byte. Then tab through it with a screen reader and with the keyboard only.

<!doctype html>
<meta charset="utf-8" />
<title>Waiting-for-tokens harness</title>
<style>
  :root { font: 16px/1.45 system-ui, sans-serif; }
  #status { margin: 0.75rem 0; }
  #log { min-height: 4rem; white-space: pre-wrap; }
  [hidden] { display: none !important; }
  button:focus, textarea:focus { outline: 3px solid #222; }
</style>
<div>
  <label for="prompt">Prompt</label>
  <textarea id="prompt" rows="3">Explain focus restoration after submit.</textarea>
  <p>
    <button type="button" id="send">Send</button>
    <button type="button" id="stop" hidden>Stop</button>
    <button type="button" id="retry" hidden>Retry</button>
  </p>
  <p id="status" aria-live="polite" aria-atomic="true">Idle. Composer ready.</p>
  <div id="log" role="article" aria-label="Assistant draft"></div>
</div>
<script>
  const FIRST_TOKEN_STALL_MS = 12000;
  const ANNOUNCE_EVERY_MS = 4000;
  const els = {
    prompt: document.getElementById("prompt"),
    send: document.getElementById("send"),
    stop: document.getElementById("stop"),
    retry: document.getElementById("retry"),
    status: document.getElementById("status"),
    log: document.getElementById("log"),
  };

  let phase = { status: "idle" };
  let abort = null;
  let tick = null;
  let lastAnnounce = 0;

  function setPhase(next) {
    phase = next;
    const waiting = next.status === "waiting";
    const busy = waiting || next.status === "streaming";
    els.send.hidden = busy;
    els.stop.hidden = !busy;
    els.retry.hidden = next.status !== "stalled" && next.status !== "error";
    els.prompt.disabled = busy;
    if (next.status === "waiting") {
      const seconds = Math.floor(next.elapsedMs / 1000);
      maybeAnnounce(`Waiting for the first token, ${seconds} seconds.`);
    } else if (next.status === "streaming" && next.text.length === 0) {
      announce("Response started.");
    } else if (next.status === "stalled") {
      announce(`No tokens after ${Math.floor(next.elapsedMs / 1000)} seconds. Retry available.`);
      els.retry.focus();
    } else if (next.status === "error") {
      announce(next.message);
      els.retry.focus();
    } else if (next.status === "complete") {
      announce("Response complete.");
      els.prompt.focus();
    }
  }

  function announce(text) {
    els.status.textContent = text;
    lastAnnounce = Date.now();
  }
  function maybeAnnounce(text) {
    if (Date.now() - lastAnnounce >= ANNOUNCE_EVERY_MS) announce(text);
    else els.status.textContent = text; // visual elapsed time without extra speech
  }

  async function mockStream(signal) {
    // Local delay stands in for a cold remote first byte.
    await new Promise((resolve, reject) => {
      const id = setTimeout(resolve, 5000);
      signal.addEventListener("abort", () => {
        clearTimeout(id);
        reject(new DOMException("Aborted", "AbortError"));
      });
    });
    if (signal.aborted) return "";
    return "Focus stayed on Stop, then returned to the composer.";
  }

  async function start() {
    abort = new AbortController();
    const startedAt = Date.now();
    lastAnnounce = 0;
    els.log.textContent = "";
    setPhase({ status: "waiting", startedAt, elapsedMs: 0 });
    els.stop.focus();
    tick = setInterval(() => {
      if (phase.status !== "waiting") return;
      const elapsedMs = Date.now() - startedAt;
      if (elapsedMs >= FIRST_TOKEN_STALL_MS) {
        abort.abort();
        clearInterval(tick);
        setPhase({ status: "stalled", elapsedMs, reason: "first-token-timeout" });
        return;
      }
      setPhase({ status: "waiting", startedAt, elapsedMs });
    }, 500);
    try {
      const text = await mockStream(abort.signal);
      clearInterval(tick);
      if (phase.status === "stalled") return;
      setPhase({ status: "streaming", startedAt, text: "" });
      els.log.textContent = text;
      setPhase({ status: "complete", text });
    } catch (err) {
      clearInterval(tick);
      if (err.name === "AbortError") {
        if (phase.status !== "stalled") {
          setPhase({ status: "idle" });
          els.prompt.focus();
          announce("Generation stopped. Composer ready.");
        }
        return;
      }
      setPhase({ status: "error", message: "The request failed. Retry available.", recoverable: true });
    }
  }

  els.send.addEventListener("click", start);
  els.stop.addEventListener("click", () => abort && abort.abort());
  els.retry.addEventListener("click", start);
  els.prompt.addEventListener("keydown", (event) => {
    if (event.key === "Enter" && !event.shiftKey) {
      event.preventDefault();
      if (phase.status === "idle") start();
    }
    if (event.key === "Escape" && (phase.status === "waiting" || phase.status === "streaming")) {
      abort && abort.abort();
    }
  });
</script>

The important moves are boring on purpose. Stop exists before the first token. Focus moves to Stop, not into the void. Elapsed time is visible even when speech is throttled. Stall is a named transition with Retry as the new tab stop. Completion restores the composer. None of that requires ARIA fireworks. It requires a phase the dots were hiding.

Debugging technique: log the phase, not the pixels

I logged phase.status on every transition and ignored CSS until the log told a straight story. Pixel debugging would have nudged the bounce timing and left the mute gap intact. Phase debugging made the missing waiting owner obvious in about a minute.

Useful probes, in the order I actually used them:

Did fetch or the mock start before any token arrived, or did submit no-op?
What is document.activeElement right after Send unmounts?
Does the live region change during waiting, or only after streaming?
If I abort at eight seconds, does focus return, or does Stop vanish too?
If first byte exceeds the stall threshold, is Retry the next tab stop?

If you only watch the network panel, you will call a cold start “slow AI” and ship the same mute gap. The network panel cannot tell you who owns focus.

Where a remote free server made the wait honest

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

A local five-second setTimeout is a clean reproduction, and you should keep it. It is also a liar in one important way: your laptop is already warm. I needed a remote target so first-token delay was not a cartoon. MonkeyCode is an open-source project with free model access and a free server option, so I pointed the same harness at that option and watched waiting become a real duration instead of a mocked sleep. I am not quoting latency numbers here because they move with load, and I will not invent model names, quotas, or hardware. The lesson is the state machine. The remote option only made the empty interval honest.

Expected UI states, in keyboard order

Focus the composer, type, and submit with Enter. Send must not steal the story by disappearing into nowhere.
Land on Stop immediately. Confirm you can press it without a pointer, including Escape as a synonym.
Hear a throttled wait announcement, not token-sized chatter and not total silence.
If the first byte never arrives, land on Retry and hear that stall is a named failure.
On success, restore the composer and announce completion once.
On user cancel, return to the composer with a short stopped message, not a blank status.

If step two fails, everything after it is theater. Users cannot cancel a wait they cannot reach.

Accessibility notes the bouncing dots skip

Status text beats a CSS-only animation. Motion is not an accessible name.
aria-live="polite" plus throttling beats a per-token feed. Speech queues are not free.
Keep Stop mounted through waiting and streaming. Unmounting is a focus bug with extra steps.
Pointer-independent paths matter: Enter to send, Escape to stop, Retry as a real button.
Do not remount the transcript node when the first token arrives. In-place completion is a different article, but the wait state still has to survive that transition.

Environment-specific QA matrix

This is a regression matrix, not a conformance certificate. Please run the exact submit-to-first-token transition and write down versions.

Environment	What I check	Failure that counts
Chromium plus keyboard only	Submit, Stop, Escape, Retry	Focus lands on `body` after Send unmounts
Firefox plus keyboard only	Same path	Stall banner skipped in tab order
Safari plus VoiceOver (versions you record)	Wait announcements	Silence until a paragraph dump
NVDA plus Firefox or Chrome (versions you record)	Throttle vs backlog	Wait spoken every 500ms
Slow 3G throttle in DevTools	Elapsed time	Dots forever, no stall recovery

If you file a bug against this harness, I want the browser, OS, assistive technology, and the exact transition that failed. “It feels laggy” is not a transition.

Limitations, and who should not copy this blindly

This pattern does not make a cold server fast. It only makes a slow first byte explainable, cancelable, and recoverable. A twelve-second stall threshold will feel wrong in some products and too generous in others. Throttled polite announcements can still collide with other live regions on a busy page. A mock delay is not a service-level agreement, and a free remote server is not a promise about uptime, latency, or capacity.

Do not use this as a WCAG badge. Do not drop it into medical, legal, or emergency flows without a dedicated review. Do not use it if your “chat” is actually a fire-and-forget job with no user-facing cancel. And please do not treat bouncing dots as a wait state. They are decoration. Decoration cannot own focus.

Next time I feel tempted to add a typing cursor, I will ask a smaller question first. Who announces the wait, and where does the keyboard live until a token exists? If you need a remote endpoint while you answer that, MonkeyCode’s free model access and free server option are there to try against this harness.

Streaming Chat Needs In-Place Completion, Not a Remount That Drops Focus

babycat — Thu, 17 Sep 2026 04:58:18 +0000

I was one Tab away from Stop generating when the last token landed in the bubble. The Stop control vanished, and my keyboard focus jumped into the browser chrome without any spoken warning. VoiceOver stayed completely quiet, which felt worse than an error because nothing explained that disappearance. Have you ever watched a successful stream steal the only keyboard focus you still had?

The race is a completion bug

This was not a missing Stop handler, and it was not a flaky screen reader gesture either. The mouse path looked polished because the pointer never depended on that doomed button remaining mounted. I kept reproducing the break with the same four steps, and they failed whenever the last chunk arrived late.

The four steps that exposed it

Focus the composer first, then submit a short prompt with Enter so streaming actually starts.
Tab once so Stop generating receives focus while tokens are still visibly arriving in the bubble.
Wait for completion without pressing Stop, Copy, Retry, or any other control in the transcript.
Confirm the next Tab lands in browser chrome because the page no longer holds a focused node.

Why does a finished reply feel like an accessibility crash instead of a calm success state? The streaming element is thrown away, and a static twin mounts with a brand new identity. The focused Stop button dies during that commit, so the document activeElement becomes the body or null.

Draw the state table before you patch

I should have drawn this table before touching styles, because the missing row was named completing. Most chat demos jump from streaming into a brand new idle bubble and then call that success. Keyboard users live in the completing row, which is exactly where identity changes do the damage.

State	Visible UI	Focus owner	Live announcement	Keyboard action
`idle`	Composer enabled, no active reply	Composer	None	Submit the prompt
`streaming`	Same reply node plus Stop	Stop or composer	Reply is streaming	Cancel the request
`completing`	Same reply node, busy ends	Stay put, then move on purpose	Reply is complete	Copy or retry
`failed`	Same reply node plus Retry	Retry	Reply failed	Retry or dismiss
`cancelled`	Partial reply, composer enabled	Composer	Reply cancelled	Edit and resubmit

If completing remounts the article, every focused child inside that article is gone after paint. Copy cannot restore focus when it lives on a different node than the Stop control you were holding. Does your state machine even have completing, or do you collapse it into idle after the final token?

A single-file reproduction

The demo below is a local reproduction, not a production chat client with analytics or authentication. Paste it into index.html, serve the file, and use the delayed complete toggle to force the race. A polite local timer often hides the bug because you tab away before completion can fire. I needed irregular gaps between chunks so Stop could still be focused when the complete event arrived.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>In-place stream completion demo</title>
  <style>
    :root { font-family: system-ui, sans-serif; line-height: 1.45; }
    #reply[aria-busy="true"] { outline: 2px dashed #555; }
    button:focus, textarea:focus { outline: 3px solid #0b57d0; }
    .row { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-top: 0.5rem; }
  </style>
</head>
<body>
  <h1>Streaming completion focus race</h1>
  <p>Submit, Tab to Stop, wait for finish, then Tab again.</p>
  <div id="status" class="visually-hidden" aria-live="polite"></div>
  <article id="reply" aria-busy="false" hidden>
    <h2>Assistant reply</h2>
    <div id="reply-text"></div>
    <div class="row">
      <button id="stop-or-copy" type="button">Stop generating</button>
    </div>
  </article>
  <form id="composer-form">
    <label for="composer">Message</label>
    <textarea id="composer" rows="3">Explain focus loss when a stream remounts.</textarea>
    <div class="row">
      <button type="submit">Send</button>
      <label><input id="delay-complete" type="checkbox" checked /> Delay the complete event</label>
      <label><input id="remount" type="checkbox" /> Broken remount path</label>
    </div>
  </form>
  <script>
    /** @typedef {'idle' | 'streaming' | 'completing' | 'failed' | 'cancelled'} ChatStatus */
    const reply = document.getElementById('reply');
    const replyText = document.getElementById('reply-text');
    const actionBtn = document.getElementById('stop-or-copy');
    const composer = document.getElementById('composer');
    const live = document.getElementById('status');
    const remountToggle = document.getElementById('remount');
    const delayToggle = document.getElementById('delay-complete');

    /** @type {{ status: ChatStatus, text: string, abort: AbortController | null }} */
    const machine = { status: 'idle', text: '', abort: null };

    function announce(message) {
      live.textContent = '';
      requestAnimationFrame(() => { live.textContent = message; });
    }

    function renderInPlace() {
      reply.hidden = machine.status === 'idle' && !machine.text;
      reply.setAttribute('aria-busy', String(machine.status === 'streaming'));
      replyText.textContent = machine.text;
      if (machine.status === 'streaming') {
        actionBtn.textContent = 'Stop generating';
        actionBtn.dataset.mode = 'stop';
      } else {
        actionBtn.textContent = 'Copy reply';
        actionBtn.dataset.mode = 'copy';
      }
    }

    // Broken path: destroy the article and mount a twin after the last token.
    function renderWithRemount() {
      const next = reply.cloneNode(true);
      reply.replaceWith(next);
      next.id = 'reply';
      next.querySelector('#reply-text').textContent = machine.text;
      next.setAttribute('aria-busy', 'false');
      const btn = next.querySelector('#stop-or-copy');
      btn.textContent = 'Copy reply';
      btn.dataset.mode = 'copy';
    }

    function setStatus(next, announcement) {
      const before = document.activeElement;
      console.log('before complete', before && before.id);
      machine.status = next;
      if (next === 'completing' && remountToggle.checked) {
        renderWithRemount();
      } else {
        renderInPlace();
      }
      if (next === 'completing' && before && before.id === 'stop-or-copy') {
        document.getElementById('stop-or-copy').focus();
      }
      console.log('after complete', document.activeElement && document.activeElement.id);
      announce(announcement);
    }

    async function fakeStream(signal) {
      const chunks = ['Streaming ', 'chat needs ', 'one stable ', 'article node.'];
      for (const chunk of chunks) {
        if (signal.aborted) throw new DOMException('Aborted', 'AbortError');
        await new Promise((r) => setTimeout(r, 400));
        machine.text += chunk;
        renderInPlace();
      }
      if (delayToggle.checked) {
        await new Promise((r) => setTimeout(r, 1600));
      }
    }

    document.getElementById('composer-form').addEventListener('submit', async (event) => {
      event.preventDefault();
      machine.abort = new AbortController();
      machine.text = '';
      machine.status = 'streaming';
      renderInPlace();
      reply.hidden = false;
      announce('Reply is streaming');
      actionBtn.focus();
      try {
        await fakeStream(machine.abort.signal);
        setStatus('completing', 'Reply is complete');
        machine.status = 'idle';
      } catch (err) {
        if (err.name === 'AbortError') {
          setStatus('cancelled', 'Reply cancelled');
          composer.focus();
        } else {
          setStatus('failed', 'Reply failed');
          actionBtn.textContent = 'Retry';
          actionBtn.dataset.mode = 'retry';
          actionBtn.focus();
        }
      }
    });

    document.body.addEventListener('click', (event) => {
      const btn = event.target.closest('#stop-or-copy');
      if (!btn) return;
      if (btn.dataset.mode === 'stop' && machine.abort) machine.abort.abort();
      if (btn.dataset.mode === 'copy') navigator.clipboard.writeText(machine.text);
    });
  </script>
</body>
</html>

Serve it with a static file command, then run the four steps with the remount checkbox on and off.

python3 -m http.server 4173

What a free remote stream actually exposed

Local setTimeout chunks behave like a metronome, which makes the remount race annoyingly easy to miss. Disclosure: This article was prepared as part of MonkeyCode's product outreach, which I am declaring before describing that remote stream. MonkeyCode is an open-source project with free model access and a free server option. I pointed this same demo at that remote stream only as bursty traffic, not as a product benchmark. I am not publishing model names, token quotas, hardware details, or latency numbers I did not measure.

You can keep the fake timer for unit tests and reserve the remote stream for this focus race. The debugging value is irregular completion, not a model leaderboard or a hosting comparison. Wire any SSE or fetch stream into the same machine, and keep the article node stable when done arrives.

// Labeled example: point this at your own stream URL, including a free remote server.
async function readRemoteStream(url, signal, onChunk) {
  const response = await fetch(url, { signal, headers: { Accept: 'text/event-stream' } });
  if (!response.ok || !response.body) throw new Error('stream failed');
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    onChunk(decoder.decode(value, { stream: true }));
  }
}

Root cause: identity change on complete

The React tree that bit me looked harmless until I printed keys during the streaming to complete transition. One branch mounted a streaming message, and the other branch mounted a finished message with a different key. Two components and two keys mean one focused button that cannot survive the next commit phase. React is not being rude here; you asked for a new tree and it faithfully threw the old one away.

// Broken: completion remounts the focused Stop button out from under the keyboard.
{status === 'streaming' ? (
  <StreamingMessage key="hot" text={draft} onStop={stop} />
) : (
  <FinishedMessage key="cold" text={draft} />
)}

Imagine handing someone a postcard, then snatching it and sliding a photocopy under their finger instead. Their fingertip was on the stamp, and now the stamp exists on a different piece of paper. Screen readers experience the same theft when the article node is replaced at the exact completion moment. Is a prettier finished bubble worth dropping the only keyboard user who was supervising the stream?

Debug the trapdoor before you reach for ARIA

When focus disappears, I do not start with ARIA attributes or a fresh color pass on the Stop button. I log document.activeElement before and after the status write that finally marks the stream complete. If the element is null or BODY after commit, a node was removed while it still held focus. That console pair is faster than a full axe scan for this exact class of keyboard bug.

before complete  button#stop-or-copy
after complete   body          <-- remount stole focus
after complete   button#stop-or-copy  <-- in-place mutation kept it

The fix: mutate, then restore on purpose

Keep one article node for the active reply, and mutate its text instead of swapping the component type. Drive a typed status field, then change aria-busy, button labels, and announcements from that single source. If Stop is focused when status becomes complete, move focus to Copy or back to the composer. Pick one restoration target and test it; do not hope the browser will invent a reasonable fallback.

type ChatStatus = 'idle' | 'streaming' | 'completing' | 'failed' | 'cancelled';

function completeInPlace(opts: {
  article: HTMLElement;
  actionBtn: HTMLButtonElement;
  composer: HTMLTextAreaElement;
  restore: 'copy' | 'composer';
}) {
  const hadStop =
    document.activeElement === opts.actionBtn &&
    opts.actionBtn.dataset.mode === 'stop';

  opts.article.setAttribute('aria-busy', 'false');
  opts.actionBtn.dataset.mode = 'copy';
  opts.actionBtn.textContent = 'Copy reply';

  if (!hadStop) return;
  if (opts.restore === 'copy') opts.actionBtn.focus();
  else opts.composer.focus();
}

Notice the live region only announces state changes, not every token, because token chatter creates a backlog. Tokens belong in the article as text; the live region is for complete, failed, and cancelled transitions. Pointer users can still click Stop, and keyboard users can still press it without a separate hidden control.

Expected UI states after the patch

Streaming: the same article stays in the tree, aria-busy="true", Stop is a real button.
Completing: text is unchanged in place, aria-busy="false", Stop becomes Copy without a remount.
Cancelled: partial text remains, composer is enabled, focus returns to the composer on purpose.
Failed: Retry replaces Stop on the same node, and Retry receives focus if the stream died under the keyboard.

Keyboard and screen-reader checks

I did not collect a formal assistive technology lab report for this article, so treat the matrix as a reproduction invite. Please record browser, OS, and assistive-technology versions plus the exact transition that failed on your machine. The transition that matters is streaming with Stop focused, then complete, then the very next Tab key.

Environment	Action	Expected	Failure to log
Chrome + keyboard only	Stop focused, stream completes	Copy keeps focus	Focus jumps to the URL bar
Firefox + keyboard only	Cancel during stream	Composer focused, partial text remains	Stop leftover, composer disabled silently
Safari + VoiceOver	Complete announcement	One "Reply is complete"	Tokens spoken, then silence on finish
NVDA + Chrome	Tab after complete	Next control inside the transcript	Tab lands in browser chrome

If the remount checkbox still passes with a mouse, do not trust that pass. The bug is pointer-invisible until a keyboard user is holding Stop at the wrong millisecond.

Limitations, and who should not copy this

This pattern assumes you can keep a stable DOM identity for the message that is currently streaming. Virtualized transcripts that recycle row nodes will remount anyway, and you must restore focus after recycle. A free remote server is useful for irregular chunks, but it is not a production inference SLA.

Who should skip this approach? Teams that cannot own abort, focus, and status in one state machine. Also skip a free shared server if you must keep prompts off any third-party infrastructure for compliance reasons. If you only ship pointer kiosks, the remount still wastes work, but the focus trapdoor shows up less often.

Do not treat aria-live as the whole repair, and do not claim WCAG conformance from this demo alone. In-place mutation fixes the identity crash; it does not replace contrast, names, or a real abort owner. Successful streams should feel like the same card receiving its last word, not like a trapdoor under focus.

If you need bursty remote chunks to reproduce the race, MonkeyCode's free server option is one available source. Then run the four steps again, and do not ship until Stop can die without taking the keyboard with it.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Cancel Mid-Stream Needs an Abort Owner, Not a Grey Stop Button

babycat — Wed, 16 Sep 2026 03:24:25 +0000

In a lab walkthrough I assembled for this article, the failure arrived in the worst possible keyboard order. AI coding assistants in the browser all ship a Stop control now, but many of those controls only paint a disabled state. I tabbed to Stop Generating, pressed Enter, and watched the control go grey while tokens kept landing. Have you ever cancelled a generation from the keyboard and still heard the model talking afterward?

The visual state lied because the demo held two fetches and only one Stop control. Switching models opened a second request that stole the button without aborting the previous AbortController. The live region stayed polite, so leftover chunks from the first request still reached assistive technology. Why should a disabled button be the recovery path for a stream you already tried to cancel?

The interaction that actually failed

I used one keyboard-only path, and you should run it before trusting a mouse click on Stop. The point of this path is overlapping ownership during a model switch, not raw token speed. If the first request is still open when the second handle binds the button, cancel becomes theatre.

Focus the composer, submit a prompt, and wait until tokens begin appending to the transcript.
Open the model switcher from the keyboard, then choose a different model without waiting for completion.
Tab to Stop Generating and press Enter once, keeping focus where it lands afterward.
Listen for further tokens, and check whether that Stop control is disabled while still focused.

The expected UI keeps a single request as abort owner, with Stop enabled until abort completes. Focus then returns to the composer, and a polite status says that generation was cancelled. The broken UI disables Stop against a brand-new idle handle while the old stream continues writing. Can a screen-reader user tell which model is still speaking into the transcript?

Before: [Stop focused, disabled]  request A still appending tokens
After:  [composer focused]        status: Generation cancelled

State table before the fix

I placed this table early because happy-path screenshots never show two owners at once. Named states matter more than a spinner, especially when a switcher can create a second fetch. Read the switching row first, then ask who the Stop button is actually bound to.

Named state	Fetch	Abort owner	Stop button	Live region	Focus
idle	none	none	hidden	silent	composer
streaming	request A	controller A	enabled	tokens from A	Stop or transcript
switching	A open, B starting	controller B only	bound to B	tokens from A and B	model switcher
cancelled-looking	A still open	none	disabled	leftover tokens from A	trapped on Stop
cancelled	aborted and closed	cleared	hidden	Generation cancelled	composer

The switching row is the entire bug, packed into one quiet frame that the happy path never renders. Two streams share one button there, and that button reports the wrong request identity to the rest of the UI. If you cannot name the abort owner in that frame, extra ARIA on the spinner will not save the interaction.

Symptom to evidence

I did not start with role attributes, because the document was narrating a network story that never happened. Reusable debugging here means correlating identities across fetch, DOM, and focus, not sprinkling aria-busy on every waiting glyph. The five checks below are the ones that actually exposed the leaked controller.

Log requestId, signal.aborted, and modelId on every chunk, not only when the fetch begins.
Stamp each transcript node with data-request-id so leftover writes remain visible inside DevTools.
Record which element currently owns aria-busy, and which transition is allowed to clear it.
Watch focus after Enter on Stop, because a disabled button is a trap rather than a status message.
Compare a fast local mock against a slower remote stream, since cancel races almost never appear in setTimeout demos.

The local mock finished within a handful of milliseconds, so the model switch never overlapped a live response body. That is why the unit tests looked green while the keyboard path still leaked tokens into the transcript. I needed a slower endpoint that still respected cancellation, not another skeleton overlay sitting on top of the composer.

Where a free remote stream helped the reproduction

I pointed the lab client at MonkeyCode because I needed a real streaming response I could cancel from the keyboard. Disclosure: This article was prepared as part of MonkeyCode's product outreach, which is the only product relationship I need to state here. MonkeyCode is an open-source project with free model access and a free server option for this kind of lab.

I am not naming models, quoting token allotments, or publishing timings, because I did not measure those claims for this article. The useful property was latency that overlapped with Tab, Enter, and a model change during an open stream. If your mock always resolves before the next keystroke, abort ownership bugs stay invisible in both tests and demos.

A teaching fetch wrapper for the lab looks like the snippet below, and it is not a production SDK. Treat the aborted check as part of the contract, not as optional cleanup after the button has already gone grey.

type StreamHandle = {
  requestId: string;
  modelId: string;
  controller: AbortController;
};

async function startStream(
  url: string,
  body: unknown,
  handle: StreamHandle,
  onChunk: (requestId: string, text: string) => void,
) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: handle.controller.signal,
  });

  if (!response.ok || !response.body) {
    throw new Error(`stream failed: ${response.status}`);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    if (handle.controller.signal.aborted) break;
    onChunk(handle.requestId, decoder.decode(value, { stream: true }));
  }
}

Notice the aborted guard before onChunk, which is easy to skip when the Stop button already looks idle. Without that check, a late chunk still mutates the transcript after the control claims the request has ended. Have you logged aborted at chunk arrival time, or only inside the click handler that tries to stop the stream?

Root cause: the button cancelled a controller that no longer existed

The model switcher allocated a new AbortController, wrote it into component state, and rebound Stop to the latest handle. The previous handle left state without abort(), so request A kept pumping tokens into a polite live region. For one render, the latest handle looked idle, which disabled Stop while keyboard focus was still parked on that button. React was honest about its local state; that state simply described the wrong network owner.

// Anti-pattern from the lab: switching models replaces the handle without aborting.
function switchModel(nextModelId: string) {
  setModelId(nextModelId);
  setHandle({
    requestId: crypto.randomUUID(),
    modelId: nextModelId,
    controller: new AbortController(),
  });
}

There is no abort call, no status announcement, and no focus restore anywhere in that switcher function. The live region still contained leftover text from request A, so the cancelled generation sounded like output from the newly selected model. Does your switcher abort the open owner first, or does it only call setState and hope the old fetch notices?

The typed state machine that owns cancel

I collapsed the interface onto one owner, which means StreamHandle is singular or it is absent. Every transition is a named event, including SWITCH_MODEL, so a mid-stream change cannot skip abort and still look successful. The reducer below is a teaching demo, not battle-tested library code from a production chat.

type ChatEvent =
  | { type: "SUBMIT"; modelId: string; prompt: string }
  | { type: "SWITCH_MODEL"; modelId: string }
  | { type: "CHUNK"; requestId: string; text: string }
  | { type: "CANCEL" }
  | { type: "ERROR"; message: string }
  | { type: "COMPLETE"; requestId: string };

type ChatState =
  | { status: "idle"; announcement: string }
  | {
      status: "streaming";
      handle: StreamHandle;
      buffer: string;
      announcement: string;
    }
  | { status: "cancelling"; handle: StreamHandle; announcement: string }
  | { status: "error"; message: string; announcement: string };

function reduce(state: ChatState, event: ChatEvent): ChatState {
  switch (event.type) {
    case "SWITCH_MODEL": {
      if (state.status === "streaming") {
        state.handle.controller.abort();
        return {
          status: "cancelling",
          handle: state.handle,
          announcement: "Cancelling the previous model before switching.",
        };
      }
      return { ...state, announcement: `Model set to ${event.modelId}.` };
    }
    case "CANCEL": {
      if (state.status !== "streaming") return state;
      state.handle.controller.abort();
      return {
        status: "cancelling",
        handle: state.handle,
        announcement: "Cancelling generation.",
      };
    }
    case "CHUNK": {
      if (state.status !== "streaming") return state;
      if (event.requestId !== state.handle.requestId) return state;
      if (state.handle.controller.signal.aborted) return state;
      return { ...state, buffer: state.buffer + event.text };
    }
    default:
      return state;
  }
}

The requestId equality check and the abort-before-switch path are the actual fix for the leaked speech. Chunks from a dead owner become no-ops instead of extra spoken markdown in the polite live region. Should a cancelled request ever be allowed to speak through the same live region again after Stop has fired?

Semantic structure, focus, and announcements

Stop Generating remains a real button, not a clickable div with a late keydown handler bolted on. It is disabled only while status is cancelling, never because some other handle looked idle for a single frame. After cancel settles, focus moves back to the composer, and a polite atomic status node announces that generation was cancelled. Pointer users fire the same CANCEL event through that button, so there is no hover-only stop glyph hiding beside the stream.

<section aria-labelledby="chat-heading">
  <h2 id="chat-heading">Streaming reply</h2>
  <div id="transcript" aria-live="polite" aria-relevant="additions"></div>
  <p id="status" aria-live="polite" aria-atomic="true"></p>
  <label>
    Prompt
    <textarea id="composer"></textarea>
  </label>
  <button type="button" id="stop" data-action="cancel">Stop generating</button>
</section>

I keep token text in the transcript and discrete status in a second live region on purpose for this demo. Mixing cancel messages into the same node that receives tokens is how spoken status falls behind the stream. Focus rules I encode as lab checks, rather than as a vague accessibility appendix, are listed next.

Submit moves focus to Stop Generating after the first token arrives, not while the request is still connecting.
Cancel restores focus to the composer and never leaves the user parked on a disabled control.
Model switch during streaming aborts, announces the cancel, and only then starts the next handle.
Escape dispatches the same CANCEL event as the button, so keyboard users are not hunting for Stop.

Error, cancel, and retry without a silent composer

When the remote endpoint returned an error, I refused to cover the composer with a toast that could not take focus. The error state exposes a focusable status region with Retry and Dismiss as real buttons in the tab order. Retry allocates a new requestId and a new AbortController; it never reuses a signal that already aborted, because aborted signals stay aborted. If cancel is still in flight, Retry is omitted, which sounds obvious until a leaked handle renders both actions at once.

function retryFromError(
  state: ChatState,
  modelId: string,
  prompt: string,
): ChatEvent {
  if (state.status !== "error") {
    throw new Error("retry is only legal from error");
  }
  return { type: "SUBMIT", modelId, prompt };
}

Who owns the in-flight request after Retry is pressed from that error status region? If answering that question needs a paragraph, the state machine still has two owners and a lying button. Pointer-independent retry matters here, because the people who cancelled from the keyboard are the same people who need to recover.

Environment-specific QA matrix

Please reproduce with versions written down, not with a vague sense that VoiceOver sounded generally fine yesterday. The transition that failed in the lab is streaming, then switch model, then Stop, then leftover tokens still arriving. This matrix is a proposed checklist for that path, not a claim that I certified every cell on a given day.

Environment	Assistive tech	Transition	Pass if
Chrome current, Windows	NVDA	streaming → switch → Stop	no further tokens spoken; composer focused
Firefox current, macOS	VoiceOver	streaming → Escape	Generation cancelled is spoken; composer focused
Safari current, iOS	VoiceOver	streaming → Stop	Stop does not remain a disabled tab stop
Keyboard only, any browser	none	Tab to Stop, then Enter	the pointer is unnecessary for cancel

If the first token arrives after you have already switched models, you are still inside the original race. Slow the stream on purpose with a remote endpoint or a throttled local ReadableStream before you declare cancel done. Otherwise the QA grid will pass for the same reason the unit tests passed: nothing lived long enough to overlap a keystroke.

Limitations, and who should not copy this

This pattern is for user-cancellable token streams inside a browser chat surface, not for arbitrary background work. It will not cancel server work that ignores AbortSignal, and it is not a job queue for long-running agents that commit side effects. I am not claiming conformance for your product, because I cannot hear your live region or see your focus order in production.

Do not copy this approach if you only mock streams with setTimeout at zero delay, or if Stop is a decorative icon. Skip it when model switch is allowed to multiplex two audible replies, because the machine assumes a single abort owner at a time. Also skip a free remote endpoint if you need named models, guaranteed capacity, or a production service level for real users.

The free model access in this walkthrough was enough to keep a stream open during keyboard interaction and model switching. It is not a promise about rate limits, hardware, duration, or benchmarked quality of any particular model. If that remote stream is unavailable, use a local throttled ReadableStream and keep the same reducer, because the bug lives in ownership.

What I would inspect next

If tokens still speak after cancel, dump requestId from the DOM node that mutated after Stop. If focus disappears into nowhere, you probably disabled the control that currently held the tab stop. If the cancel announcement arrives late, status text is likely sharing a live region with the transcript buffer. None of those failures are library mysteries; they are abort-ownership bugs you can see with a stamped chunk log.

If you need a slower public stream for the same keyboard reproduction, MonkeyCode's free server option is a convenient target for the lab client. Run the streaming-to-switch-to-Stop transition on your own machine, then write down the browser, operating system, and assistive-technology versions that still leak chunks. I care more about that exact failed transition than about a screenshot of a happy stream finishing in the default theme.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

My Screen Reader Read Three Sentences Behind: Debugging a Live-Region Backlog in Streaming Chat

babycat — Tue, 15 Sep 2026 03:05:11 +0000

My Screen Reader Read Three Sentences Behind: Debugging a Live-Region Backlog in Streaming Chat

At 1:12 a.m. on a Tuesday, a QA note landed in my inbox with a twelve-second screen recording attached to it. Visually, the chat reply had finished: the typing dots were gone, the Stop button was disabled, and the text sat quietly on screen. Audibly, the screen reader kept speaking words from the middle of that same message for another eleven seconds. The visual UI said "done," and the audio channel said "still catching up."

Was the model still streaming? No — the network panel showed the response body had closed cleanly a moment earlier. Was the screen reader broken? Also no, and that assumption cost me an hour before I dropped it. I had simply handed the assistive technology a job it could never finish in real time.

This post is the debugging retro: the symptom table, three hypotheses, an instrumented reproduction, the real root cause, and the commit-boundary fix I now use in every streaming chat interface.

The one-line rule before we start: never mutate a polite live region once per token. Buffer tokens, then commit complete sentence or paragraph additions into a single role="log" container.

The symptom table I write before touching any code

Ask what the interface promises before you open a debugger, because streaming text runs two clocks at the same time. One clock is visual paint, and the other one is the speech queue that nobody instruments. Most teams measure the first and assume the second follows it.

Moment	What sighted users see	What the screen reader should do
Stream starts	Dots appear, Stop enables	Nothing, or one short status message
Tokens arrive	Words fill in gradually	Nothing per token
Sentence ends	Same visual, no change	Announce the new sentence once
Long unpunctuated stretch	Text keeps growing	Announce on a time budget, not per character
Stream ends	Dots vanish, controls settle	Finish the last addition, then stop
Error	Inline error appears	Announce the error text once
User cancels	Text freezes, "Stopped" appears	Announce the stop once, leave focus alone

Observed behavior in that recording: the announcement queue lagged about three sentences behind at completion, and the gap grew with response length. When I swapped a long answer for a two-line answer, the lag nearly disappeared, which was the first genuinely useful clue.

Three hypotheses, one instrumented reproduction

I listed the plausible causes before writing any fix, because guessing at assistive-technology behavior is how you ship a second bug on top of the first.

Every token mutated a polite live region, so mutations queued faster than speech could drain them.
aria-atomic="true" sat on the transcript container, forcing whole-region re-announcements.
The framework re-rendered the message node on each chunk, so the AT lost the position it had been tracking.

To separate them, I counted DOM mutations inside the log container and compared that cadence with what I actually heard. The instrumentation is short, and it works in any framework because it observes the DOM instead of your component tree:

const log = document.querySelector('[role="log"]');
let additions = 0;
let textChanges = 0;
const started = performance.now();

new MutationObserver((records) => {
  for (const record of records) {
    if (record.type === "childList") additions += record.addedNodes.length;
    if (record.type === "characterData") textChanges += 1;
  }
}).observe(log, { childList: true, subtree: true, characterData: true });

setInterval(() => {
  const elapsed = Math.round(performance.now() - started);
  console.log(`${elapsed}ms additions=${additions} text=${textChanges}`);
}, 1000);

Read the output against three signatures, because each signature points at a different fix:

Additions per second roughly equal to tokens per second means hypothesis 1, and the queue is the problem.
Additions spiking while the visible text stays identical means hypothesis 3, which is remount churn.
A single addition that re-announces the entire message means hypothesis 2, and you should inspect the accessibility tree rather than your JSX.

How I hosted the reproduction

I wanted a real token stream instead of a hardcoded fixture, so I ran the whole reproduction on MonkeyCode, an open-source project that offers free model access and a free server option. Its page advertises a free token allowance, 10M tokens at the time of writing, so treat that figure as time-sensitive and confirm the current terms yourself. I did not need a paid tier to serve a static demo page plus a small streaming proxy.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

One security note that matters more than the hosting choice: keep provider keys on the server side behind your proxy, even in a throwaway demo, and never inline them into the client bundle.

Root cause: a queue that speaks at 1× and receives at 8×

Polite live regions do not drop text, and that is exactly why they fail here. They schedule it. When you mutate the region faster than the speech engine can drain its queue, the backlog accumulates monotonically for as long as the stream runs. The stream then ends while the queue is still draining, which produces the precise symptom in that recording: a finished UI with a voice still reading the middle of the message.

Hypothesis 3 makes the same problem worse in a subtler way. If your renderer replaces the message node on each chunk, the region's tracked content resets constantly, and some AT and browser pairings react by re-reading earlier text. That is why the audio sometimes jumped backwards instead of simply lagging.

Why not just set the live region to off and announce once at the end? For a two-line answer that is fine, but for a thirty-second answer the user sits in silence with no idea whether the request is alive. Coalescing gives you progress without giving up a readable cadence.

The fix: commit at boundaries, never per token

Start with a transcript that is one live region, not many, and keep a separate status element for stream state. role="log" already implies polite behavior with additions and text as the relevant changes, so declaring the attributes is mostly documentation for the next reader.

<div id="transcript" role="log" aria-live="polite" aria-relevant="additions"></div>

<p id="stream-status" role="status" class="sr-only">Idle</p>

Then buffer incoming tokens and commit them as single DOM additions when a boundary occurs. The thresholds below are heuristics I tuned by listening, not laws of nature, so change them after you measure your own responses.

const BOUNDARY = /([.!?…]["')\]]?(?=\s|$)|\n{2,})/;
const MAX_CHARS = 120;
const MAX_WAIT_MS = 900;

class LogCommitter {
  #buffer = "";
  #timer: number | null = null;
  #lastCommit: number;

  constructor(private readonly log: HTMLElement, private readonly now = () => performance.now()) {
    this.#lastCommit = this.now();
  }

  push(token: string): void {
    this.#buffer += token;
    const hitBoundary = BOUNDARY.test(this.#buffer);
    const tooLong = this.#buffer.length >= MAX_CHARS;
    const tooSlow = this.now() - this.#lastCommit >= MAX_WAIT_MS;
    if (hitBoundary || tooLong || tooSlow) this.commit();
    else this.#schedule();
  }

  finish(): void {
    this.commit();
  }

  #schedule(): void {
    if (this.#timer !== null) return;
    const wait = Math.max(0, MAX_WAIT_MS - (this.now() - this.#lastCommit));
    this.#timer = window.setTimeout(() => {
      this.#timer = null;
      this.commit();
    }, wait);
  }

  commit(): void {
    if (this.#timer !== null) {
      clearTimeout(this.#timer);
      this.#timer = null;
    }
    const text = this.#buffer.trim();
    this.#buffer = "";
    this.#lastCommit = this.now();
    if (!text) return;

    const chunk = document.createElement("span");
    chunk.textContent = `${text} `;
    this.log.append(chunk); // one DOM addition → one polite announcement
  }
}

Wiring it up stays boring, which is the point:

const transcript = document.querySelector<HTMLElement>("#transcript")!;
const committer = new LogCommitter(transcript);

for await (const token of tokenStream) {
  committer.push(token);
}
committer.finish();

Two details make this hold together in practice. First, never repeat the message text inside the status region, or every commit gets announced twice. Second, the visual typing cursor can live outside the transcript as a decorative element, but the committed text must stay in one place so reading order never changes under the user.

The state table your implementation actually needs

Write this table down, because it forces you to decide what the log does in every state instead of only the happy one.

State	Buffer	DOM write	Live region effect	Focus
Idle	Empty	None	Silent	Composer
Streaming	Growing	None	Silent	Composer, unchanged
Committing (boundary hit)	Flushed	Append one span	One polite addition	Unchanged
Complete	Flushed	Append final span	One addition, status updates	Unchanged
Error	Flushed or dropped	Error text in the same log	One plain-language error	Stays in composer
Cancelled	Flushed	"Stopped by you" appended	One addition	Wherever the user left it

The 20-minute manual test

Automated mutation counts tell you cadence, but only listening tells you comprehension. This is the sequence I run before calling a streaming UI done:

Open the deployed reproduction and enable your screen reader with speech at your normal rate.
Request an answer of at least three sentences and start a stopwatch when the visible text stops changing.
Stop the stopwatch on the last spoken word, and write the gap into the matrix below.
Request an answer that contains a long unpunctuated string, to exercise the 900 ms time budget.
Cancel mid-stream, and confirm the log announces the stop once without moving focus.
Force an error by killing the proxy, then confirm the error is announced once and in plain language.
Repeat everything with only the keyboard, and watch for reading position jumps.

Browser	OS	AT and version	Gap at completion	Re-read earlier text?
Chrome	Windows	NVDA (your version)	___ s	yes / no
Chrome	macOS	VoiceOver (your version)	___ s	yes / no
Safari	iOS	VoiceOver (your version)	___ s	yes / no
Firefox	Windows	NVDA (your version)	___ s	yes / no

Fill this with your own numbers rather than mine, because default speech rates, punctuation handling, and queue behavior differ per pairing. A gap that stays flat as responses get longer is a passing result, and a gap that grows with length means you are still committing too often.

What this approach does not fix, and who should skip it

Coalescing is a cadence fix, not a universal accessibility fix, and I would rather be honest about the edges:

It does not equalize AT behavior. Braille display users may prefer a different commit cadence than speech users.
It does not fit code-heavy responses, where sentence punctuation inside a code block is meaningless. Commit at fenced-block boundaries instead.
It adds complexity you do not need if your responses arrive complete, or if you are rendering short deterministic strings.
It is a poor fit for live captioning, where latency matters more than chunk size, so use a dedicated policy for that case.
A free demo server is not production infrastructure. Do not put real user data, long-lived secrets, or compliance-relevant logs on one.

The thresholds here are my heuristics after listening to real responses, and they will need retuning for fast speech rates, verbose models, or languages where sentence boundaries look different.

Reproduce it with me

If your streaming UI finishes visually before it finishes audibly, I would like the exact numbers: browser, OS, assistive technology and version, plus the specific transition where the queue fell behind. Those three data points turn a vague "screen reader feels laggy" report into something reproducible in twenty minutes. If you want to run the reproduction without standing up your own model proxy, MonkeyCode's free model access and free server option are what I used for mine, though check the current terms before you plan around them. Fix the cadence first, and the interface will finally agree with itself.

Chat File Consent Needs a Request Snapshot, Not a Sticky Include Checkbox

babycat — Sun, 13 Sep 2026 19:09:48 +0000

I tabbed onto Retry after a sluggish timeout, and VoiceOver still described the composer as empty. The Network panel told a much less comforting story about that same impatient retry click I made. The retry had posted my unsaved buffer, even though Include current file sat visually unchecked. Have you ever trusted a checkbox that was only decorating the last request you sent?

This walkthrough is a lab reproduction, not a production postmortem with customer telemetry behind it. I wanted an accessible coding chat that could attach the current file, fail slowly, and recover without lying. The failure was quiet, repeatable, and worse than a crashed stream because the UI looked honest.

The interaction that actually failed

The composer stayed focusable. The checkbox looked unchecked. The live region said the request timed out, then offered Retry as a real button. Keyboard users could reach Retry without a pointer, which felt like a win until the POST left the tab.

Here is the exact transition I kept reproducing in the demo:

Check Include current file, send a prompt, then uncheck the box while tokens stream.
Let the remote turn hit a timeout instead of a clean abort, so Retry stays available.
Press Retry without visiting the checkbox again, and inspect the JSON body.
Hear VoiceOver announce timeout recovery, with no warning that a buffer is leaving the browser.

Would you call that a streaming bug, a forms bug, or a privacy bug? I treated it as all three, because the accessible controls were telling a different story from the payload.

State table before any ARIA debate

I put the state table above widgets on purpose. If the states are wrong, a prettier checkbox cannot save the retry path.

Phase	Composer	Include file control	Retry	What may leave the browser	Live region
`idle`	enabled	reflects next request only	hidden	nothing	idle, not busy
`confirming`	disabled	keyboard operable	hidden	nothing yet	“Confirm whether to include the current file.”
`streaming`	disabled	disabled, shows snapshot	hidden	snapshot captured at send	“Generating answer.” once
`timed_out`	enabled	shows snapshot, not a guess	enabled	still nothing new	“The request timed out. Retry is available.”
`retrying`	disabled	locked to snapshot or a new confirm	disabled	only the snapshot the user confirmed	“Retrying the timed-out request.”
`denied`	enabled	unchecked and announced	hidden	prompt text only	“Current file will not be sent.”

Notice Retry never reads the live checkbox. Retry reads a frozen snapshot, or it must open a confirm path again. That one rule would have stopped my leak.

Why a slow free endpoint made the bug obvious

Local mocks hide this class of failure because they resolve before anyone unchecks a box. I needed a remote turn that stayed open long enough for a consent change, then died with a timeout instead of a tidy cancel. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I pointed the lab at MonkeyCode as an open-source project with free model access and a free server option, which made the slow timeout easy to trigger without inventing a private cluster.

I am not attaching model names, token ceilings, or hardware claims here, because those details drift and I did not verify them for this article. The useful property for this bug is simple latency you can feel with a keyboard. If your mock answers in forty milliseconds, you will never watch a user uncheck a file while the request is still alive.

Symptom, then the lying object

The first screen-reader pass sounded fine. Timeout was announced once. Focus returned to the composer, not to a toast. Retry was a button in tab order, not a mouse-only overlay. So why did I still flinch when I opened DevTools?

The request body still had this shape:

// Lab reproduction only. This is the broken payload I logged.
{
  "prompt": "Explain the timeout path in ChatRequest.",
  "files": [
    {
      "name": "ChatRequest.ts",
      "content": "export type ChatRequest = { /* unsaved buffer */ }"
    }
  ],
  "retryOf": "req_17"
}

The checkbox in the DOM was unchecked. The React state for includeFile was false. The retry helper had cloned lastRequest, and lastRequest.files was still populated from send time. Which source of truth would you trust in a code review: the widget, the atom, or the blob that actually went to the network?

Root cause: consent lived on the widget, files lived on the request

I had modeled consent like a settings flag, because that is how dark mode and density toggles work. File inclusion is not a theme. It is part of one HTTP request, and it must die with that request.

The broken helper looked roughly like this:

// Broken lab code: retry reuses the last network payload.
function retryLastRequest(last: ChatRequest, liveIncludeFile: boolean): ChatRequest {
  return {
    ...last,
    id: crypto.randomUUID(),
    retryOf: last.id,
    // liveIncludeFile is ignored, so unchecking does nothing on retry
  };
}

Two more mistakes sat under that helper, and they only showed up with assistive tech plus a slow timeout.

The checkbox was not disabled during streaming, so it looked editable while the in-flight snapshot stayed unchanged.
Retry did not re-announce file inclusion, so a screen-reader user could activate recovery without hearing that a buffer would travel again.

Is a sticky Include checkbox convenient? Yes. Is it an accurate control once a request has left the tab? No.

Fix: bind consent to the request id

The repair is a snapshot, not a smarter aria-label. Capture consent when the user sends, store it on the request id, and refuse to serialize files unless that snapshot still says yes.

type ConsentSnapshot = {
  requestId: string;
  includeFile: boolean;
  fileName: string | null;
  grantedAt: number;
};

type ChatPhase =
  | { status: "idle" }
  | { status: "confirming"; requestId: string }
  | { status: "streaming"; requestId: string; consent: ConsentSnapshot }
  | { status: "timed_out"; requestId: string; consent: ConsentSnapshot }
  | { status: "retrying"; requestId: string; consent: ConsentSnapshot }
  | { status: "error"; requestId: string; message: string };

function snapshotConsent(requestId: string, includeFile: boolean, fileName: string | null): ConsentSnapshot {
  return { requestId, includeFile, fileName, grantedAt: Date.now() };
}

function toNetworkBody(prompt: string, consent: ConsentSnapshot, file: { name: string; content: string } | null) {
  if (!consent.includeFile || !file || file.name !== consent.fileName) {
    return { prompt, files: [] as const, requestId: consent.requestId };
  }
  return { prompt, files: [file], requestId: consent.requestId };
}

Retry now has to choose one of two honest paths. It can resend the frozen snapshot after announcing that the same file will be included. Or it can drop into confirming again, move focus to the dialog, and require a keyboard-confirm before any buffer is attached.

function planRetry(phase: Extract<ChatPhase, { status: "timed_out" }>): ChatPhase {
  if (!phase.consent.includeFile) {
    return { ...phase, status: "retrying" };
  }
  // Do not silently reuse files just because they exist in memory.
  return { status: "confirming", requestId: crypto.randomUUID() };
}

I prefer the confirm path whenever a file would leave the machine. Timeouts are confusing enough. Users should not also have to remember what a checkbox looked like forty seconds ago.

Accessible UI for the snapshot, not for the live box

A request-bound snapshot still needs a visual and spoken representation. I treated the streaming row like a receipt, not like a setting that might change the in-flight turn.

function FileConsent({ phase, includeFile, onToggle }: {
  phase: ChatPhase;
  includeFile: boolean;
  onToggle: (next: boolean) => void;
}) {
  const locked = phase.status === "streaming" || phase.status === "retrying";
  const snapshotName = "consent" in phase ? phase.consent.fileName : null;

  return (
    <div className="consent">
      <label>
        <input
          type="checkbox"
          checked={locked ? Boolean(snapshotName) && "consent" in phase && phase.consent.includeFile : includeFile}
          disabled={locked}
          onChange={(event) => onToggle(event.target.checked)}
        />
        Include current file in the next request
      </label>
      {locked && (
        <p>
          In-flight snapshot: {"consent" in phase && phase.consent.includeFile
            ? `${phase.consent.fileName} will be sent`
            : "no file will be sent"}
        </p>
      )}
    </div>
  );
}

Use a real label and a real checkbox. A chip that never receives tab focus is how this pattern quietly fails. Disable the control while a snapshot is in flight so the widget cannot contradict the receipt.

Status text belongs in a polite live region that speaks phase changes, not file contents. Never dump buffer text into aria-live, because that is a privacy incident and a speech flood in the same gesture.

<div role="status" aria-live="polite" aria-atomic="true">
  {statusTextFor(phase)}
</div>

On timeout, move focus back to the composer, then let Retry sit next in tab order. Do not trap focus in a skeleton overlay, and do not steal it with a toast that disappears before anyone reads the consent receipt.

Keyboard and screen-reader regressions to run

I did not record a pass/fail matrix as production evidence, so treat this as the lab script. The failing transition is always uncheck during stream → timeout → Retry.

Tab from the prompt textarea to the checkbox, then to Send, with no pointer.
While streaming, confirm the checkbox is disabled and the snapshot text is still in the reading order.
Trigger a timeout, hear one announcement, and confirm focus is in the composer.
Tab to Retry, activate it, and confirm a blocking confirm when a file would be resent.
Cancel that confirm and inspect the network panel for an empty files array.
Repeat with captions and a screen reader, because the visual unchecked state is not enough.

Suggested environments for the same transition:

Windows 11, Firefox, NVDA
macOS, Safari, VoiceOver
Windows 11, Chrome, JAWS
Keyboard only, no assistive technology, watching focus rings

If Retry posts files while the confirm dialog is still open, you are not done. If the live region reads the file body, you are also not done.

What this approach is not

A consent snapshot is an interface guarantee, not a compliance program. It will not tokenize secrets, strip .env files, or replace a legal review. It also will not help if your agent uploads a whole workspace through a different code path that bypasses the composer.

Skip this pattern when you already have a blocking, request-scoped permission dialog with server-side enforcement. Skip it when the product must never send local files, because then the checkbox should not exist. Skip it if you only ship happy-path demos that never time out, since the bug lives on the recovery path.

The free remote option is a debugging tool here, not a privacy control. Slow servers reveal races. They do not decide whether a buffer should travel.

Close the loop on Retry

After the snapshot landed, Retry stopped feeling like a magic restore button and started feeling like a second send. The checkbox finally described the next request only. The receipt described the in-flight one. VoiceOver could narrate timeout recovery without implying that the composer was empty of consequences.

If you are wiring a similar lab and want a remote turn that stays open long enough to uncheck a file, MonkeyCode’s free server option is one straightforward way to reproduce that timeout on purpose. Then keep the network panel open, because the honest UI is the payload, not the checkbox you left behind.

Remote Chat Failover Needs a Tab-Stop Origin Banner, Not a Skeleton Overlay

babycat — Sat, 12 Sep 2026 17:05:10 +0000

I was halfway through a keyboard-only pass on a streaming chat when the local path died. A skeleton overlay covered the composer, my focus jumped, and tokens started arriving from somewhere else. Did the interface tell me those tokens had left the browser? It did not, and that silence is the real defect.

Sighted teammates might notice a faint retry pulse and keep going. Keyboard and screen-reader users only felt a trap, then a voice that never named the new host. This write-up is a debugging retrospective, from that frozen caret to a typed origin state you can fail on purpose.

The failure I kept reproducing

I built a small chat shell that retries when a local inference call rejects. The retry helper reused status: "streaming", so the UI never distinguished on-device work from a remote server. That collapse is how a privacy change becomes a loading animation, and it is an easy mistake when failover feels like infrastructure rather than UX.

Here is the interaction I treated as the failing transition.

Start: composer focused, local origin, chat idle
Action: submit a prompt the local path cannot serve
Observed: overlay appears, focus leaves the textarea, no announcement
Then: tokens stream, overlay unmounts, focus is simply gone
Expected: origin change is announced, consent is reachable, focus returns

The state table I wished I had on day one

If your table has one streaming row, you will hide origin changes from assistive tech. That is the pitfall, not the spinner’s CSS.

State	Origin	Focus	Live region	Composer
idle	local	textarea	silent	enabled
streaming-local	local	textarea	Answer streaming on this device	disabled, cancel available
needs-consent	remote proposed	primary consent control	Local path failed. Remote send needs confirmation	disabled
streaming-remote	remote	textarea after confirm	Answer streaming from a remote server	disabled, cancel available
error	last known	retry, then composer	assertive error, once	enabled
cancelled	last known	composer	Request cancelled	enabled

Why does a skeleton feel honest while still lying? Because waiting is visible, and destination is not.

Symptom to root cause

I started with the keyboard, not the network panel, because the complaint was focus loss. Tab after the overlay appeared cycled through chrome around the chat, then died against aria-hidden on the main landmark. The overlay had been marked aria-busy="true" on #app, which is a blunt instrument and a familiar false friend.

Was the fetch still using the local URL? DevTools said no. The retry wrapper swapped the endpoint after a single 503, then streamed as if nothing privacy-related had happened. The visual skeleton was honest about waiting and dishonest about where the bytes went.

Root cause, stacked in three mistakes I now look for first:

One boolean, isStreaming, represented local work, remote work, and the gap between them.
The overlay stole focus with tabIndex={-1} plus an effect that called overlayRef.current?.focus().
The live region only announced “Assistant is typing,” which is the same phrase for every origin.

None of those is an ARIA trivia problem. They are state-modeling problems that accessibility tools merely made visible. If you “fix” them by adding more live regions without an origin enum, you will drown the one sentence that mattered.

Debugging technique you can reuse

I now keep a three-column log while reproducing AI chat failures. It is slower than jumping into CSS, and it stops me from treating a privacy change like a spinner ticket.

Input: key, pointer, or programmatic submit, plus the last focused element id.
Network: which host answered, and whether the client chose it automatically.
Accessibility tree: name, role, and live-region text at the moment of the transition.

If column two changes host while column three stays frozen, you have a silent origin bug. If column one and the accessibility tree disagree about focus, you have a trap. Write the log before you add another aria-* attribute, because attributes cannot recover a missing phase.

I also freeze the retry in a reducer so I can replay it without waiting on a real model. The sketch below does that with a local failure, then an optional remote path. Think of origin like a shipping label on a package you already started wrapping: the packing motion can look identical, but the destination is what people must hear.

A typed origin, not another spinner

A typed union forces every view to answer a rude question: where is this request going? Automatic failover is convenient for developers and hostile for people who cannot see the URL bar change.

type Origin = "local" | "remote";

type ChatPhase =
  | { status: "idle" }
  | { status: "streaming"; origin: Origin }
  | { status: "needs-consent"; to: Origin; prompt: string }
  | { status: "error"; message: string; origin: Origin }
  | { status: "cancelled"; origin: Origin };

The needs-consent phase is the missing beat. Ask before the first remote token, keep that question in the tab order, then restore focus. I am not using a focus-trapped modal here on purpose: the last time I shipped a blocking dialog for a different chat prompt, testers lost the transcript. This banner stays in document flow.

stateDiagram-v2
  [*] --> idle
  idle --> streamingLocal: submit
  streamingLocal --> idle: done
  streamingLocal --> cancelled: stop
  streamingLocal --> needsConsent: local 503
  needsConsent --> streamingRemote: confirm
  needsConsent --> cancelled: decline
  streamingRemote --> idle: done
  streamingRemote --> cancelled: stop
  cancelled --> idle: type again

Minimal reproduction

The following React sketch is a labeled demo, not a production privacy platform. It keeps the origin banner in tab order and returns focus to the composer after confirm or cancel. Screen-reader copy is short on purpose so the live region does not flood.

I needed a remote target that did not require a private GPU story in this article. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I pointed the failover branch at MonkeyCode’s free model access and free server option so the remote origin was real enough to test announcements, without standing up my own inference box.

import { useEffect, useReducer, useRef } from "react";

type Origin = "local" | "remote";

type Phase =
  | { status: "idle" }
  | { status: "streaming"; origin: Origin }
  | { status: "needs-consent"; prompt: string }
  | { status: "error"; message: string }
  | { status: "cancelled" };

type State = {
  phase: Phase;
  draft: string;
  answer: string;
  log: string;
};

type Action =
  | { type: "type"; value: string }
  | { type: "submit" }
  | { type: "local-fail"; prompt: string }
  | { type: "consent-yes" }
  | { type: "consent-no" }
  | { type: "token"; chunk: string }
  | { type: "done" }
  | { type: "cancel" };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case "type":
      return { ...state, draft: action.value };
    case "submit":
      if (state.phase.status === "streaming") return state;
      return {
        ...state,
        answer: "",
        phase: { status: "streaming", origin: "local" },
        log: "Answer streaming on this device.",
      };
    case "local-fail":
      return {
        ...state,
        phase: { status: "needs-consent", prompt: action.prompt },
        log: "Local path failed. Confirm before sending to a remote server.",
      };
    case "consent-yes":
      return {
        ...state,
        phase: { status: "streaming", origin: "remote" },
        log: "Answer streaming from a remote server.",
      };
    case "consent-no":
      return {
        ...state,
        phase: { status: "cancelled" },
        log: "Remote send cancelled. Composer is ready.",
      };
    case "token":
      return { ...state, answer: state.answer + action.chunk };
    case "done":
      return { ...state, phase: { status: "idle" }, log: "Answer complete." };
    case "cancel":
      return {
        ...state,
        phase: { status: "cancelled" },
        log: "Request cancelled.",
      };
    default:
      return state;
  }
}

export function OriginAwareChat() {
  const [state, dispatch] = useReducer(reducer, {
    phase: { status: "idle" },
    draft: "",
    answer: "",
    log: "Chat idle on this device.",
  });
  const composerRef = useRef<HTMLTextAreaElement>(null);
  const confirmRef = useRef<HTMLButtonElement>(null);
  const abortRef = useRef<AbortController | null>(null);

  useEffect(() => {
    if (state.phase.status === "needs-consent") {
      confirmRef.current?.focus();
      return;
    }
    if (
      state.phase.status === "idle" ||
      state.phase.status === "cancelled" ||
      state.phase.status === "error"
    ) {
      composerRef.current?.focus();
    }
  }, [state.phase.status]);

  async function send(origin: Origin, prompt: string, signal: AbortSignal) {
    const response = await fetch(
      origin === "local" ? "/local-infer" : "/remote-infer",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ prompt }),
        signal,
      }
    );
    if (!response.ok || !response.body) throw new Error("infer-failed");
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      dispatch({ type: "token", chunk: decoder.decode(value) });
    }
  }

  async function onSubmit(event: React.FormEvent) {
    event.preventDefault();
    const prompt = state.draft.trim();
    if (!prompt) return;
    dispatch({ type: "submit" });
    abortRef.current?.abort();
    const controller = new AbortController();
    abortRef.current = controller;
    try {
      await send("local", prompt, controller.signal);
      dispatch({ type: "done" });
    } catch {
      if (controller.signal.aborted) dispatch({ type: "cancel" });
      else dispatch({ type: "local-fail", prompt });
    }
  }

  async function confirmRemote() {
    if (state.phase.status !== "needs-consent") return;
    const prompt = state.phase.prompt;
    dispatch({ type: "consent-yes" });
    const controller = new AbortController();
    abortRef.current = controller;
    try {
      await send("remote", prompt, controller.signal);
      dispatch({ type: "done" });
    } catch {
      if (controller.signal.aborted) dispatch({ type: "cancel" });
      else dispatch({ type: "done" });
    }
  }

  const blocked =
    state.phase.status === "streaming" ||
    state.phase.status === "needs-consent";

  return (
    <div className="chat">
      <p aria-live="polite" aria-atomic="true" className="sr-only">
        {state.log}
      </p>

      {state.phase.status === "streaming" && (
        <p className="origin-banner" tabIndex={0}>
          Origin:{" "}
          {state.phase.origin === "local" ? "this device" : "remote server"}
        </p>
      )}

      {state.phase.status === "needs-consent" && (
        <div
          className="origin-banner"
          role="region"
          aria-labelledby="consent-title"
        >
          <h2 id="consent-title">Send this prompt to a remote server?</h2>
          <p>The local path failed. A remote model will see the prompt text.</p>
          <button ref={confirmRef} type="button" onClick={confirmRemote}>
            Send remotely
          </button>
          <button type="button" onClick={() => dispatch({ type: "consent-no" })}>
            Stay on this device
          </button>
        </div>
      )}

      <div aria-live="polite">{state.answer}</div>

      <form onSubmit={onSubmit}>
        <label htmlFor="composer">Message</label>
        <textarea
          id="composer"
          ref={composerRef}
          value={state.draft}
          disabled={blocked}
          onChange={(event) =>
            dispatch({ type: "type", value: event.target.value })
          }
        />
        <button type="submit" disabled={blocked}>
          Send
        </button>
        <button
          type="button"
          onClick={() => {
            abortRef.current?.abort();
            dispatch({ type: "cancel" });
          }}
          disabled={state.phase.status !== "streaming"}
        >
          Stop
        </button>
      </form>
    </div>
  );
}

Notice the origin banner is a tab stop while streaming, not a toast. Toasts expire, and expired copy cannot be reviewed by a screen-reader cursor. The consent region sits in document order ahead of the composer, so Tab does not wander through the chrome first.

A little CSS keeps the banner readable without becoming another overlay that steals the page.

.origin-banner {
  border: 2px solid currentColor;
  padding: 0.75rem 1rem;
  margin-bottom: 1rem;
}

.origin-banner:focus {
  outline: 3px solid currentColor;
  outline-offset: 2px;
}

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
}

Do not put aria-busy on the document root during failover. Busy on #app hides the consent controls you just rendered, which is how I created the original trap.

Expected UI states

Idle: composer enabled, no banner, live region quiet after the last completion.
Local streaming: banner says “this device,” Stop is enabled, composer disabled but not aria-hidden.
Failover: banner asks for consent, initial focus on “Send remotely,” live region fires once.
Remote streaming: banner says “remote server,” same keyboard map as local streaming.
Cancel or decline: polite copy once, focus back on the textarea, draft text preserved.

If any of those states reuse a single “loading” string, you are back to the original bug. Would you ship a checkout that retried against another processor without naming it? Then do not ship chat that way either.

Keyboard and screen-reader regressions

Run these as regressions, not as a one-off demo day. I write the exact transition into the bug title so the next failure is comparable.

Submit with local failure. Focus must land on the consent primary button, not the overlay root.
Press “Stay on this device.” Focus must return to the composer, not the document body.
Confirm remote send. The live region must mention remote origin once, not on every token.
Tab during remote streaming. The origin banner must be reachable without a pointer.
Activate Stop. Streaming ends, the banner clears, and the composer must accept keys.

Do not announce every token. Token-level live regions bury the origin change under a speech queue nobody can interrupt cleanly. If your reader is still speaking fragments when consent appears, the user will confirm a prompt they never heard.

Environment-specific QA matrix

I am not claiming conformance from this matrix. I am claiming a reproducible path you can fail on purpose, with browser, OS, and AT versions recorded beside the transition.

Environment	What I check	Failed transition to log
NVDA + Chrome on Windows	polite live region on consent, banner in browse mode	local fail → needs-consent
VoiceOver + Safari on macOS	focus move to confirm, then back to textarea	consent-no → cancelled
Keyboard only, Firefox	tab order banner → stop → no trap	streaming-remote
Reduced motion	no overlay animation that implies a different state	needs-consent

Invite a teammate to reproduce with their versions plus the exact transition that failed. “It works on my laptop” is not a QA record when the bug is a silent host change.

What this does not solve

This pattern is for product teams who already stream chat in a browser and who sometimes leave the device. It is not a privacy policy, a DPA, or a substitute for documenting retention on the remote host. The sketch also skips auth, rate limits, and model catalogs on purpose.

Do not use this approach if your product never leaves the device. Do not use it if legal consent must be a separately captured workflow with audit storage. I am not attaching quotas, hardware, duration, or benchmark numbers to the free server path, because those claims would be invented here.

The accessibility fix is the state machine, the tab-stop banner, and the focus return. A reachable remote origin only made the failing transition cheaper to replay. If you want that replay without standing up your own box, try the free model access and free server option against the consent states above, and log the AT combo that still misses the origin change.

DEV Community: babycat

A Stream Retry Needs a Fresh Announcement, Not a Rewritten Transcript

The failure I could hear but not see

A state table before any more guesses

How I traced the stale node

Three checks, in the order I ran them

The fix: split the transcript from the announcement

Names, focus, and what I refuse to announce

Where a slow first byte made the race obvious

A QA matrix you can run this afternoon

Transitions that must not glue

Who should skip this pattern

What I want you to reproduce

A Quiet Stream Close Needs a Focusable Diagnostics Panel, Not Console Logs

The interaction that actually failed

I guessed the wrong layer first

The state table I wish I had drawn on day one

Minimal reproduction

What I changed in the real control

Keyboard and screen-reader regressions I now run

Environment matrix

Limitations, and who should not copy this blindly

An In-Browser Agent Needs a Consent Gate You Can Tab Through, Not a Silent Fetch

The interaction that failed

State table before any ARIA

Symptom to root cause

Probe 1: keyboard-only, mouse unplugged

Probe 2: document.activeElement on every transition

Probe 3: screen-reader speech log

Probe 4: the consent flag race

The fix: a consent gate with an abort owner

What I wired around the fetch

Where a free completion endpoint actually helped

Expected UI states

Keyboard and screen-reader regressions

Limitations, and who should not copy this

What I would check tomorrow morning

Hidden-Tab Streams Need a Visibility Abort, Not a Frozen Generating Label

The frozen Stop I came back to

State table before any ARIA

Reproducing the death without a mock stream

Root cause: generating outlived the network

A typed visibility owner

Focus, announcements, and a retry that does not auto-fire

Environment-specific QA matrix

What this will not save you from

Test Streaming Markdown for Transient Headings and Half-Written Links

The interaction that actually broke

State table before any ARIA

Debugging technique: freeze the chunk, not the screenshot

Dump headings after every token

Replay at rude cadences

Root cause: a full parser on an incomplete buffer

The fix: commit closed blocks, keep a non-semantic draft

Expected UI states

A slow stream is the test fixture, not a luxury

Minimal reproduction

Proposed QA matrix

Limitations, and who should skip this

What I want you to reproduce

An Empty Model Handshake Needs a Recoverable Error, Not a Disabled Composer

The failure, without the happy path

Expected UI states

Debugging order I now refuse to skip

Keyboard reproduction

Network truth versus UI truth

Root cause

The fix: name the handshake

What the DOM must do when the first byte never comes

Why two real endpoints made the bug honest

Proposed QA matrix

Limitations, and who should skip this

What I want you to reproduce

Build an Accessible Waiting-for-Tokens Control With Stall Recovery

The failure I was actually debugging

Symptom: the dots lied

Hypotheses I wrote down before touching CSS

Root cause: no owner for “nothing has streamed yet”

The typed states I should have started with

A runnable wait-state harness

Probe 2: `document.activeElement` on every transition