DEV Community: babycat

Unexpected End of JSON Input: Debugging a Tool Call That Streamed Half a Brace

babycat — Mon, 26 Oct 2026 11:06:32 +0000

I pressed Run on a tool-calling chat panel, watched the model stream {"query":"dev.to tag:accessibility into the preview, and then the whole panel blinked out of existence. My composer had a half-typed follow-up in it, the model was still billing tokens somewhere, and the only thing left on screen was a red box that said Unexpected end of JSON input. The user could not tell whether the search had run, whether it had been cancelled, or whether retrying would run it twice.

That last sentence is the actual bug, by the way. The exception was just the messenger. What follows is the retrospective: the state model I should have written first, a fixture you can replay with no API key, the two root causes, and the accessibility contract that keeps a half-finished tool call honest.

The state table I wish I had drawn first

Before touching the parser, write down every terminal shape a streamed tool call can land in. Mine was missing half of them, which is why the UI had no branch to render.

What the stream does	Old UI	New UI
Arguments arrive in 40 fragments	throws on fragment 1	`streaming` → `partial` preview
Last fragment closes the JSON	never reached	`complete`, tool may run
Server stops with `finish_reason: "length"`	throws, panel unmounts	`truncated`, retry offered, tool never runs
Connection drops mid-object	throws, draft lost	`invalid`, buffer preserved verbatim
User cancels	panel unmounts	`cancelled`, buffer kept for inspection

Two of those rows are not errors at all, and treating them as errors is what cost me the draft. truncated is a budget decision made upstream. cancelled is a user decision made locally. Neither deserves an exception boundary.

Reproduce it without a key, a quota, or a network

I do not want my regression tests to depend on a provider being up, so I record one stream once and replay it as a fixture forever. Here is the smallest harness I use, in Node with no dependencies:

mkdir -p fixtures && node replay.mjs fixtures/truncated-toolcall.sse

// replay.mjs
import { readFileSync } from "node:fs";

function* events(path) {
  const lines = readFileSync(path, "utf8").split("\n");
  for (const line of lines) {
    if (!line.startsWith("data:")) continue;
    const payload = line.slice(5).trim();
    if (payload === "[DONE]") return;
    yield JSON.parse(payload);
  }
}

for (const event of events(process.argv[2])) {
  const choice = event.choices?.[0];
  const args = choice?.delta?.tool_calls?.[0]?.function?.arguments;
  if (args) console.log("chunk", JSON.stringify(args));
  if (choice?.finish_reason) console.log("finish", choice.finish_reason);
}

The fixture itself is four lines of hand-written SSE that imitate the shape, not a recording of anyone's model. Yes, that is a constructed transcript, and I label it that way so nobody mistakes it for a benchmark.

data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\"query\":\"dev.to tag:acc"}}]}}]}

data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"essibility\",\"limit\":2"}}]}}]}

data: {"choices":[{"delta":{},"finish_reason":"length"}]}

data: [DONE]

Run that and the bug is obvious in about ten seconds: arguments is a string fragment stream, and I was calling JSON.parse on each fragment as if it were a document.

Root cause one: I parsed a delta like a document

The shipped version was three lines, and all three were wrong in the same way:

const args = event.choices?.[0]?.delta?.tool_calls?.[0]?.function?.arguments;
const parsed = JSON.parse(args); // 💥 on the very first fragment
render(parsed);

Look at the failure order. It did not break on the last brace; it broke on the first character of the first fragment, because {"query":"dev is not JSON. That is why the error boundary fired while the model was still producing the first key, and why the panel died before any output existed. A per-chunk parse is a category error, not an edge case.

The fix is a buffer plus a scanner that knows where it is inside the object. It tracks string state, escapes, and an open-bracket stack, then closes what is still open — bounded, because an unbounded repair is a fuzzer's dream.

export const MAX_DEPTH = 32;

export function scan(buffer) {
  let inString = false, escaped = false;
  const stack = [];
  for (const ch of buffer) {
    if (escaped) { escaped = false; continue; }
    if (ch === "\\") { escaped = true; continue; }
    if (ch === '"') { inString = !inString; continue; }
    if (inString) continue;
    if (ch === "{" || ch === "[") stack.push(ch);
    else if (ch === "}" || ch === "]") {
      const open = stack.pop();
      if (!open || (ch === "}") !== (open === "{")) return { ok: false, reason: "unbalanced" };
    }
  }
  return { ok: true, inString, stack };
}

export function repair(buffer) {
  const s = scan(buffer);
  if (!s.ok) return { status: "invalid", reason: s.reason };
  if (!s.stack.length && !s.inString) return { status: "complete", text: buffer };
  if (s.stack.length > MAX_DEPTH) return { status: "invalid", reason: "too-deep" };
  let text = s.inString ? buffer + '"' : buffer;
  for (let i = s.stack.length - 1; i >= 0; i--) text += s.stack[i] === "{" ? "}" : "]";
  try { return { status: "partial", text, value: JSON.parse(text) }; }
  catch { return { status: "invalid", reason: "repair-failed" }; }
}

That is an excerpt, not the whole reducer, but it carries the invariant that matters: repair never throws and never returns a value it did not successfully parse. Everything else is presentation.

Root cause two: `finish_reason: "length"` is not an exception

My second mistake was upstream of the parser. A truncated tool call is a known terminal state with a known cause, and I had no type for it, so it fell through to the error path. Here is the shape I use now, typed so the compiler nags me about missing branches:

type ToolCall =
  | { status: "streaming"; buffer: string }
  | { status: "partial"; buffer: string; preview: string }
  | { status: "complete"; value: unknown }
  | { status: "truncated"; buffer: string; preview: string | null }
  | { status: "invalid"; buffer: string; reason: string }
  | { status: "cancelled"; buffer: string };

When the terminal event says length, the reducer moves to truncated, keeps the buffer for inspection, and shows a retry that re-sends the same request under a new abort scope. The tool itself is never invoked with repaired arguments, and that distinction is the whole safety story: a repaired object is a display artifact, never an executable one.

The accessibility contract for half-finished output

A streaming preview is a live region that screams forty times and says nothing useful. I settled on this contract, and it survived screen-reader passes because it announces almost never:

The partial preview sits in a region with aria-live="off" and aria-busy="false"; it updates visually without interrupting speech.
One role="status" node announces exactly once per terminal state — complete, truncated, invalid, cancelled.
The composer keeps focus through every transition, because nothing here replaces the subtree that owns the textarea.
Retry and Cancel are real buttons in DOM order after the preview, reachable by Tab, and Cancel stays pointer-independent during streaming.
Truncated and invalid states expose the raw buffer in a disclosure widget, since debugging output is a feature for the person hitting it.

Accessible names matter here too: "Retry" alone is ambiguous when two tool calls are on screen, so the label includes the tool name and the reason.

Where I reproduced it, and why that matters

I originally hit this while building against a cheap endpoint and could not afford to keep re-running a long tool prompt after every change. I moved the reproduction to MonkeyCode, an open-source coding agent project that at the time of writing advertises two things relevant to this loop: free model access and a free server option, with a free allowance of 10 million tokens listed on the project page — check the repo for the current terms, because allowances are exactly the kind of number that changes.

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

What that gave me was not magic, it was iteration speed: I could replay the fixture against a real streamed endpoint dozens of times in one afternoon without rationing calls. The free server option mattered for a duller reason — I needed a process that stays up long enough to be killed mid-stream, and killing a local tunnel is a much worse test than killing a small deployed one.

A QA matrix, because one browser lies

Transition	What I check	Tooling
streaming → partial (×40)	no announcement per chunk, no layout jump	NVDA + Firefox, VoiceOver + Safari
partial → complete	one status announcement, tool may run	both of the above
streaming → truncated	retry focused after announcement, buffer visible	keyboard only
streaming → cancel	buffer retained, no orphan fetch on reload	DevTools network throttle
invalid mid-object	error text names the reason, draft intact	screen reader + manual

Run the keyboard rows with the mouse physically unplugged. I am serious; that is how I found that my Cancel button was inside the preview that gets replaced on each chunk.

Limitations, and who should skip this

Bounded repair produces plausible objects, and plausible is dangerous: a repaired {"limit":2 becomes {"limit":2} and looks authoritative. If your tool call writes to a database, charges a card, or sends an email, do not use this path for execution at all — validate the complete payload against a schema and fail closed.

Also skip the replay harness if your failures are timing-dependent rather than shape-dependent; a deterministic fixture will happily hide a race. And if you need hard guarantees about concurrency, do not read a free-tier endpoint as a load-testing rig — that is not what it is for, and I would not trust anyone's numbers about it, including mine.

The question I now ask before every stream

Which of these states has no branch in my UI? It takes two minutes to answer and it would have saved me an afternoon, a lost draft, and one very confused user who thought their search had silently run.

If you want to replay this fixture against a live stream without a paid key, the free model access on MonkeyCode is the least wasteful loop I have found so far. And if you hit a variant I missed — a provider that closes the object but never sends finish_reason — send me the browser, OS, assistive tech version, and the exact chunk where it broke, and I will add it to the matrix.

The Health Check Said 200 While the Model Said 401: Debugging a Silent Endpoint Fallback

babycat — Tue, 20 Oct 2026 09:12:27 +0000

I have watched the same failure three times this month, and it never looks like the same failure at first glance.

Someone wires an AI coding assistant to an endpoint they copied out of a README, sends one prompt, and gets a spinner that turns for thirty seconds before collapsing into the words "Request failed." The console is clean, the network tab has a response worth reading, and the UI tells them none of it.

Is it the key? The URL? The model id? The proxy? The stream flag? The browser? Six suspects, one vague sentence on screen, and no way to bisect them from inside the app.

The walkthrough below is a reconstruction of that class of bug, written so you can execute every step against your own endpoint. It is not a benchmark and it is not a product review; it is a debugging retrospective with a runnable harness at the end.

Why this failure got common in the last few months

The number of AI endpoints a frontend developer is expected to juggle went up, and the amount of configuration discipline per endpoint went down. A single app now resolves a base URL from a UI field, a shell variable, a .env file, and a hard-coded default, and whichever one wins is usually decided by accident.

I have been testing this with MonkeyCode, an open-source AI coding project whose operator states that you can use free model access (up to 10 million tokens) and a free server option. Those two paths hand you two different endpoints, which is exactly the condition that produces the bug below.

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

To be clear about scope: the free tier is operator-supplied availability, not a guarantee, and I am not quoting any quota, model list, or uptime number I could not re-verify on the project's own page at publication time. Re-check the current terms before you build a workflow on top of any free tier.

The symptom, written as a state table

Before touching code, write down what each layer reports. In the incident I keep seeing, the layers disagree in a very specific way:

Layer	What it reports	What it means
`GET /health`	`200 OK` in 40 ms	The gateway process is alive
`POST /v1/chat/completions`	`401` with a JSON body	Your key is not valid for this route
App fetch wrapper	`ok === false`	Truth
App UI	"Request failed."	Useless
User	Reloads the page and tries again	Wasted afternoon

The health endpoint answered a different question than the one the user was asking. That is the whole bug, and everything below is mechanical: prove it, isolate it, then make the UI incapable of lying that way again.

Step 1: Stop trusting the app and run the request yourself

Open a terminal and send the exact request the app sends. A three-rung curl ladder separates reachability, authorization, and first-byte timing, which are three completely different failures that the browser collapses into one.

export MC_BASE="https://your-endpoint.example.com"
export MC_KEY="sk-..."        # from a local .env, never committed
export MC_MODEL="your-model-id"

BASE="${MC_BASE%/}"          # strip one trailing slash, not all of them

# Rung 1: DNS, TLS, and whether the host answers at all
curl -sS -o /dev/null -w 'health: %{http_code} in %{time_total}s\n' "$BASE/health"

# Rung 2: auth and path, non-streaming, one token of output
curl -sS -D /tmp/headers.txt -o /tmp/body.txt \
  -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $MC_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MC_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"max_tokens\":1}"
head -n 1 /tmp/headers.txt; head -c 300 /tmp/body.txt; echo

# Rung 3: streaming on, measure time to first byte
curl -sS -N -o /dev/null -w 'ttfb: %{time_starttransfer}s total: %{time_total}s\n' \
  -X POST "$BASE/v1/chat/completions" \
  -H "Authorization: Bearer $MC_KEY" -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MC_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}],\"stream\":true,\"max_tokens\":1}"

In the case I keep seeing, rung 1 returns 200 and rung 2 returns 401. That single pair of lines ends the guessing phase, and it costs you about eight seconds.

Reading rung 3 without over-reading it

-N disables curl's own buffering, so a fast ttfb with a slow total means streaming genuinely works end to end. A slow ttfb means something between you and the model is holding bytes back, and no amount of client-side work will fix it. Keep those two conclusions separate, because mixing them is how people end up rewriting a perfectly good render loop.

Step 2: Dump the config the app actually resolved

The 401 was not a credential problem in the end. The app had read OPENAI_BASE_URL from a shell profile it inherited before the user typed anything into the settings panel, and the explicit value lost the precedence fight silently.

Fix the resolution order first, then log it exactly once at startup:

// config.js — loud, ordered, and logged once
const sources = [
  ['ui',    process.env.MC_BASE_URL],
  ['shell', process.env.OPENAI_BASE_URL],
  ['file',  readConfigFile()?.baseUrl],
];

const resolved = sources.find(([, value]) => typeof value === 'string' && value.length > 0);
if (!resolved) {
  throw new Error(`No base URL configured. Checked: ${sources.map(([name]) => name).join(', ')}`);
}

console.info(`[config] base=${resolved[1]} source=${resolved[0]}`);

A silent fallback is worse than a missing value, because a missing value stops you at boot and a fallback follows you into production. If the user set something explicitly, a lower-precedence source should never override it, not even when the explicit value looks malformed.

The trailing `/v1` trap

Most endpoints accept https://host/v1/chat/completions, and a large number of copy-pasted configs store https://host/v1 as the base. Join those two naively and you request https://host/v1/v1/chat/completions, which typically returns a 404 that reads like a model problem and is not one.

const joinUrl = (base, path) => {
  const b = base.replace(/\/+$/, '');
  const p = path.replace(/^\/+/, '');
  // if the base already ends in /v1, drop the duplicate segment from the path
  const deduped = b.endsWith('/v1') && p.startsWith('v1/') ? p.slice(3) : p;
  return `${b}/${deduped}`;
};

Route every request through one joiner. One function is testable; twelve template literals scattered across a codebase are not.

Step 3: Replace the health check with a readiness probe

A boolean fetch('/health').then(r => r.ok) answers "is a process listening," which nobody has ever needed to know. What you want is a probe that performs a minimal real completion and classifies the failure into something the UI can say out loud.

const STATUS_REASONS = {
  401: 'auth', 403: 'auth',
  404: 'path',
  429: 'rate',
  500: 'server', 502: 'server', 503: 'server', 504: 'server',
};

export async function probe({ baseUrl, apiKey, model, timeoutMs = 8000 }) {
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), timeoutMs);
  const started = performance.now();

  try {
    const res = await fetch(`${baseUrl.replace(/\/+$/, '')}/v1/chat/completions`, {
      method: 'POST',
      signal: ac.signal,
      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
      body: JSON.stringify({
        model,
        messages: [{ role: 'user', content: 'ping' }],
        max_tokens: 1,
        stream: false,
      }),
    });

    const ms = Math.round(performance.now() - started);
    const text = await res.text();

    if (!res.ok) {
      return { ok: false, reason: STATUS_REASONS[res.status] ?? 'server', status: res.status, ms, detail: text.slice(0, 200) };
    }

    let json;
    try { json = JSON.parse(text); }
    catch { return { ok: false, reason: 'server', status: res.status, ms, detail: 'non-JSON body' }; }

    const content = json?.choices?.[0]?.message?.content;
    if (typeof content !== 'string' || content.trim() === '') {
      return { ok: false, reason: 'empty', status: res.status, ms };
    }

    return { ok: true, status: res.status, ms };
  } catch (err) {
    const ms = Math.round(performance.now() - started);
    return { ok: false, reason: ac.signal.aborted ? 'timeout' : 'network', status: 0, ms, detail: String(err) };
  } finally {
    clearTimeout(timer);
  }
}

Two notes on honesty rather than cleverness. A probe spends tokens, so keep max_tokens at 1 and run it on session start or an explicit "Test connection" click, never per keystroke. If your provider enforces a larger floor than 1, raise it to the smallest accepted value and say so in a code comment, because the next maintainer will assume 1 works everywhere.

The empty branch is the one that saves the most time in practice. A proxy that rewrites your model alias happily returns 200 with choices: [], and an app that only checks res.ok renders a blank bubble with no error at all.

Step 4: Map every transport outcome to one UI state

Once the probe can classify, the client should not be allowed to improvise. This table is the whole contract between transport and screen, and I keep a copy of it in the repository next to the fetch wrapper:

Probe result	Visible UI	Screen reader	Retry policy
`ok`	normal composer	silent	n/a
`auth`	"This key was rejected by `host`" + link to settings	assertive alert once	blocked until edited
`path`	"Endpoint path looks wrong (404)"	assertive alert once	blocked
`rate`	"Rate limited — try again shortly"	polite status once	enable after `Retry-After` if present
`server`	"Endpoint error, one automatic retry"	polite status once	one automatic retry, then manual
`timeout`	"No response in 8s" + Cancel	polite status once	manual
`empty`	"The model returned an empty reply"	assertive alert once	manual

The accessibility rules that keep that table honest

Three rules matter more than the table itself, because a table is easy to write and easy to violate in a status component.

Announce the transition, not the timer. A live region that updates every second while waiting turns a slow request into a screen-reader hostage situation.
Only alert for states the user must act on. Auth and path failures block everything, so they earn assertiveness; slow networks do not.
Put the host and the next action in the text. "Request failed" costs a debugging session; "This key was rejected by api.example.com" costs nothing.

Step 5: Wrap it in a typed state machine

Types are the cheapest way to stop the UI from inventing a seventh state nobody designed. Four phases cover the whole lifecycle, and the blocked phase carries the reason as a union rather than a string.

type BlockReason = 'auth' | 'path' | 'rate' | 'server' | 'timeout' | 'empty' | 'network';

type Session =
  | { phase: 'idle' }
  | { phase: 'probing' }
  | { phase: 'ready'; endpoint: string; model: string }
  | { phase: 'blocked'; reason: BlockReason; host: string; retryAfterMs?: number };

const timeoutBudget = { connectMs: 3000, firstTokenMs: 8000, totalMs: 60000 };

In practice I use the same object to drive both the visual state and the announcement copy, so a new reason cannot ship without a message. If you add a variant and the build still passes, you forgot an exhaustive switch somewhere, and TypeScript will tell you where.

The timeout budget is deliberately three numbers instead of one. A connect timeout tells the user their network is the problem, a first-token timeout points at buffering or model queueing, and a total timeout points at a runaway generation you should let them cancel rather than silently truncate.

A verification matrix you can run in an afternoon

Reproducing a bug is half the job; proving you fixed the whole class is the other half. These six rows are the ones that have caught real regressions for me:

Scenario	Setup	Expected probe	Expected UI
Direct connection	no proxy	`ok`	composer enabled
Corporate proxy	`HTTPS_PROXY` set, TLS intercepted	`network` or `server`	error names the host, no infinite spinner
Wrong key	key from another project	`auth`	alert + settings link, retry blocked
Doubled path	base ends in `/v1`	`path`	alert, no auto-retry loop
Idle free endpoint	first request after a quiet period	slow `ok`	one polite status, then success
Empty rewrite	proxy strips `choices`	`empty`	explicit empty reply message

Run the matrix with the network panel open and once with a screen reader on. The two passes catch different bugs, and the screen-reader pass is the one that surfaces double announcements you will never notice visually.

Limitations, and who should not do this

This workflow is a debugging aid, not an architecture. A single probe proves one path at one moment, and it will happily pass while a streaming request through the same endpoint still stalls on a buffering proxy.

Please do not build on it if any of these apply:

You handle regulated data. A shared free endpoint is not the place to send it, regardless of how good the ergonomics are.
You need reproducible evaluation runs. Probe-and-retry logic hides model drift instead of pinning it.
You need an availability commitment. Free tiers are operator-supplied and can change; keep a second configured endpoint and a documented switch.
You only want a demo that looks fast. Skip the probe and accept that your first real user becomes your health check.

If you want a second endpoint to run the curl ladder against, the free model access and free server option in MonkeyCode are a low-friction way to get one, and having two configs is precisely what makes precedence bugs visible. Run the three rungs against both, and tell me which rung fails first.

When you report a reproduction, include your Node version, curl version, whether a proxy sits in the path, and the exact transition that broke — probe to first token, or first token to done. That detail is what turns "it doesn't work" into a bug somebody can actually close.

The Retry Never Got Announced: Debugging a Stuck aria-busy in a Streaming Chat

babycat — Mon, 19 Oct 2026 07:45:45 +0000

A support message landed in my inbox with a detail I almost skipped: the reply was there on screen, but the screen reader said nothing at all. It only happened when the first attempt failed and the person pressed Retry. Sighted testers, including me, had shipped that build a day earlier and called it done.

That pattern — visible text, silent assistive tech, one specific path — is usually a live region problem. But the live region was present, correctly labelled, and working on the happy path. So what else can make a region go quiet while its text keeps growing?

This is the story of a single stale attribute, two code paths that both claimed ownership of it, and the state table I should have written before the first line of streaming code.

The report was suspiciously specific

The reporter described three details, and every one of them mattered:

First answer streams in, then fails mid-sentence with an inline error.
Pressing Retry produces a complete answer that looks normal.
VoiceOver stays silent for the retry, but announces the error message fine.

Notice what the third point rules out. The live region is not broken, because it spoke the error. Announcements are not globally disabled, because the person heard something. The failure is scoped to the retried message node, which means the bug lives in the lifecycle of that node, not in the live region configuration.

First hypothesis: "we forgot the live region" (wrong)

My first guess cost me twenty minutes. I assumed the retry re-rendered the message into a fresh element and lost aria-live on remount. I added a MutationObserver to the list and logged every attribute change during a failed-then-retried stream.

The log told a different story. Attribute changes on the message element during attempt one: aria-busy="true". During the error: nothing. During the retry: nothing. During completion: nothing.

[attempt 1] aria-busy -> true
[error]     (no attribute changes)
[retry]     (no attribute changes)
[done]      (no attribute changes)

So aria-busy went true and never came back. A busy live region is a region whose updates assistive technology may defer until the busy state clears — which is precisely the behaviour we were seeing. The region was not silent because it was misconfigured; it was silent because we had told it, permanently, "I am still working."

Reproducing it in one file

I could not debug this against a provider that only fails on Tuesdays. I needed a stream that reliably dies after N tokens, so I wrote a forty-line endpoint with a failAfter query parameter and no dependencies.

// server.mjs — node server.mjs
import { createServer } from 'node:http';

const TOKENS = ['Accessible ', 'streams ', 'announce ', 'one ', 'settled ', 'state.'];

createServer((req, res) => {
  const url = new URL(req.url, `http://${req.headers.host}`);
  if (url.pathname !== '/stream') return void res.writeHead(404).end('not found');

  const failAfter = Number(url.searchParams.get('failAfter') ?? -1);
  const delay = Number(url.searchParams.get('delay') ?? 120);

  res.writeHead(200, {
    'content-type': 'text/event-stream',
    'cache-control': 'no-cache, no-transform',
    connection: 'keep-alive',
    'x-accel-buffering': 'no',
  });

  let i = 0;
  const timer = setInterval(() => {
    if (failAfter >= 0 && i === failAfter) {
      clearInterval(timer);
      res.write('event: error\ndata: {"message":"upstream stopped"}\n\n');
      return void res.end();
    }
    if (i >= TOKENS.length) {
      clearInterval(timer);
      res.write('event: done\ndata: {}\n\n');
      return void res.end();
    }
    res.write(`data: ${JSON.stringify({ t: TOKENS[i++] })}\n\n`);
  }, delay);

  req.on('close', () => clearInterval(timer));
}).listen(process.env.PORT || 8080);

You need a stream that dies on demand and a URL you can open from a phone, a VM, and a colleague's laptop. That is where MonkeyCode earned its place in this workflow: the free model access let me swap upstreams to check whether the stream shape was the provider's fault, and the free server option was enough to host this endpoint behind a real URL instead of localhost. The token allowance I have seen quoted is 10 million, which I am taking from the operator rather than measuring myself.

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

The buggy client, in eleven lines

The original code is short, readable, and wrong in a way that reviews never catch:

// ❌ the bug: imperative busy, cleared only on the happy path
async function send(prompt, row) {
  row.setAttribute('aria-busy', 'true');
  const res = await fetch(`/stream?failAfter=3`);
  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let text = '';
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    text += value;
    row.textContent = text;
  }
  row.setAttribute('aria-busy', 'false');
}

// ❌ and retry(): pasted from send(), missing the attribute line entirely
async function retry(row) {
  const res = await fetch(`/stream`);
  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let text = '';
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    text += value;
    row.textContent = text;
  }
}

Attempt one sets the attribute, then throws before the clear line. retry() streams into the same row and never touches the attribute, because the line was lost in the copy-paste. Two functions own one attribute, and the second one only knows half the contract.

Why the happy path hid it

On a successful first attempt, aria-busy flips true and then false, so announcements work. On a failed first attempt it stays true, and the retry inherits a region that is permanently busy. Is that a bug you would find by clicking around? Almost certainly not — the pixels are identical.

The state table I should have written first

Before touching code, I wrote the table. Every column is something a user can observe, and every row must be true at the same time:

State	`aria-busy`	Live region	Focus
`idle`	false	empty	composer
`streaming`	true	silent (tokens are not announced)	Stop stays reachable
`complete`	false	final text, once	composer
`error`	false	"Reply stopped. Retry available."	Retry is next in tab order, not focused
`cancelled`	false	"You stopped this reply."	composer

Two rules fall out of that table. First, aria-busy is true in exactly one state. Second, it must be false in every terminal state, including the ones reached by failure.

Fix: derive aria-busy, never set it

When a value must be true in exactly one state, stop storing it as its own value. I replaced the imperative attribute writes with a typed reducer and derived aria-busy from the state on every render.

type ChatState =
  | { kind: 'idle' }
  | { kind: 'streaming'; id: string; text: string; attempt: number }
  | { kind: 'complete'; id: string; text: string; attempt: number }
  | { kind: 'error'; id: string; text: string; error: string; attempt: number }
  | { kind: 'cancelled'; id: string; text: string; attempt: number };

type Event =
  | { type: 'send'; id: string }
  | { type: 'token'; text: string }
  | { type: 'done' }
  | { type: 'fail'; error: string }
  | { type: 'cancel' }
  | { type: 'retry' };

export const isBusy = (s: ChatState) => s.kind === 'streaming';

export function reduce(state: ChatState, event: Event): ChatState {
  switch (event.type) {
    case 'send':
      return state.kind === 'streaming'
        ? state
        : { kind: 'streaming', id: event.id, text: '', attempt: 1 };
    case 'token':
      return state.kind === 'streaming' ? { ...state, text: state.text + event.text } : state;
    case 'done':
      return state.kind === 'streaming'
        ? { kind: 'complete', id: state.id, text: state.text, attempt: state.attempt }
        : state;
    case 'fail':
      return state.kind === 'streaming'
        ? { kind: 'error', id: state.id, text: state.text, error: event.error, attempt: state.attempt }
        : state;
    case 'cancel':
      return state.kind === 'streaming'
        ? { kind: 'cancelled', id: state.id, text: state.text, attempt: state.attempt }
        : state;
    case 'retry':
      return state.kind === 'error'?
        { kind: 'streaming', id: state.id, text: state.text, attempt: state.attempt + 1 }
        : state;
  }
}

Rendering then becomes a pure function of state, and there is no code path that can leave the attribute behind:

<li
  className="msg msg--assistant"
  aria-busy={isBusy(state) ? 'true' : 'false'}
>
  {state.kind !== 'idle' ? state.text : null}
</li>

Note that focus is untouched in every branch. On error, the live region speaks the message and the Retry button sits next in reading order; it does not grab focus and it does not move the caret. Users decide when to retry, not us.

Tests that would have caught it

The reducer is small, so the test is table-driven. It asserts the invariant, not a specific string, which means new states cannot quietly break it.

import test from 'node:test';
import assert from 'node:assert/strict';
import { reduce, isBusy, type ChatState, type Event } from './chat-machine.ts';

const run = (events: Event[]) => events.reduce<ChatState>(reduce, { kind: 'idle' });

const paths: Event[][] = [
  [{ type: 'send', id: 'm1' }],
  [{ type: 'send', id: 'm1' }, { type: 'done' }],
  [{ type: 'send', id: 'm1' }, { type: 'fail', error: 'upstream stopped' }],
  [
    { type: 'send', id: 'm1' },
    { type: 'token', text: 'partial' },
    { type: 'fail', error: 'upstream stopped' },
    { type: 'retry' },
    { type: 'done' },
  ],
  [{ type: 'send', id: 'm1' }, { type: 'cancel' }],
];

test('busy is true only while streaming, on every path', () => {
  for (const path of paths) {
    const end = run(path);
    assert.equal(isBusy(end), end.kind === 'streaming', path.map((e) => e.type).join(' > '));
  }
});

test('retry keeps partial text and increments the attempt', () => {
  const end = run([
    { type: 'send', id: 'm1' },
    { type: 'token', text: 'Accessible ' },
    { type: 'fail', error: 'upstream stopped' },
    { type: 'retry' },
  ]);
  assert.equal(end.kind, 'streaming');
  if (end.kind === 'streaming') assert.equal(end.text, 'Accessible ');
  if (end.kind === 'streaming') assert.equal(end.attempt, 2);
});

Run it with whichever TS runner you already have (npx tsx busy.test.ts), and wire it into CI next to your type check. One caveat worth saying out loud: automated accessibility scanners like axe will not catch this class of bug, because a stuck attribute is valid markup. The invariant test is doing the work a scanner cannot do.

A manual pass you fill in, not one I fill in for you

The stuck-attribute behaviour depends on the browser and the assistive technology, so I will not pretend my environment is yours. Here is the matrix I keep, with the transitions that matter most:

Failure mid-stream, then retry — the single most important case, and the one that started this post.
Failure with zero tokens received — does the error message still announce?
Cancel, then send a new prompt — does the old reply go quiet without replaying?
Two messages in flight — does the second one's busy state interfere with the first?
Retry with a screen reader in browse mode — does the virtual cursor stay where the person left it?

Log the browser, OS, AT name and version, plus the exact transition that failed. "It doesn't work in Safari" is unactionable; "Safari 18, macOS, VoiceOver, fail after three tokens, then Retry" is a bug report.

Limits, and who should skip this

A few honest boundaries on the approach above. If your chat surface is a vendor widget, patching around its internals is worse than filing upstream with this reproduction attached. If your message list also contains the composer or other interactive controls, do not put aria-busy on that container at all, because you will suppress more than one region. And if you cannot run even one manual screen-reader pass before shipping, the invariant test buys you correctness of state but not confidence in behaviour.

One more trend-shaped note. On-device browser AI features make this mistake easier to ship, because there is no flaky network to force your catch branch and no server error to disagree with your state machine. Fewer failures in development, more silent regions in production.

What I check first next time

A short checklist that would have saved me a day, and that I now paste into streaming PRs:

List every state and mark which one owns aria-busy.
Find every function that writes that attribute. If there is more than one, consolidate.
Force a failure after three tokens, then retry, before merging.
Assert the invariant in a unit test, not in a comment.
Do one manual screen-reader pass on the failure path specifically.

If you want to reproduce the failure without wiring a provider key, the fault-injecting endpoint plus a free model endpoint is enough of a setup to see the silent retry for yourself, and the free server option is plenty for a demo nobody else has to babysit. Tell me your browser, OS, and assistive-technology versions plus the exact transition that went quiet — I would rather extend the matrix than defend the fix.

A Retry Button Sent the Same Prompt Twice: Debugging Idempotency in a Streaming Chat

babycat — Sun, 18 Oct 2026 06:45:13 +0000

The bug report you will eventually get is short: “Retry sometimes gives me two answers.” The transcript looks normal until you notice two assistant bubbles with almost identical text and a duplicate “Generating response” announcement in the screen-reader log. Nothing threw an exception, so the console is useless. Where do you even start?

I reduce this class of failure to two requests and one question: is this retry the same user intent, or a new one? A retry after a dropped connection is the same intent. A regenerate after a successful answer is a new intent. When the client treats both as “send again,” you get duplicate work, duplicate announcements, and sometimes duplicate billing.

The failure is two different requests wearing one button

The state table I want on the wall before touching code:

User-visible state	What should exist	Common bug
Idle	One send action, no request id	Id reused across prompts
Sending	Send is busy, one key	CSS-only disable lets double Enter through
Streaming	Partial text plus stop control	Retry appears while stream is open
Failed before first token	Same key, visible error	New key on every retry
Failed after partial token	Same key, explicit “retry from start” copy	Partial plus full answer mixed
Retry succeeds	One answer, one completion message	Old error stays, focus disappears

The table makes the root cause less mysterious. The server cannot deduplicate two requests if the client gives them different identities. The button also cannot prevent a second submit if it is disabled only in CSS. Those are separate defects, and fixing one leaves the other alive.

Reproduce it with one idempotency key

The smallest server I use for this review is an in-memory ledger with an SSE response. It is not production storage, but it makes the contract visible. Node 20 or newer is enough; there are no dependencies.

// server.mjs
import { createServer } from 'node:http';
import { createHash } from 'node:crypto';

const ledger = new Map();
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function sendEvent(res, event, data) {
  res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
}

function tokenize(prompt) {
  return ['A ', 'cached ', 'answer ', 'for: ', prompt];
}

const server = createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/api/chat') {
    res.writeHead(404).end('Not found');
    return;
  }

  let body = '';
  for await (const chunk of req) body += chunk;

  let payload;
  try {
    payload = JSON.parse(body || '{}');
  } catch {
    res.writeHead(400, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: 'invalid json' }));
    return;
  }

  const prompt = typeof payload.prompt === 'string' ? payload.prompt : '';
  const key = req.headers['idempotency-key'];
  if (!prompt || typeof key !== 'string' || key.length < 8) {
    res.writeHead(400, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: 'missing prompt or idempotency key' }));
    return;
  }

  const fingerprint = createHash('sha256').update(prompt).digest('hex');
  const prior = ledger.get(key);

  if (prior && prior.fingerprint !== fingerprint) {
    res.writeHead(422, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: 'key reused for a different prompt' }));
    return;
  }

  if (prior?.state === 'running') {
    res.writeHead(409, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ error: 'request already running' }));
    return;
  }

  if (prior?.state === 'done') {
    res.writeHead(200, {
      'content-type': 'text/event-stream',
      'cache-control': 'no-cache',
      'idempotent-replay': 'true',
    });
    sendEvent(res, 'token', prior.text);
    sendEvent(res, 'done', {});
    res.end();
    return;
  }

  ledger.set(key, { state: 'running', text: '', fingerprint });
  res.writeHead(200, {
    'content-type': 'text/event-stream',
    'cache-control': 'no-cache',
    connection: 'keep-alive',
  });

  let text = '';
  for (const token of tokenize(prompt)) {
    await sleep(250);
    text += token;
    sendEvent(res, 'token', token);
  }

  ledger.set(key, { state: 'done', text, fingerprint });
  sendEvent(res, 'done', {});
  res.end();
});

server.listen(8787, () => console.log('http://localhost:8787'));

Run it, then fire two requests with the same key at the same time:

node server.mjs

URL=http://localhost:8787/api/chat
KEY=6f1c2f6e-7a1b-4a4e-9d1a-111111111111
BODY='{"prompt":"accessibility"}'

for i in 1 2; do
  curl -sS -D headers-$i.txt -o body-$i.txt -X POST $URL -H 'content-type: application/json' -H "idempotency-key: $KEY" -d "$BODY" &
done
wait
grep -iE 'HTTP/|idempotent-replay' headers-*.txt

Expected result: one 200, one 409. Run the same curl again after the stream finishes, and you should see idempotent-replay: true. The second request does not call the generator again. That is the whole trick, and it has nothing to do with a particular model vendor.

Now break it on purpose. In the client, generate a new key inside the retry handler and remove the in-flight guard. The server sees two keys, so it treats them as two user intents. Two answers are then correct behavior for the server and wrong behavior for the product.

The client fix: reuse the key, guard the click

The key belongs to the message attempt, not to the fetch call. Create it when the user submits a new prompt. Reuse it for retries caused by a network error, a double Enter, or a refresh that resumes the same attempt. Create a new key only when the user chooses “Regenerate” after a completed answer.

The identity diagram is small enough to keep beside the code:

new prompt     ──► key A ──► POST ──► 200 stream ──► done
network retry  ──► key A ──► POST ──► 200 replay (same answer)
regenerate     ──► key B ──► POST ──► 200 stream (new answer)

Here is the smallest client state I use. The HTML keeps the retry control in the document and uses aria-disabled instead of disabled, so focus does not vanish mid-interaction.

<form id='chat'>
  <label for='prompt'>Prompt</label>
  <textarea id='prompt' required></textarea>
  <button id='send' type='submit'>Send</button>
</form>
<p id='status' role='status'></p>
<section id='answer' hidden aria-labelledby='answer-heading'>
  <h2 id='answer-heading' tabindex='-1'>Answer</h2>
  <p id='answer-text'></p>
  <button id='retry' type='button' aria-describedby='status' hidden>Retry</button>
</section>

<script>
  const form = document.querySelector('#chat');
  const promptEl = document.querySelector('#prompt');
  const send = document.querySelector('#send');
  const retry = document.querySelector('#retry');
  const statusEl = document.querySelector('#status');
  const answer = document.querySelector('#answer');
  const answerText = document.querySelector('#answer-text');
  const answerHeading = document.querySelector('#answer-heading');

  let requestKey = null;
  let inFlight = false;

  function setBusy(isBusy) {
    inFlight = isBusy;
    send.toggleAttribute('aria-disabled', isBusy);
    retry.toggleAttribute('aria-disabled', isBusy);
  }

  async function post(prompt) {
    if (inFlight || !requestKey) return;
    setBusy(true);
    statusEl.textContent = retry.hidden ? 'Sending.' : 'Retrying the same request.';

    try {
      const response = await fetch('/api/chat', {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          'idempotency-key': requestKey,
        },
        body: JSON.stringify({ prompt }),
      });

      if (response.status === 409) {
        statusEl.textContent = 'That request is still running. Wait for the current answer.';
        return;
      }
      if (!response.ok) throw new Error(`HTTP ${response.status}`);

      answer.hidden = false;
      answerText.textContent = '';
      const reader = response.body.getReader();
      const decoder = new TextDecoder();
      let buffer = '';

      while (true) {
        const { value, done } = await reader.read();
        if (done) break;
        buffer += decoder.decode(value, { stream: true });
        const frames = buffer.split('\n\n');
        buffer = frames.pop() ?? '';

        for (const frame of frames) {
          if (!frame.startsWith('event: token')) continue;
          const line = frame.split('\n').find((part) => part.startsWith('data: '));
          if (line) answerText.textContent += JSON.parse(line.slice(6));
        }
      }

      statusEl.textContent = 'Answer complete.';
      if (document.activeElement === retry) answerHeading.focus();
      retry.hidden = true;
    } catch (error) {
      statusEl.textContent = `Answer failed: ${error.message}. You can retry this same request.`;
      retry.hidden = false;
      retry.focus();
    } finally {
      setBusy(false);
    }
  }

  form.addEventListener('submit', (event) => {
    event.preventDefault();
    if (inFlight) return;
    requestKey = crypto.randomUUID();
    post(promptEl.value);
  });

  retry.addEventListener('click', () => {
    if (inFlight) return;
    post(promptEl.value);
  });
</script>

The guard runs in two places because a double click can beat a visual update. The inFlight flag catches the second click before aria-disabled is painted. The aria-disabled attribute tells assistive technology that the action is temporarily unavailable, while the element remains focusable. Test that behavior with your actual screen reader; support is not uniform.

The focus move after a successful retry is deliberate. If the retry button disappears while it owns focus, the next Tab starts from the top of the document. Moving focus to the answer heading gives the user a stable landmark. If your action bar stays visible, keep focus there and change the label to “Regenerate” instead, but assign a new key only when the user actually asks for a new generation.

What the screen reader and keyboard need

The visible error and the announced error should be the same sentence. In the snippet, aria-describedby='status' points at the polite status region, so a retry button does not announce a stale message from an earlier failure. When the retry begins, the status changes once to “Retrying the same request.” Do not stream every token into that live region; announce state transitions, not the answer itself.

A keyboard-only pass should cover the exact sequence that breaks the UI:

Tab to Retry and press Enter twice within 300 ms.
Confirm the Network panel shows one POST, not two.
Confirm one assistant answer exists after completion.
Force a 500 before the first token, then retry with Enter.
Confirm focus remains on Retry while busy, then lands on the answer heading after success.
Repeat with a screen reader and record the announcement order.

If the second Enter creates a second request, the bug is not “the model is slow.” The client created a second identity. If the screen reader announces completion twice, the live region is probably receiving both a token event and a done event. Those are different fixes, and the state table keeps them separate.

A QA matrix you can repeat

Scenario	How to force it	Pass condition
Double submit	Press Enter twice on Retry	One POST, one answer, one completion message
Fail before first token	Stop the server before sending	Visible error, Retry reuses key
Fail after partial token	Kill the stream mid-answer	Copy explains “retry from start,” no mixed answer
Replay after completion	Resend the same key	`idempotent-replay: true`, no new generation
Key reuse with new prompt	Same key, different body	`422`, not a silent second answer
Server restart	Restart between attempts	Known limitation: ledger is empty, duplicate possible

Record the browser, OS, and assistive technology versions beside each row. A result without those versions is hard to reproduce, and “works on my machine” is not a QA result.

Where MonkeyCode fits, and where this design stops

The reproduction above uses a local generator so it runs without an account. When I want to exercise the same ledger with a real model, one operator-supplied option is MonkeyCode: the operator describes the project as open source, with free model access and a free server option, including 10 million free tokens. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I am not naming models, quoting rate limits, or promising uptime, because I have not verified those details and they are not required to debug the retry contract.

Is that a good fit for this test? It can be, if you need a place to host the proxy and a model endpoint for a prototype. It is not a substitute for durable idempotency. The ledger above lives in memory, so a deploy or crash forgets every key. For production, put a unique constraint on (account_id, idempotency_key) in a database and store the terminal response with a short expiry. If prompts can contain personal data, store only the status and a hash, or return 409 instead of replaying the content.

Who should not use this approach? Teams that need exactly-once behavior across regions, teams that cannot persist a key, and teams whose provider cannot replay or cache a completed answer. In those cases, make Retry a new user-visible action with a new key, and say so in the label. Do not pretend a network retry is free when it can create a second answer.

If you try the workflow on a free deployment, bring back the browser, OS, assistive technology, and the exact transition that failed. A screenshot of two answers is a symptom. The request keys in the Network panel are the evidence.

The Stop Button Worked Once: Debugging a Reused AbortController in a Streaming Chat

babycat — Sat, 17 Oct 2026 05:44:05 +0000

Last week a teammate sent me a two-line message at the end of the day: "Stop works the first time. The second time, the chat just keeps typing and I can't make it stop." She had been testing the retry path after a 500 from our own gateway, and by the time I opened the tab, the transcript was still growing with nobody at the keyboard. Nothing in the console looked like an exception, which is usually the sign that the bug lives in the state machine rather than the network.

Here is the symptom table I wrote before touching any code, because the shape of the failure matters more than the eventual stack trace. Notice that every row is a second interaction: first interactions were all clean, and that is exactly what let the bug survive three review passes.

User action	Expected	Actual
Send, then Stop	stream ends, status becomes `Stopped`, composer re-enabled	correct, first attempt only
Send again, then Stop	stream ends again	tokens keep arriving, Stop looks inert
Retry after HTTP 500	one new attempt, one status change	UI stuck on `Generating…`, Retry gone
Screen reader user, same path	"Generating" then "Stopped"	one announcement, then silence

Three symptoms, one object: the AbortController.

Reproduce it before you theorise

I do not trust a fix I cannot trigger on demand, so step one is always a deterministic reproduction. Mine takes about ninety seconds and needs no network at all.

Stub fetch so it emits five chunks, one every 200 ms, then closes.
Send a prompt, click Stop after chunk two, confirm the status reads Stopped.
Send a second prompt, click Stop after chunk two, and watch the transcript.
Log signal.aborted at the top of the request function, every time.

// repro-harness.ts — run with `npx tsx repro-harness.ts`
let calls = 0;
globalThis.fetch = async (_url, init) => {
  calls += 1;
  console.log(`attempt ${calls}, signal.aborted at start:`, init?.signal?.aborted);

  const body = new ReadableStream({
    async start(controller) {
      for (const chunk of ["one ", "two ", "three ", "four ", "five"]) {
        if (init?.signal?.aborted) {
          return controller.error(new DOMException("Aborted", "AbortError"));
        }
        controller.enqueue(new TextEncoder().encode(chunk));
        await new Promise((r) => setTimeout(r, 200));
      }
      controller.close();
    },
  });
  return new Response(body, { status: 200 });
};

The second row of that log is the entire investigation: attempt 2, signal.aborted at start: true. The stream never had a chance, because it was born cancelled.

The root cause was a `useRef` with a lifetime problem

The component created one controller when it mounted and reused it for every request, which feels tidy and is wrong. An AbortController is a one-shot object: once you abort it, the signal stays aborted forever, and every future fetch that receives it rejects almost immediately.

// buggy
const controllerRef = useRef(new AbortController());

async function send(prompt: string) {
  setStatus({ kind: "streaming" });
  try {
    const res = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ prompt }),
      signal: controllerRef.current.signal, // aborted forever after the first Stop
    });
    await readStream(res);
  } catch (err) {
    if (err instanceof DOMException && err.name === "AbortError") return; // silent
    setStatus({ kind: "failed", message: "Something broke." });
  }
}

Two bugs compounded into one confusing experience. The cancelled attempt returned early and left status at streaming, so the UI kept advertising Generating… and hid the Retry button. The reused signal then made the next attempt abort within milliseconds, which the same early return swallowed again: a loop of silence that looked exactly like a hung network.

Can you see why the first attempt was clean? Fresh controller, fresh signal, and the abort path ran precisely once.

Fix: bind the controller to the attempt, not the component

I stopped thinking in terms of "the request" and started thinking in terms of "an attempt", because that is the unit a user can cancel, retry, or duplicate. Each attempt carries its own controller, its own id, and its own terminal state.

type Status =
  | { kind: "idle" }
  | { kind: "streaming"; attempt: number }
  | { kind: "cancelled"; attempt: number }
  | { kind: "failed"; attempt: number; message: string; retryable: boolean };

let nextAttempt = 0;
let active: { id: number; controller: AbortController } | null = null;

async function run(prompt: string) {
  active?.controller.abort(); // never leave two attempts alive
  const attempt = { id: ++nextAttempt, controller: new AbortController() };
  active = attempt;
  setStatus({ kind: "streaming", attempt: attempt.id });

  try {
    if (attempt.controller.signal.aborted) throw new Error("attempt started aborted");

    const res = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ prompt }),
      signal: attempt.controller.signal,
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    for await (const chunk of readChunks(res)) {
      if (attempt.id !== active?.id) return; // a superseded attempt writes nothing
      append(chunk);
    }
    setStatus({ kind: "idle" });
  } catch (err) {
    if (attempt.controller.signal.aborted) {
      setStatus({ kind: "cancelled", attempt: attempt.id }); // a real state, announced
      return;
    }
    setStatus({
      kind: "failed",
      attempt: attempt.id,
      message: "Connection dropped.",
      retryable: true,
    });
  }
}

function stop() {
  active?.controller.abort();
  if (active) setStatus({ kind: "cancelled", attempt: active.id });
}

The important change is not the extra types; it is that cancellation became a state instead of a missing return. My previous code treated "the user stopped it" as an absence of information, which is why nothing was announced and nothing re-enabled.

What the assistive technology actually heard

Fixing the controller did not fix the announcement, and this is the part where I usually lose an afternoon. During the stuck state the log region carried aria-busy="true" and never cleared, so polite updates inside it were deferred in my Chrome plus NVDA pass. I now treat a busy flag that outlives its attempt as a bug in its own right, not as cosmetic debt.

Keep exactly one role="status" region with aria-live="polite", outside the scrolling transcript.
Announce transitions rather than tokens: "Generating", "Stopped", "Retry available".
Do not move focus on failure; return focus only when the user explicitly asked for it.
Keep Stop focusable while streaming, and make Retry the next tab stop after the error text.
Reference the error text from Retry with aria-describedby, so the button is never an unlabelled mystery.

My test plan, and the matrix I run it in

Scenario	Input	Expected outcome
Cancel then send	Stop, then new prompt	second stream starts, Stop works again
Cancel twice quickly	double-click Stop	one announcement, no error flash
Retry after 500	stub 500, click Retry	exactly one new request, Retry disabled while pending
Superseded stream	Send while streaming	old attempt writes nothing to the transcript
Keyboard only	Tab to Stop, press Enter	focus stays put, status updates

Environments I actually run: Chrome with NVDA on Windows 11, Safari with VoiceOver on macOS, Firefox with Orca on Linux, and iOS Safari with VoiceOver. Firefox deserves more attention than it gets here, because older code paths sometimes surface cancellation as an Error rather than a DOMException.

Where MonkeyCode genuinely fit into this loop

Two things about this bug needed an environment I do not keep lying around: a deployed origin, because proxy buffering changes how chunks arrive, and a large number of failed attempts, because I ran the cancel-and-retry loop dozens of times per session. I used MonkeyCode's free model access to drive those runs without rationing tokens, and its free server option to host the same page on a second origin and compare stream timing against localhost. The operator currently advertises a ten-million-token free allowance plus a free server option; check the project page for the current terms before planning around them, because free-tier details move. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

It is a reasonable way to get a cheap second origin for this exact class of test. It is not a replacement for your own logging, and no hosted tier will tell you that your signal was born aborted.

Limitations and who should skip this

If your interface has no cancel affordance, an attempt id is overhead; one controller per mount is genuinely fine.
If your framework already scopes mutation cancellation per call, copy the guard pattern, not the plumbing.
This pattern does not fix duplicated user messages; that needs an idempotency key on the request instead.
Free allowances change over time, so never let a reproduction plan depend on a permanent quota.

What I check first next time

Log signal.aborted at request start and treat true as a hard error.
Make cancellation a rendered state, never an early return.
Assert one live attempt with a module-level id, and bail out of stale writers.
Confirm the aria-busy flag clears on every terminal transition.
Re-run the cancel-retry loop on a second origin before calling anything fixed.

A stop button that works exactly once is never a browser quirk; it is a lifetime bug wearing a network costume. If you hit the same silence, send me the browser, OS, and assistive-technology versions plus the exact interaction that broke, and I will add the row to the matrix.

Focus Left the Copy Button Every 200 ms: Debugging a Streaming Markdown Panel

babycat — Fri, 16 Oct 2026 04:39:57 +0000

Focus Left the Copy Button Every 200 ms: Debugging a Streaming Markdown Panel

Last Tuesday a colleague who navigates with a keyboard and reads with a screen reader sent me two sentences. "Every time I tab to Copy answer, something yanks me back to the top of the page." The answer was still streaming, so I assumed my polite live region was simply too chatty again. It was not the live region, and the real cause took me an afternoon of narrowing the surface instead of reading the code.

The symptom, written down before touching anything

Three reports arrived within a week, and all three shared the same shape, which is what made the bug tractable at all.

Mouse users never noticed; clicking still copied the answer correctly every time.
Keyboard users lost their place only while tokens were arriving, never after the answer finished.
Focus did not move to a nearby element; it went to the very top of the document.
No console error, no failed request, and no visible layout shift accompanied it.

Why does a bug that vanishes the moment the stream ends feel so slippery? Because it is almost never a network bug, even though it only shows up while data is moving. It is a DOM lifecycle bug, and lifecycle bugs reward a specific order of operations: write the symptom down, make it reproducible, and only then open the renderer.

Step 1: Turn the report into a failing test

You cannot fix a focus bug you can only sometimes see, so the first artifact was a test that fails on demand.

// tests/focus-stability.spec.ts
import { test, expect } from '@playwright/test';

test('Copy keeps focus while the answer streams', async ({ page }) => {
  await page.goto('/stream-demo');
  await page.getByRole('button', { name: /ask/i }).click();

  const copy = page.getByRole('button', { name: /copy answer/i });
  await copy.focus();
  await expect(copy).toBeFocused();

  const losses: string[] = [];
  for (let i = 0; i < 20; i++) {
    await page.waitForTimeout(200);
    const active = await page.evaluate(() => {
      const el = document.activeElement as HTMLElement | null;
      return `${el?.tagName}#${el?.id ?? ''}`;
    });
    if (active !== 'BUTTON#copy-answer') losses.push(`${i * 200}ms -> ${active}`);
  }

  expect(losses, `focus lost at: ${losses.join(', ')}`).toHaveLength(0);
});

npx playwright test tests/focus-stability.spec.ts --repeat-each=5 failed on the very first run with output like 600ms -> BODY#. The timestamp mattered more than the failure: focus died roughly every 200 ms, which matched my chunk cadence and not the network timing at all.

Step 2: Bisect the surface, not the source

I did not read the renderer first. I disabled one subsystem at a time and reran the same test, because a bisect hands you evidence while code review only hands you opinions.

Disabled syntax highlighting inside the answer panel.
Disabled auto-scroll to the newest chunk.
Moved the live region outside the answer panel.
Throttled the chunk cadence from 200 ms to one second.
Replaced markdown rendering with plain text output.

Toggle	Focus survives?	What it told me
Highlighting off	Yes	The highlight pass rewrote the panel on every chunk
Auto-scroll off	No	Scrolling was innocent
Live region moved out	No	Announcements were a second bug, not this one
Slower cadence	Yes	Confirmed a per-chunk rewrite, not a race condition
Plain text output	Yes	The rewrite, not the parser, was the culprit

Two rows did all the work. Highlighting, which is the expensive step, called innerHTML on the whole answer panel so that highlighted code blocks stayed current. Each call deleted every child node inside that panel, including the button I had focused a moment earlier.

Step 3: The root cause is node identity

When a focused element is removed from the DOM, focus does not travel to a sensible neighbour; in the browsers I tested, document.activeElement becomes document.body. From there the next Tab press starts at the top of the document. That is the entire mystery solved: a re-render destroyed the focused node, and the browser did exactly what it is specified to do.

The blast radius was wider than one button, which is why I did not stop at restoring focus.

// Before: every chunk rebuilds the whole panel and destroys node identity.
output.innerHTML = highlight(marked.parse(buffer));

The focused Copy button was removed and recreated on every single chunk.
Any text selection inside the answer was silently cleared as the reader highlighted it.
The polite live region wrapped the whole panel, so each rewrite queued another announcement.
scrollTop fought with auto-scroll because the panel height kept changing under the caret.

Mouse users experienced none of this, which is exactly how a bug like this survives review for months. Isn't that always the pattern with DOM churn?

Step 4: Fix it with stable nodes and a commit boundary

The fix is not a focus-restoration shim, because restoring focus after destroying it still fires focus events that interrupt a reader. The real fix is to stop destroying nodes you did not have to touch, and to commit finished markdown at paragraph boundaries.

const transcript = document.querySelector('[data-transcript]');

// One persistent text node carries the in-progress paragraph.
const tail = document.createElement('p');
tail.className = 'stream-tail';
const tailText = document.createTextNode('');
tail.append(tailText);
transcript.append(tail);

const committed = new Set(); // block indexes we never touch again
let buffer = '';

export function onChunk(text) {
  buffer += text;
  const cut = buffer.lastIndexOf('\n\n');
  if (cut !== -1) {
    const finished = buffer.slice(0, cut);
    buffer = buffer.slice(cut + 2);
    commitBlocks(finished);
  }
  tailText.nodeValue = buffer; // node identity stays stable
}

function commitBlocks(markdown) {
  for (const [index, block] of markdownBlocks(markdown)) {
    if (committed.has(index)) continue;
    committed.add(index);

    const el = document.createElement('div');
    el.dataset.blockIndex = String(index);
    el.innerHTML = renderSafe(block); // sanitize once, at commit time
    transcript.insertBefore(el, tail);
  }
}

Because committed blocks are appended once and never rewritten, a Copy button inside an earlier paragraph is never removed, so no focus event fires and document.activeElement stays where the reader put it. The tail paragraph updates through nodeValue on a text node that outlives every chunk, which also keeps the caret and any active selection inside the answer intact.

If you inherit a renderer you cannot restructure yet, this shim buys time but is not a fix, since it still tears down and recreates the node:

function replacePreservingFocus(container, html) {
  const active = document.activeElement;
  const id = active && container.contains(active) ? active.id : null;
  container.innerHTML = html;
  if (id) container.querySelector(`#${CSS.escape(id)}`)?.focus({ preventScroll: true });
}

Step 5: Regressions that catch this whole class of bug

Asserting toBeFocused() once at the end of a stream is not enough, because the loss is transient and the final state looks perfectly fine. I count removed nodes as a proxy for focus risk, which is a cheap technique you can reuse on any panel that re-renders on a timer.

await page.evaluate(() => {
  window.__removals = 0;
  new MutationObserver((records) => {
    for (const r of records) window.__removals += r.removedNodes.length;
  }).observe(document.querySelector('[data-transcript]'), {
    childList: true,
    subtree: true,
  });
});

After the fix, a twelve-second stream produced fewer than ten removals inside the transcript, all of them legitimate paragraph commits. Before the fix, the same stream produced hundreds, every one of them avoidable. That ratio is the kind of evidence a pull request reviewer can actually verify without watching you reproduce it live.

The QA matrix I now fill in

I tested on current stable Chrome and Safari on macOS with VoiceOver, and I could not test Windows or mobile screen readers myself, so the blanks below are honest blanks rather than copied numbers.

Browser	OS	Assistive tech	Keyboard path tried
Chrome ___	macOS ___	VoiceOver ___	Tab to Copy mid-stream
Firefox ___	Windows ___	NVDA ___	Caret inside answer, then Tab
Safari ___	iOS ___	VoiceOver + hardware keyboard	Copy, then Escape
Edge ___	Windows ___	Narrator ___	Shift+Tab back into panel

Where the reproduction lived

Chunk fixtures are tedious to hand-write, and a bug report is only useful when other people can hit the same transition. I used MonkeyCode's free model access to generate a set of realistic streaming fixtures and its free server option to host the demo, so a commenter can open the exact panel state that broke focus instead of describing it in prose.

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

The project advertises a free token allowance alongside a free server option, and I am deliberately not quoting the number here, because quotas move and a stale figure inside a tutorial is worse than no figure at all. Check the project page for current terms and for what the open-source repository actually contains. MonkeyCode did not fix this bug; it made the reproduction cheap enough to share, which is the step that usually stalls these reports.

Limitations, and who should skip this approach

If you render untrusted model output, sanitize at commit time. Stable nodes do not make innerHTML safe, and this focus bug is trivial next to an XSS hole.
If you use a virtualized transcript, committed blocks unmount when scrolled away, so focus can still die; pin the focused block or restore by id as a fallback.
If answers arrive in one piece, you simply do not have this problem, and the commit boundary is pure overhead.
If the focused element has no stable unique id, the restoration shim will never find it again.
If you are inside a native WebView with its own renderer, document.activeElement may not tell the whole story.

Reproduce it and tell me what breaks

Run the test above against your own streaming panel with npx playwright test --repeat-each=3, and watch document.activeElement for ten seconds while chunks arrive. If focus still escapes, I would like your browser and OS versions, your assistive technology version, and the exact transition that failed, including whether the answer had finished streaming at that moment.

If you want to try the same loop on a hosted demo, start with the project's free model access and free server option, and keep the reproduction small enough that a stranger can break it in one click.

A Token Stream That Arrives All at Once: Debugging Buffering From Symptom to Fix

babycat — Thu, 15 Oct 2026 11:05:59 +0000

Support tickets about AI features rarely say "your relay buffers the response." They say something like this: the answer is correct, it just shows up in one lump after a long pause, and my screen reader reads the whole paragraph in a single breath.

Those look like two complaints — one about latency, one about accessibility — but in the failures I have traced, they share one root cause: a stream that was correct on the wire arrived at the client in a single chunk. The model was never slow. The bytes were simply held somewhere in the middle and released together.

That failure shape is common enough that it deserves a checklist rather than a hunch. So here is the debugging path I would hand to a teammate, with a reduced reproduction you can run, the places buffering actually hides, and the accessibility regression that bites even after the latency looks fixed.

The scenario below is a composite of that failure shape rather than one specific incident; the reproduction and commands are real artifacts you can run yourself.

Write the state table before you touch the network tab

Streaming UI has more states than people admit, and buffering breaks exactly one of them. If you cannot name the states, you will "fix" the wrong one.

Phase	Visible text	Live region	Keyboard focus	Stop control
`idle`	Ready	silent	on the composer	hidden
`connecting`	Connecting…	silent	on the composer	visible, enabled
`streaming`	Growing transcript	polite, buffered	stays on composer	visible, enabled
`complete`	Final transcript	one short summary	does not move	hidden, focus returns to composer
`cancelled`	"Stopped after N characters"	polite announcement	does not move	hidden
`error`	Message plus Retry	assertive, once	Retry reachable by Tab	hidden

The bug in question shows up as connecting that appears to last 30 seconds and then a jump straight to complete, skipping visible streaming entirely. Modeling it as a typed state machine makes the symptom precise:

type StreamState =
  | { phase: 'idle' }
  | { phase: 'connecting'; startedAt: number }
  | { phase: 'streaming'; firstTokenAt: number; chars: number }
  | { phase: 'complete'; durationMs: number }
  | { phase: 'cancelled'; reason: 'user' | 'timeout' }
  | { phase: 'error'; retryable: boolean; httpStatus?: number };

If streaming never renders, the question becomes narrow and testable: did the client receive frames progressively, or did it receive one frame at the end?

Rule out the model before you blame the model

A slow provider and a buffered relay produce the same user complaint. Separate them with timestamps, not with opinions.

Hit the upstream model endpoint directly and timestamp every line as it arrives.
Hit your own relay endpoint the same way.
Compare the gaps between lines, not the total duration.
Repeat step 2 through a deployed host, not through localhost.

# Timestamp each line as it lands. If every timestamp is identical,
# you are seeing one buffered chunk, not a slow stream.
curl -N -H 'Accept: text/event-stream' https://your-relay.example/stream \
  | while IFS= read -r line; do printf '%s %s\n' "$(date +%s.%3N)" "$line"; done

# Inspect the response headers for a smoking gun.
curl -sS -D - -o /dev/null -H 'Accept: text/event-stream' https://your-relay.example/stream

Two details are worth memorizing. First, curl -N disables curl's own output buffering; without it you can manufacture the bug yourself. Second, a content-encoding: gzip header on an event stream is a strong hint that a compression layer is sitting between the model and the browser.

The three places a stream actually gets held

In my experience the bytes stop moving in one of three places, and they are easy to test in order:

Compression middleware. A generic gzip layer waits for a threshold before flushing, which is exactly wrong for latency-critical frames.
A reverse proxy. nginx's proxy_buffering defaults to on, so the proxy happily accumulates your stream until the upstream response ends.
Client-side code. A stray await response.json(), an intermediate API route that buffers the whole body, or a service worker that clones the response will all destroy progressive rendering.

Note what is not on the list: the browser's fetch reader. In the failures I have triaged, response.body.getReader() was doing its job and handing over whatever the network delivered — which was one chunk.

A relay that lies, in about thirty lines

The fastest way to internalize this bug is to build it on purpose. This relay emits twenty frames 300 ms apart and wraps them in gzip, so the client sees almost nothing until the end:

// server.mjs — deliberately buffered reproduction
import express from 'express';
import compression from 'compression';

const app = express();
app.use(compression()); // <-- the bug: frames accumulate instead of flushing

app.get('/stream', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache, no-transform');
  res.setHeader('Connection', 'keep-alive');
  // Note: no res.flushHeaders() here on purpose.

  for (let i = 0; i < 20; i++) {
    res.write(`data: ${JSON.stringify({ i, at: Date.now() })}\n\n`);
    await new Promise((resolve) => setTimeout(resolve, 300));
  }
  res.end();
});

app.listen(3000, () => console.log('http://localhost:3000/stream'));

Run it, then timestamp the output with the curl loop above. On a fast local connection you may still see reasonable spacing — which is precisely why this class of bug survives code review and dies in production.

The fix, and why "just add flush" is only half a fix

The transport fix is short, and it is about telling every layer that latency beats compression ratio:

import compression from 'compression';
import zlib from 'node:zlib';

app.use(
  compression({
    // Flush after each write instead of waiting for the internal buffer.
    flush: zlib.constants.Z_SYNC_FLUSH,
    // Never compress event streams: they are small and latency-critical.
    filter: (req) => req.headers.accept !== 'text/event-stream',
  })
);

app.get('/stream', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache, no-transform');
  res.setHeader('X-Accel-Buffering', 'no'); // nginx: do not buffer this response
  res.flushHeaders(); // unblock the client reader immediately
  // ...write frames...
});

The half that people skip is the accessibility half. Progressive frames are not automatically a good screen reader experience: if you point aria-live="polite" at the whole growing transcript, every frame risks a new announcement, and some readers will restart mid-sentence. Put the transcript outside the live region, and announce from a separate node on a timer or sentence boundary instead.

<!-- The transcript is not a live region. -->
<div id="transcript" role="log" aria-live="off"></div>

<!-- A small, separate node handles announcements. -->
<p id="stream-status" role="status" aria-live="polite" aria-atomic="true"></p>

// Announce at most once per ~1500 ms, and always a complete sentence fragment.
let lastAnnounced = 0;
function maybeAnnounce(text) {
  const now = performance.now();
  if (now - lastAnnounced < 1500) return;
  lastAnnounced = now;
  document.getElementById('stream-status').textContent = text;
}

Why localhost cannot reproduce this, and what to do about it

Loopback has no compression proxy, no cellular handoff, and no corporate middlebox. DevTools throttling changes bandwidth, not buffering semantics — those are different variables, and only one of them triggers this bug.

So the network path has to be real. That is the part of the workflow where I used MonkeyCode (Disclosure: This article was prepared as part of MonkeyCode's product outreach.), an open-source AI coding project whose operator states that it includes free model access — described as a ten-million-token allowance — and a free server option for running small services. Both of those are operator-supplied claims rather than verified benchmarks, so check the project's current terms yourself before relying on either one.

Why those two things are the relevant ones here:

A real model stream gives you realistic timing for free. Faking tokens with setTimeout teaches you nothing about inter-token gaps. A genuine model endpoint produces the uneven cadence that actually stresses a buffered relay.
A reachable host gives you a real path. A server you can open from a phone on cellular exercises a proxy and a handoff that localhost never will.
A second environment gives you a control. If the bug reproduces on the hosted relay but not on loopback, the culprit is in the deployment path, not in your reader loop.

The debugging sequence I would use: run the reproduction locally, confirm the timestamps cluster; deploy the same relay to the hosted environment; open it from a phone off Wi-Fi; timestamp both with curl; then apply the flush and compression fixes and confirm the timestamps spread out.

Limitations, and who should skip this

This workflow diagnoses delivery, not model quality. If the first token genuinely takes 20 seconds, buffering is not your problem.
Free tiers change. Treat the availability claims above as a snapshot of a vendor description, not a guarantee, and never put real credentials or user data into a throwaway reproduction host.
Do not ship the reproduction relay to production traffic. It has no auth, no rate limiting, and no cancellation handling.
If your product's output is short and non-progressive by design, this whole class of bug is irrelevant to you.

The QA matrix I would run before closing the ticket

Layer	What to change	Expected result
Transport	Remove gzip from the event stream	Frames arrive individually
Proxy	Send `X-Accel-Buffering: no`	nginx stops accumulating
Client	Reject `await res.json()` in the read path	Progressive rendering resumes
Assistive tech	Move `aria-live` off the transcript	No mid-sentence restarts
Keyboard	Tab through Stop, then Retry after an error	Focus never gets trapped or dropped

If you reproduce a variant of this, the details that matter most are your browser and OS build, your screen reader and version, and the exact transition that failed — for example, "focus left the Stop button when the stream ended on a 4G handoff." Those three facts turn a vague "streaming feels broken" report into a fix.

If you want to poke at the reproduction, the relay above runs unchanged on a small free host, which is a low-risk way to see the buffering behavior with your own eyes.

A Token Stream Needs a Quiet Buffer, Not an Assertive Live Bubble

babycat — Sun, 11 Oct 2026 19:58:47 +0000

I was halfway through a keyboard pass on a small chat demo when the delayed reply finally woke up. The painted paragraph looked smooth, but the mutation log showed the assertive bubble rewriting itself on almost every chunk. I stopped typing and asked a blunt question: why does a calm bubble schedule a new announcement for every fragment? The send button still showed focus in the log, yet the next Tab target was a copy control that should not have existed yet.

That afternoon I was not hunting a model-quality bug, and I was not blaming the network before the accessibility tree. I was watching a state machine lie about what streaming means to someone who cannot see the caret. Have you ever trusted a spinner because the pixels moved, then learned the live region was screaming? I had trusted that spinner, and the repair was smaller than the embarrassment I felt afterward.

What looked finished and what sounded broken

The visual layer appended tokens immediately, which is the behavior most of us screenshot for a progress demo. The accessibility layer treated the whole assistant bubble as an assertive live region, so each chunk aborted the previous speech. A copy button mounted as soon as a fence opened, and that button stole a tab stop from the composer. The draft survived in memory, but focus had moved, so the next Enter missed the control I thought was active.

I wrote that mismatch down before I changed a single style rule or renamed a component. If you skip the note, you will polish the animation and ship the same announcement storm. Does your status text describe only the phase, or does it secretly duplicate the entire transcript? Mine duplicated the transcript word for word, and that duplication was the first lie I had to unwind.

A symptom table I refused to skip

I keep a four-column note beside the editor until the patch is boring enough to retest. Each row names the action, the pixels, the speech policy, and the wrong blame I reached for first. If a row has no speech column, I do not get to call the bug fixed.

I submitted one prompt, saw smooth tokens, logged a rewrite on each chunk, and wrongly blamed a chatty model.
I pressed Tab during the burst, landed inside the fence, found an unnamed copy button, and wrongly blamed the browser.
I pressed Escape, watched the spinner vanish, found no phase change, and wrongly called cancel a purely visual problem.
I waited through a cold start, then a flood, logged one assertive dump, and wrongly treated latency as only a spinner issue.

How I read the rows

The rows are a debugging technique, not a design manifesto you can paste into a ticket and walk away. I ask which column changed, which column stayed silent, and which column I used as a convenient villain. Have you closed a bug because the spinner matched the mock, while the speech column stayed empty? I have done that, and the table is what makes the empty column impossible to ignore.

Three listeners before any CSS change

I did not open layout tooling first, because this bug lived in focus order and in live-region mutations. A tiny logger on focusin, assistant mutations, and chunk arrival showed me which event actually fired first. Would you rather debate a transition curve, or count how many times the live region mutates each second? I counted those mutations in the log, and the rate was high enough to embarrass the demo.

<div id="log" role="region" aria-label="Debug log" tabindex="0"></div>
<script>
  const log = document.querySelector("#log");
  const note = (line) => {
    const item = document.createElement("p");
    item.textContent = new Date().toISOString() + " " + line;
    log.appendChild(item);
  };
  document.addEventListener("focusin", (event) => {
    note("focusin " + (event.target.id || event.target.tagName));
  });
  const bubble = document.querySelector("#assistant");
  new MutationObserver(() => note("assistant mutated")).observe(bubble, {
    childList: true,
    characterData: true,
    subtree: true
  });
</script>

A repeatable local burst

I then forced chunks locally so I was not debugging the network and the widget at the same time. A timer is not a benchmark, and it is not a claim about any vendor's latency or hardware. It only makes the same state transitions repeatable on a laptop before I trust a socket. If your fake reader cannot trigger cancel, error, and completion, it is an animation toy rather than a test.

async function fakeChunks(text, push, signal) {
  const parts = text.match(/\S+\s*|\s+/g) ?? [];
  for (const part of parts) {
    if (signal.aborted) return;
    await new Promise((resolve) => setTimeout(resolve, 40));
    push(part);
  }
}

You can serve the single file and poke the composer from the console without hunting for a mouse path. I use a local static server so focus behavior matches a real origin rather than a file URL quirk. The console lines set a prompt and submit, which is the same transition I want a later screen-reader pass to repeat.

python3 -m http.server 4173

document.querySelector("#prompt").value = "Explain focus in one short sentence.";
document.querySelector("#composer").requestSubmit();

Root cause, underneath the costume it wore

The root cause was an announcement policy tied directly to paint, plus controls born before the markdown fence closed. One assertive region was acting as transcript, status line, and error channel, so every role interrupted the others. Replacing the message node on each chunk also dropped focus toward the log whenever the element identity changed. I had enabled Send whenever the textarea was non-empty, even while a reply was still in flight.

A polite status region from an earlier pass would not have saved this demo by itself. If you pipe every token into that status node, you still restart speech, only with a politer interrupt. The costume was an accessible live region, and the cause was announcing the paint. Have you ever added a role and called the interaction finished? I had done exactly that, and the mutation count called my bluff.

You should separate what you paint for sighted progress from the phrases you enqueue for speech. You should defer any new button until the structure that contains it is complete and nameable. Clear pending speech when the phase becomes cancelled or failed, so a late phrase cannot land afterward. Ignore a chunk whose generation does not match the current id, which keeps a stale socket from rewriting the bubble.

Eager paint, quiet speech

Sighted readers can keep immediate token paint, because the moving caret is already their progress cue. Assistive technology needs a coalesced phrase or a phase update, not a restart on every syllable. I leave the transcript at aria-live="off" and put phase copy in one polite status region that already exists in tab order. Errors use a single assertive announcement only when the phase actually changes to error, not when a token arrives.

const Phase = {
  idle: "idle",
  waiting: "waiting",
  streaming: "streaming",
  cancelled: "cancelled",
  error: "error",
  done: "done"
};

function createBuffer(announce, delay = 700) {
  let timer = 0;
  let pending = "";
  return {
    push(chunk) {
      pending += chunk;
      window.clearTimeout(timer);
      timer = window.setTimeout(() => {
        const phrase = pending.trim();
        pending = "";
        if (phrase) announce(phrase);
      }, delay);
    },
    flush() {
      window.clearTimeout(timer);
      const phrase = pending.trim();
      pending = "";
      if (phrase) announce(phrase);
    },
    clear() {
      window.clearTimeout(timer);
      pending = "";
    }
  };
}

This buffer is a proposal you can paste into a single file, not a telemetry result from a production cluster. I announce Generating reply when the phase enters waiting, then coalesced phrases while the phase stays streaming. On done I flush once, then announce Reply complete only if that exact phrase was not just spoken. On cancel I clear the buffer before I write Reply stopped, so the delayed timer cannot speak over the stop.

<section aria-labelledby="thread-title">
  <h2 id="thread-title">Conversation</h2>
  <p id="stream-status" role="status" aria-live="polite">Idle</p>
  <div id="transcript" aria-live="off"></div>
  <form id="composer">
    <label for="prompt">Message</label>
    <textarea id="prompt"></textarea>
    <button type="submit" id="send">Send</button>
    <button type="button" id="stop" disabled>Stop</button>
  </form>
</section>

Copy buttons wait until the fence closes, because an early button is a tab stop without a stable accessible name. I render open fences as plain text, and I mount the button only after the closing marks arrive or the stream completes. Is that slower for a mouse user who wants to copy a half-written sample right away? Yes, and that delay stays intentional until the control can be named honestly for every user.

Phase table I keep next to the file

Phase	Send	Stop	Status text	Transcript live	Buffer
idle	enabled	disabled	Idle	off	empty
waiting	disabled	enabled	Generating reply	off	empty
streaming	disabled	enabled	Generating reply	off	coalescing
cancelled	enabled	disabled	Reply stopped	off	cleared
error	enabled	disabled	Reply failed. Retry when ready.	off	cleared
done	enabled	disabled	Reply complete	off	flushed once

Focus stays on Stop when the user activated Stop, and it returns to the textarea only if they did not move elsewhere. I set a userMovedFocus flag from the same focusin logger, so a helpful focus call cannot yank them out of the debug log. Have you ever shipped a convenience focus move that felt like a keyboard trap during a test? I have shipped that move, and the flag is how I stopped repeating it on the next pass.

A remote stream, after the local matrix already fails honestly

Disclosure: This article was prepared as part of MonkeyCode's product outreach. I still run the fake reader first, because a local timer is how I force the same chunk size on demand. When I want a real cadence, I point that same push function at MonkeyCode's free model access and free server option. I do not treat one cold start as a quota, a hardware figure, or a permanent latency promise.

This file does not measure quotas or hardware, so those claims stay out of the notes. The local path is for frontend developers who need a keyboard-operable reproduction before they open a socket. If that free server is unavailable, the demo still teaches the buffer, because the fake reader exercises every phase in the table. You should not lean on the remote option alone for a conformance report, a capacity plan, or any uptime claim.

The request shape belongs in the current product docs, so STREAM_URL stays a placeholder instead of a path I invented. I pass whatever response those docs currently describe, and the reader below only consumes a ReadableStream. If the docs change the payload, this UI code should not need a rewrite, because the parser stays outside the widget.

async function readStream(response, push, signal) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  while (!signal.aborted) {
    const step = await reader.read();
    if (step.done) break;
    push(decoder.decode(step.value, { stream: true }));
  }
}

This harness records interface transitions only, and it is not a service-level test of the host. If the local matrix already passes, that same remote option can feed readStream without you provisioning a machine first. Follow the current docs for authentication and payload shape, and keep the phase table even when the network looks quiet. I would not start there, because a flaky socket hides the announcement bug you can already force with a timer.

Checks I expect, not scores I borrowed

I have not attached pass rates, browser builds, or assistive-technology versions, because those belong to your run rather than to this prose. If a transition fails, write down the browser, the operating system, the assistive technology and version, and the exact phase change. That note is more useful than another screenshot of a spinner that never explains the speech. Run the rows in order, and stop when a row disagrees with the expected transition.

Check	Action	Expected transition
Announcement storm	Submit one sentence with 40ms chunks	Status changes on phase boundaries, not on every token
Early copy control	Tab from Stop while a fence is open	Focus does not enter an unnamed copy button
Cancel race	Press Stop, then wait one second	No coalesced phrase lands after Reply stopped
Late chunk	Deliver a chunk after the phase is cancelled	Buffer stays clear and the transcript does not grow
Focus retention	Leave focus in the debug log until done	Focus remains in the log when the reply completes
Retry	Activate Retry from the error phase	Fresh status text, new phase, previous transcript kept

When I would not use this buffer

A seven-hundred-millisecond coalesce hides token-level speech, so skip it when every fragment must be announced verbatim instead. Assertive errors still need their own moment, or a polite delay will bury them behind a phrase that was already pending. The buffer does not fix a missing label, a positive tabindex on a non-control, or a dialog that never manages focus. If you need a formal conformance statement, treat this file as a regression aid, not as the statement itself.

I also skip the remote stream when the lesson is parser correctness, because jitter disguises a fence bug I can force with a string. Do not store raw prompts in the debug log when those prompts contain private data, and do not ship the logger. The pattern assumes you own the client state machine, and it cannot repair a socket that never signals completion.

Would I use an assertive bubble again just to make a demo sound busier than it is? No, I would not, because busy speech is not the same thing as an understandable reply. Leave the paint eager, keep the speech quiet, and let the phase table tell you when the reply is actually done.

A Heartbeat-Only Stream Needs a First-Token Deadline, Not a Forever Generating Label

babycat — Fri, 09 Oct 2026 11:35:15 +0000

I rebuilt a one-file chat panel after a keyboard pass left the composer disabled and the status stuck on Generating. The mock inference server had already sent response headers, so the network row looked healthy and I almost blamed the model. A screen reader repeated the old polite status once, then stayed silent, as if tokens were still arriving somewhere. Have you ever left a spinner running because the status code never left the success range at all?

What the failure felt like in the tab order

I started from the keyboard, not from the console, because that is how the bug actually landed on a waiting user. Focus sat in a disabled textarea, the Stop control was missing, and the only change on screen was a pulsing label. The live region had announced Generating when the request began, and it had nothing new to say after that moment. Would you keep waiting if the interface never offered a spoken failure or a reachable cancel action?

The visual story and the accessibility story had diverged, which is a familiar trap in streaming chat interfaces. Sighted debugging saw a spinner and assumed latency, while assistive technology heard a frozen status with no recovery path. I wrote the expected states down before I touched the parser, because guessing from pixels had already wasted a pass. A table is slower to write than a guess, but it is the only place the missing state can show up clearly.

A state table before another spinner tweak

UI state	Entered when	Status text	Focus	Live announcement
idle	No request	Ready to send	Composer	None
connecting	Fetch started	Connecting to server	Stop button	Connecting
awaiting-token	Headers arrived, no token yet	Waiting for the first token	Stop button	Waiting for the first token
streaming	First text token	Generating	Stop button	Generating, then chunks by policy
stalled	Deadline elapsed with no token	No token arrived	Retry button	No token arrived. Retry is available.
cancelled	User activated Stop	Cancelled	Composer	Generation cancelled
done	Stream ended with text	Reply complete	Composer	Reply complete

That table made the hole obvious, because my code jumped from connecting straight into a forever Generating label. Headers and Server-Sent Events comments were being treated as proof that an answer had already started for the user. A heartbeat is a sign of life for the socket, not evidence that a reply exists and can be announced. If those two facts stay collapsed, every later accessibility tweak is decorating the wrong state and will miss the stall.

The frames I thought were tokens

I reproduced the stall with a local mock so the bug would not depend on a vendor outage or a quiet network. The server returns a success status and an event-stream content type, then writes comment heartbeats and never a data token. Curl makes that shape obvious if you refuse to let the browser developer tools hide the raw body from you. Have you checked whether your last slow token was actually a colon comment with no data line behind it?

What the raw frames are doing

curl -N --max-time 12 http://127.0.0.1:8787/mock-stream

// mock-server.mjs — local fixture only, not a vendor client
import { createServer } from "node:http";

createServer((req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
  });
  const timer = setInterval(() => res.write(": keepalive\n\n"), 1000);
  req.on("close", () => clearInterval(timer));
}).listen(8787);

A naive reader increments a received counter on every chunk, including comments, so the UI believes generation has begun. I split frames into heartbeats and tokens, and I refused to change the visible state until a non-empty text delta appeared. The parser below is a fixture for that distinction, and it is not a complete Server-Sent Events implementation for production. Empty data lines stay null on purpose, because silence should not be promoted into assistant text that a reader might trust.

type Frame =
  | { kind: "heartbeat" }
  | { kind: "token"; text: string }
  | { kind: "done" };

function parseSseBlock(block: string): Frame | null {
  const lines = block.split("\n");
  if (lines.every((line) => line.startsWith(":") || line.trim() === "")) {
    return { kind: "heartbeat" };
  }
  const data = lines
    .filter((line) => line.startsWith("data:"))
    .map((line) => line.slice(5).trimStart())
    .join("\n");
  if (data === "[DONE]") return { kind: "done" };
  if (!data) return null;
  return { kind: "token", text: data };
}

These snippets are a local fixture assembled for this walkthrough, not a transcript from a production incident or a measured outage. I want the failure to be boring and repeatable before I point any client at a host I do not control. A green status code plus a moving waterfall is not a reply, and the fixture exists to keep that temptation visible. If your own log cannot mark comment frames, you will keep fixing the spinner and missing the stall.

Root cause: connected was masquerading as generating

The root cause was a collapsed state, not a slow paint and not a missing animation on the generating label. Fetch resolved, the reader loop ran, and each keepalive chunk cleared an inactivity timer that I had attached to the wrong event. Because the status string never changed, a polite live region had no mutation to announce, which is how a quiet failure hides. Why would a live region speak if we never changed the string it was watching and never moved focus to a recovery control?

I also found a focus bug sitting underneath the stall, and it would have survived a purely visual timeout tweak. The composer was disabled on submit, and Stop was rendered only in the streaming state, so awaiting-token had no keyboard action. A deadline that only logged to the console would have repeated a mistake I already knew from earlier stream bugs. Invisible recovery is not recovery, and a user who cannot tab to Stop is still trapped even after you detect the stall.

The fix is a deadline tied to tokens

I moved the clock to the awaiting-token state and let heartbeats update a debug line without touching that clock at all. Eight seconds is a demo threshold for this mock, not a recommendation for every model or every network path you ship. When the deadline fires, I abort the reader, move to stalled, and announce a specific failure that names the missing token. Would a generic something-went-wrong string tell a keyboard user whether to retry, wait, or check the connection?

type Phase =
  | "idle"
  | "connecting"
  | "awaiting-token"
  | "streaming"
  | "stalled"
  | "cancelled"
  | "done";

const FIRST_TOKEN_MS = 8000;

function onFrame(frame: Frame, phase: Phase, startedAt: number, now: number): Phase {
  if (phase === "awaiting-token" && now - startedAt >= FIRST_TOKEN_MS) return "stalled";
  if (frame.kind === "heartbeat") return phase;
  if (frame.kind === "token") return "streaming";
  if (frame.kind === "done") return phase === "streaming" ? "done" : "stalled";
  return phase;
}

function armFirstTokenDeadline(signal: AbortSignal, onStall: () => void) {
  const timer = setTimeout(onStall, FIRST_TOKEN_MS);
  signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
  return () => clearTimeout(timer);
}

Status copy and focus

The status node stays in the same place in the accessibility tree, which avoids a focus-stealing toast when the phase changes. I use one assertive announcement only for the stall and cancellation, because those are interruptions a waiting user actually needs. Token appends stay polite or visual only, so a long reply does not bury the later stall message under a flood of characters. Stop remains a real button in tab order from the moment connecting begins, and it aborts the controller even before a token arrives.

<p id="stream-status" role="status">Waiting for the first token</p>
<p id="stream-alert" aria-live="assertive" aria-atomic="true"></p>
<button type="button" id="stop-stream">Stop generating</button>

Why aria-busy is not the announcement

Setting aria-busy on the log does not tell a screen reader that no token arrived, and it does not move focus to Stop. Busy is a hint about a region, not a recovery plan, and some users never hear it as a distinct failure at all. I still set aria-busy while connecting, but the stalled transition clears it and writes the assertive text beside the status. If you only toggle busy, you have changed an attribute and left the spoken status stuck on Generating for the user.

Retry creates a new request id and a new announcement, and it does not rewrite the previous empty attempt into fake assistant prose. The empty attempt stays in a diagnostics line as no token arrived, so a later success cannot be confused with the stalled turn. I log phase, frame kind, and elapsed milliseconds on each transition, because that one line made the heartbeat mistake undeniable. If your log cannot tell a comment from a token, you are still debugging the spinner rather than the stream itself.

A debugging loop I can reuse

Reproduce against a local mock before you blame the remote model, a remote server, or a flaky office network.
Capture raw frames with curl and the N flag, and mark comments, data lines, and the terminal event separately.
Draw the state table, including the waiting gap between response headers and the first user-visible text token.
Confirm the live region string actually changes on every transition you expect a screen reader to notice.
Tab the recovery path with a screen reader running, including the case where Stop is pressed before any token.
Only then point the same client at a remote endpoint, and compare frame kinds rather than the feeling of slowness.

These steps stay useful when the stall comes from a proxy, a sleeping laptop, or padding that keeps a socket open. The technique is the artifact I want to keep, which is separating transport liveness from answer progress in the client. Announcements and focus should bind to that distinction, or the interface will keep narrating a generation that never started. A remote endpoint is a later comparison, not the first place I try to understand a silent generating label.

A tiny log shape that survives the next bug

I keep a ring buffer of the last twenty frames as time, kind, and bytes, and I print it when the deadline fires. The buffer belongs in the bug report, not a spinner screenshot, because a screenshot cannot show the missing data line. Bytes matter here, because a comment heartbeat can be tiny and still look like real traffic in the network waterfall. If the buffer shows only heartbeat kinds, I stop profiling renders and go back to the parser before I touch CSS.

Trying the same probe against a free server

Disclosure: This article was prepared as part of MonkeyCode's product outreach. I mention the project here because a free server is a practical place to rerun this probe after the mock is green. A vendor name does not fix a silent live region, and I do not want this section to sound like a loading-state miracle. The outreach notes for this draft describe free model access, a free server option, and a stated allowance of ten million tokens.

I have not measured that allowance, I am not listing model names or hardware, and I am not treating the offer as permanent. Read the current project terms before you depend on them, because an outreach figure can change without this article changing with it. If you want a remote target, the free server option is a fair next socket after your mock fails on purpose. Keep the first-token deadline, the raw frame log, and the keyboard Stop path when you leave localhost for that server.

A free endpoint can still heartbeat, stall, or return a body that is not a token, so the same bug remains yours to fix. Open-source availability does not remove those checks, and a large token allowance does not announce itself to a screen reader. If this probe matches a bug you already have, try the current MonkeyCode free server only after you confirm the live terms yourself. I would rather you reproduce the stall locally first than treat a hosted socket as proof that the interface states are finished.

Who should not use this deadline as-is

Skip this client timer if your protocol already emits a typed error or a trusted first-token event before any heartbeat.
Do not use the eight-second demo constant as a capacity plan, a quota monitor, or a benchmark of any hosted model.
Do not treat aborting the reader as a security boundary, because it only returns control of the interface to the user.
Avoid this pattern if your product must preserve partial tokens across reconnects, since this demo discards an empty attempt instead.
Teams that cannot run a screen reader pass should not ship the status copy from this article without another review.

Limits of the reproduction

The mock never sends a real model delta, so it cannot tell you how a particular free model chunks text or emits comments. The eight-second constant will be wrong for long cold starts, and you should replace it from your own latency notes. A single polite region will still be too chatty if you later announce every token instead of phase changes only. I did not run a formal conformance audit, and this markup is a regression fixture rather than a claim of WCAG conformance.

Check	Environment note	Pass condition
Heartbeat does not enter streaming	Local mock, any browser	Status stays on waiting for the first token
Deadline announces stall	Screen reader on	No token arrived. Retry is available. is spoken
Stop before first token	Keyboard only	Focus returns to the composer and the request aborts
Retry after stall	Same page, no reload	New status announcement, old attempt not rewritten
Remote free server	After current terms are confirmed	Frame log distinguishes comments from tokens

Browser, operating system, and assistive technology versions will change announcement timing, which is why the matrix is part of the fix. If you rerun this, send the browser, the operating system, the assistive technology version, and the exact transition that failed. I care most about the jump from headers received to stalled, because that is the transition my first spinner completely hid. A generating label that never changes is not a loading strategy, and the first-token clock is what made that missing state visible.

A Cancelled Stream Needs a Generation Guard, Not Just a Stop Button

babycat — Thu, 08 Oct 2026 09:03:43 +0000

I opened a keyboard-only chat panel and pressed Escape as soon as the answer started wandering off topic. The spinner disappeared, focus landed in the composer, and I started typing a shorter follow-up prompt. A late sentence then appeared under the cancelled turn, and the screen reader spoke it over my half-finished words. Was the remote model ignoring cancel, or was my own client applying bytes it had already promised to drop?

That failure is quieter than a crashed tab and more dishonest than a slow spinner, because the interface claims a finished state. I reproduced it in a single-file demo instead of leaning on a production log I cannot publish here. The same race appears whenever a browser stream outlives the button that was supposed to end it. If the label says cancelled while the reader is still appending, who exactly did the user stop?

What the panel claimed versus what the reader did

I wrote the visible states down before I touched the fetch loop, because a polished spinner can hide a contradictory transcript. A stop control that only toggles a boolean will look finished while the network task is still alive. I wanted the table in front of me so every later patch had to name a state, not a vibe. Can you point at one row and say which writer is allowed to mutate the turn?

State	Composer	Stop control	Transcript	Status announcement
idle	enabled	removed from tab order	earlier turns only	silent
streaming	disabled	visible button	partial text, marked incomplete	one polite start
cancelling	disabled	busy, still present	partial text, still incomplete	Cancelling, once
cancelled	enabled and focused	removed	partial text, marked cancelled	Cancelled, once
stale chunk	must stay cancelled	removed	ignore the bytes	must stay silent

The last row is the bug itself, not a feature you should document in a tooltip and ship. If rendering can still enter that row, the stop button is only a costume over an open reader. I kept the table beside the demo and refused to change copy until that row became unreachable. A state you cannot name will come back as a spinner tweak that leaves the reader running.

How I misread the symptom

The first note I wrote blamed the screen reader, because the late sentence was announced after I had already moved on. I assumed the live region was too chatty, so I removed the live region and listened to the panel again. The spoken glitch went quiet, and the visual glitch stayed, since cancelled text still grew on the screen. Why would muting that one announcement repair a network writer that had never actually been aborted?

I then blamed the remote model, because those late bytes clearly arrived after I had pressed Escape. That story felt satisfyingly neat, and it explained nothing about a loop that still accepted every chunk. A local mock that sleeps between two fragments reproduced the same growth with no model anywhere in the path. Have you ever shipped a server-side fix for a client loop that was still happily reading?

Patches that looked finished and still failed

I tried three patches that would have made a tidy before-and-after screenshot, and each one left the stale row reachable. First I hid the Stop button immediately, which only made the false finished state faster to believe. Next I cleared the partial text on cancel, which deleted the evidence and still let a late chunk repaint a ghost turn. Then I debounced rendering, which postponed the glitch until I had started typing, so the race became ruder instead of gone.

None of those patches asked whether the original reader was still alive and still allowed to write. Have you noticed how often a loading fix is really just a visibility fix in a nicer coat? I kept a short note beside each attempt so I would not congratulate myself for making the bug quieter. The generation check finally made the stale row unreachable, and the canceled network row was the first observation that agreed.

The checks that found the real break

I stopped swapping visual components around and pinned three observations before I changed any behavior again. The list is short on purpose, because more logs would have let me hide from the id mismatch. I wanted each logged line to answer a question the button label was no longer allowed to answer alone. Can a longer checklist replace a state table, or does it only help once those states already have names?

Log the generation id on every incoming chunk, on cancel, and again on the next submit.
Confirm that fetch actually received an AbortSignal, not merely that an AbortController exists somewhere in memory.
Record focus and the status text at each transition, including any chunk that arrives after abort runs.

The chunk after cancel still carried generation 1, while the composer already belonged to generation 2. That single mismatch ended the argument that assistive technology was inventing a sentence on its own. The handler had flipped local state, and the first reader had never been told to stop writing. Would another CSS tweak, or a slower fade on the spinner, have surfaced that generation clash for me?

Commands I kept in the loop

I wanted a check I could rerun without clicking through the panel and trusting my memory of the race. The node test covers the writer logic, and the browser network row covers whether abort actually left the machine. If those two observations disagree, I trust the still-pending request over the button label every single time. Does your debug loop include a command, or only a story you retell after the demo looks calm?

node --test chat-stream.test.js
# In DevTools Network, press Escape and confirm the request shows (canceled).
# A row that stays pending after status is cancelled means abort never reached fetch.

Root cause, without the costume

The cancel handler set status to cancelled and cleared a loading flag that only the button could see. It never called abort, and the fetch options omitted the signal even after I had constructed a controller. The read loop also trusted the setter it closed over, so a late decode still appended to the finished turn. A local flag is not a generation guard, because the next network event can simply take that costume off.

Two in-flight requests were sharing one transcript slot, and both of them believed they still owned it. Which request is allowed to write into that slot once the user has already asked the panel to stop? I had answered that ownership question with a boolean, and the boolean lost the race to the open reader. Until those ids diverged in the log, I was debugging a costume instead of the writer underneath it.

A guard you can run before you pick a host

The module below is a local reproduction, not a production client and not a conformance claim of any kind. It uses a status union, a monotonic generation, and a controller whose signal actually reaches the reader. Swap the mock for your real endpoint only after the assertion proves those late chunks are dropped. I am not claiming that this small mock matches every server event framing or every error payload shape.

/** @typedef {'idle'|'streaming'|'cancelling'|'cancelled'|'error'} Status */

export function createChatStream() {
  let generation = 0;
  let controller = null;
  let status = /** @type {Status} */ ('idle');

  async function start(prompt, onEvent) {
    controller?.abort();
    const mine = ++generation;
    controller = new AbortController();
    status = 'streaming';
    onEvent({ type: 'status', status, generation: mine });

    try {
      for await (const chunk of streamTokens(prompt, controller.signal)) {
        if (mine !== generation) return;
        onEvent({ type: 'chunk', text: chunk, generation: mine });
      }
      if (mine === generation) {
        status = 'idle';
        onEvent({ type: 'status', status, generation: mine });
      }
    } catch (error) {
      if (error.name === 'AbortError' && mine === generation) {
        status = 'cancelled';
        onEvent({ type: 'status', status, generation: mine });
        return;
      }
      if (mine === generation) {
        status = 'error';
        onEvent({
          type: 'status',
          status,
          generation: mine,
          message: 'Stream failed before completion'
        });
      }
    }
  }

  function cancel(onEvent) {
    if (status !== 'streaming') return;
    status = 'cancelling';
    onEvent({ type: 'status', status, generation });
    controller?.abort();
  }

  return { start, cancel };
}

async function* streamTokens(prompt, signal) {
  const parts = [`Draft for ${prompt}.`, ' Trailing clause that should not land.'];
  for (const part of parts) {
    await new Promise((resolve, reject) => {
      const timer = setTimeout(resolve, 50);
      signal.addEventListener('abort', () => {
        clearTimeout(timer);
        reject(new DOMException('Aborted', 'AbortError'));
      }, { once: true });
    });
    yield part;
  }
}

Notice the early return when mine no longer matches the generation that now owns the composer. Abort alone is not enough if a chunk was already decoded in the moment before the signal fired. Do you check the generation before you render text, or only in the moment before you call abort? I keep the assertion next to the demo so a quiet visual success cannot hide a trailing clause.

import assert from 'node:assert/strict';
import { createChatStream } from './chat-stream.js';

const events = [];
const chat = createChatStream();
const pending = chat.start('explain cancel', (event) => events.push(event));
chat.cancel((event) => events.push(event));
await pending;
const late = events.filter((event) => event.type === 'chunk' && event.text.includes('Trailing'));
assert.equal(late.length, 0);
assert.equal(events.at(-1).status, 'cancelled');

This assertion does not prove what a screen reader will speak after the status event finally lands. It only proves that the writer stopped applying the trailing clause after cancel had won the race. I still have to listen with the status element connected, because the test never opens a browser. If the trailing clause appears in the log, the guard is wrong, no matter how calm the button looks.

Wiring keys without trapping the panel

Escape should call the same cancel path as the Stop button, and it should not become a keyboard trap. I listen on the panel, ignore Escape when status is already idle, and move focus only after cancelled. The incomplete turn keeps a visible note that says the response was cancelled and the partial text was kept. Retry starts a new generation on purpose, and it does not rewrite the cancelled turn in place afterward.

panel.addEventListener('keydown', (event) => {
  if (event.key !== 'Escape') return;
  event.preventDefault();
  chat.cancel((update) => render(update));
});

What should be announced, and what should stay quiet

I announce the start of a stream once, and I announce cancel once, in a polite status element outside the transcript. Token chunks update the transcript visually, and they do not each poke a live region as if they were new messages. After cancel, focus moves to the composer only when the status event says cancelled, not while it still says cancelling. A chatty region would make an honest cancel feel like a brand new answer that arrived too late.

The Stop control is a real button, and I remove it from the tab order when the stream is idle.
I avoid aria-disabled on that button, because a disabled control can swallow the click we still need during cancelling.
The cancelled turn exposes the partial text plus a plain sentence that names the outcome for anyone who cannot see the styling.
A retry control is a separate button, and it does not pretend the old turn suddenly completed.

Markup the status, not the transcript

The status element is a paragraph with role status, and the composer points at it through aria-describedby. I do not put an aria-live attribute on the transcript, because every token would then become its own announcement. The Stop button is a native button beside the composer, so it stays in tab order only while a stream exists. Can you reach Stop, then Escape, then the composer without a mouse, even while the first chunk is still arriving?

<p id='stream-status' role='status'>Cancelled. Partial text kept.</p>
<button type='button' id='stop'>Stop</button>
<textarea id='composer' aria-describedby='stream-status'></textarea>

Focus order after cancel

Focus should land on the composer, not on a toast that disappears before a screen reader user can read it. I move focus in the status handler for cancelled, and I do not move it again on every arriving chunk. If a retry button appears, it comes after the composer in tab order so Escape and then typing still works. Would you rather recover the draft you started, or hunt for a toast that has already unmounted itself?

Using a free server only as a slower clock

I did not need a private GPU box just to hear this race on a real network path. Free model access and a free server option from MonkeyCode were enough to leave the mock and hit actual delay. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I pointed the same guarded client at that free server and used it only as a second target.

I am not quoting a model list, a token quota, or an uptime promise in this draft. Those figures were not in the sources I had, and I will not invent them to sound specific. The free server did not fix the bug, and it should not get credit for the generation check. What it changed was the gap between abort and the last buffered chunk, which made the stale write obvious in DevTools.

A slower network clock is useful while debugging, and it is not evidence that the host cancelled work for you. If your proxy buffers the stream, will the panel still tell the truth when that buffer finally arrives late? I still needed the generation guard, because the extra delay only made a client lie easier to see. Check the current access page before you depend on any host, since availability language goes stale fast.

The matrix I want attached to any bug report

Run the mock first, then one remote target, and write down the assistive technology instead of a local shrug. Hidden-tab cancellation is a different bug, so I am not folding visibility handling into this particular guard. I want the matrix attached to the report so we can see which transition failed, not which theme was on screen. Have you ever closed a streaming bug with a screenshot that never showed the cancelled state at all?

Check	Input	Screen reader	Expected
Escape on first chunk	Escape	on	status cancelled, trailing clause absent
Stop, then type	Tab to composer	on	new keys not interrupted by old tokens
Cancel, then retry	Enter on Retry	on	new generation, old turn unchanged
Abort while the request fails	Escape	off	one error, composer recoverable
Signal omitted on purpose	Escape	off	request stays pending; this is the old bug

Please include the browser, the operating system, and the assistive-technology version when a row fails. The useful detail is the transition, not a screenshot of a finished answer sitting under a calm spinner. I would rather read one failing row than another note about how the loading color feels. Which row would you actually trust if the button and the network panel disagreed?

Who should not ship this, and what it cannot prove

This guard stops the client from painting stale tokens, and that is the whole claim I will stand behind today. It does not prove the server halted generation, released capacity, or stopped metering the usage on its side. If your real risk is privacy or cost on the server, you need a cancel API and a test that watches the upstream log. A green client test can sit beside a server that is still generating into a buffer you no longer read.

Do not treat this pattern as your only accessibility plan, and do not treat ARIA as the repair for a still-running reader. Skip it when you cannot pass an AbortSignal into fetch, or when each chunk replaces the transcript and throws focus away. I would also skip it for untrusted partial HTML, because a generation check will not make streamed markup safe to inject. Who is this for, then, if it refuses to promise a server stop or a conformance badge at the end?

I have not measured latency, quota consumption, or conformance, and one listening pass is not a WCAG claim. The stream helper is a stand-in with a fixed delay, so your parser still has to honor the signal and the generation together. If you replay the race on a free inference host you can already reach, send the failing matrix row with versions. Please include your browser, operating system, and screen reader versions instead of another happy-path capture.

A Superseded AI Stream Needs a Stable Status Region, Not a Focus-Stealing Toast

babycat — Thu, 08 Oct 2026 06:28:12 +0000

I sat down to cancel a streamed rewrite and lost the caret to a toast that vanished before I could read it. I pressed Escape because the tone had drifted, and I expected the textarea to keep focus the whole time. Instead a small notice mounted, called focus, and removed itself on a timer. The screen reader then announced Draft saved, which belonged to an older success, not to the cancel I had just requested.

Have you ever trusted a status line that was describing a state you had already left behind? I rebuilt that exact failure as a single-file lab, after a week of DEV posts about vibe-coded pages and whether they stay operable. That conversation was only a topic nudge, not evidence that the toast behavior itself was correct. This walkthrough is a reconstructed reproduction, not a customer incident, and it does not report production metrics.

The remote leg can use MonkeyCode's free model access and its free server option, only so you can abort a real hosted stream. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I am not claiming a particular model, quota, region, or uptime, because those details were not part of what I verified. The defect sits in status and focus code, not in whatever endpoint happens to answer the request.

What broke, in the order I saw it

The visible symptom is small enough that a sighted click-through can miss it entirely. After Escape, the textarea loses focus, and Tab from the document body skips the composer until a click. A second later the page looks calm, because the toast has already unmounted and left no trace. Why would a cancel path announce a save if the network panel showed an aborted request?

I write the sequence down before I change a single line, because memory is a terrible debugging log. The order is submit, tokens, Escape, toast focus, toast removal, then a late status write from the previous generation. If you skip that timeline, you will fix the toast and leave the lying announcement in place. That is the retrospective method I trust: freeze the timeline, then change one writer at a time.

A state table before any more code

Phase	Trigger	Focus	What the status region may say	Stream
idle	load	composer	nothing	none
connecting	submit	composer	Connecting to the suggestion stream.	abort older, open new
streaming	first chunk	composer	Suggestion stream started.	read body
superseded	submit while active	composer	Previous suggestion stopped. A newer request is starting.	abort old generation
cancelling	Escape or Cancel	composer	Cancelling the suggestion.	abort current
cancelled	abort settles	composer	Suggestion cancelled. Composer is ready.	closed
failed	network or bad status	composer, then Retry	Suggestion failed. You can retry from the composer.	closed

That table is the artifact I now keep open beside the component while I edit any transition. If a transition is not listed in the table, the code is not allowed to announce it. Does your streaming panel have a row for a newer request replacing this one, or only a happy path and a generic error? I draw the table before I touch fetch, because the announcement text is part of the interface contract.

How I trace it without guessing

I treat this like any other race condition, not like an accessibility mystery that needs a special theory. These checks are cheap to add, and they transfer cleanly to other live regions you already own.

I log every phase change with a generation integer, the previous phase, and a short reason string.
I listen for focusin and print the target id, so a toast cannot steal focus silently.
I observe the status node and record every text change, including clears, together with a timestamp.
I abort the in-flight work with AbortController, then ignore any response whose generation id no longer matched.
I refuse to map an older HTTP 200 onto the current phase, even when its body says the draft was stored.

A listener that convicts the toast

A one-line focus logger is enough to convict a toast of stealing the caret after Escape. Paste it before you restyle anything, and keep the phase variable in the same closure.

document.addEventListener("focusin", (event) => {
  const id = event.target.id || event.target.tagName;
  console.log(JSON.stringify({ t: performance.now(), id, phase }));
});

When you run that listener, a toast that calls focus prints its id after Escape, before the status text settles. I am describing the check to run, not a captured production trace or a measured latency budget. Would you have noticed that focus jump if you had only been watching the network panel carefully?

The root cause was three writers

Why the live region lied

The toast called focus on mount because a library example treated every notice as if it were a dialog. It was not a dialog, it had no accessible role, and it disappeared on a short timer. When it unmounted, focus fell back to the document body instead of returning to the textarea. That is a real focus bug, but it was not the whole lie the screen reader spoke.

The status region still held the words Draft saved from the previous successful run I had finished. My render path appended text and never replaced it, so an empty update did not clear the node. A late response from generation three then wrote a save message while generation four was already cancelling. The browser coalesced those polite updates, and the screen reader spoke the stale save out loud.

I had also classified a disconnect from the free server as success, because an earlier handler treated any completed fetch as saved. A completed fetch can mean saved, cancelled, or superseded, depending on which generation still owns the request. Which of those three outcomes did my old mapper actually know when that late response body arrived? None of them, until I passed the reason into the announcer instead of inferring it from status codes.

One announcer, and focus stays put

This reproduction is a proposal you can paste into a static file and drive by hand. It does not vendor a model SDK, and it does not claim the timings you will see on your own network. Point /api/suggest at a proxy you control. Do not invent a vendor path you have not read in current docs.

<form id="composer">
  <label for="prompt">Rewrite brief</label>
  <textarea id="prompt" name="prompt"></textarea>
  <button type="submit">Stream suggestion</button>
  <button type="button" id="cancel">Cancel</button>
  <button type="button" id="retry" hidden>Retry</button>
</form>
<p id="stream" tabindex="-1"></p>
<div id="status" role="status" aria-live="polite" aria-atomic="true"></div>

const announcements = {
  connecting: "Connecting to the suggestion stream.",
  streaming: "Suggestion stream started.",
  superseded: "Previous suggestion stopped. A newer request is starting.",
  cancelling: "Cancelling the suggestion.",
  cancelled: "Suggestion cancelled. Composer is ready.",
  failed: "Suggestion failed. You can retry from the composer."
};

let phase = "idle";
let generation = 0;
let controller = null;
const status = document.querySelector("#status");
const prompt = document.querySelector("#prompt");
const retry = document.querySelector("#retry");
const stream = document.querySelector("#stream");

function announce(next, reason) {
  if (phase === next) return;
  phase = next;
  status.textContent = announcements[next] || "";
  retry.hidden = next !== "failed";
  if (document.activeElement !== prompt) prompt.focus();
  console.log(JSON.stringify({ next, reason, generation }));
}

async function readBody(response, mine) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const step = await reader.read();
    if (mine !== generation) return;
    if (step.done) return;
    stream.textContent += decoder.decode(step.value, { stream: true });
  }
}

async function startStream(text) {
  const mine = ++generation;
  if (phase === "connecting" || phase === "streaming") {
    announce("superseded", "new-submit");
  }
  controller?.abort();
  controller = new AbortController();
  announce("connecting", "submit");
  stream.textContent = "";
  try {
    const response = await fetch("/api/suggest", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ text, generation: mine }),
      signal: controller.signal
    });
    if (mine !== generation) return;
    if (!response.ok || !response.body) throw new Error("bad-status");
    announce("streaming", "headers");
    await readBody(response, mine);
  } catch (error) {
    if (mine !== generation) return;
    if (error.name === "AbortError") announce("cancelled", "abort");
    else announce("failed", "request");
  }
}

document.querySelector("#composer").addEventListener("submit", (event) => {
  event.preventDefault();
  startStream(prompt.value);
});

document.querySelector("#cancel").addEventListener("click", () => {
  announce("cancelling", "button");
  controller?.abort();
});

prompt.addEventListener("keydown", (event) => {
  if (event.key === "Escape") {
    event.preventDefault();
    announce("cancelling", "escape");
    controller?.abort();
  }
});

Save the script as announcer.mjs only if you extract the logic without the DOM, then run node --check announcer.mjs before you open the page. The important line is the generation guard that runs before any announcement is written into the region. A late body chunk must not be allowed to speak for a request the user already replaced. I move focus back to the composer on purpose, because this notice is not a control the user asked to operate. If you truly need a blocking choice, use a real dialog with a focus trap and a named cancel, not a timer.

Checks I run before I trust the region

I do not claim any conformance level from this checklist alone, and you should not infer one. I only claim that these transitions are the ones that lied, and I do not want them failing quietly again.

Start a stream, press Escape, and confirm that keyboard focus remains on the textarea the whole time.
Submit again while tokens are still arriving, and confirm the status says the previous suggestion stopped.
Force a failed response, and confirm Retry is visible, focusable, and does not replace the prompt text.
Leave an old Draft saved string in the status node, then cancel, and confirm the node text was replaced rather than appended.
Tab through the form with a screen reader and confirm the stream output is readable without stealing the caret.
Repeat the cancel with a pointer, the keyboard, and a screen reader, in at least two desktop browsers.

Environment notes

If you reproduce it, tell me the browser, the OS, the assistive technology version, and the exact transition that lied. That kind of failure report is more useful to me than another screenshot of the happy path. A polite region is enough for cancel and supersede, because focus never leaves the composer and the user can keep typing. An assertive region is the wrong volume here, unless you are warning about lost work that a polite update might miss.

Who should skip this pattern

This pattern is only a client state machine for one composer and one polite status region beside it. It will not save you if the product needs an interruptive alert or a guaranteed capacity contract. It also will not replace a proper design study of whether people want streamed suggestions at all. A free model route and a free server option are convenient for the remote leg of a lab reproduction. They are the wrong dependency if you need a named quota, a pinned model, or an uptime promise I have not verified.

Do not point production traffic at an unlabeled free option and then encode its hiccups as a successful save. Do not use a polite live region for a destructive confirmation that the user must not miss. Do not autofocus a toast that is not a dialog and does not expose a reliable keyboard dismiss. If your only goal is visual polish, this debugging loop will feel slow, and you should not pretend the status region is optional.

I would reuse the same generation log the next time a stream and a notice disagree about the outcome. The question I keep taped above the monitor is almost embarrassingly simple, and it still catches me. If this response belongs to an older request, why is the client still allowed to speak it?

If you want a hosted stream you can cancel on purpose, MonkeyCode's free model access and free server option can stand up that remote leg. Keep the state table next to the component, and treat any availability detail you have not checked as unknown. I would rather you reproduce the cancel path than take my word for any of the announcement text.

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.

DEV Community: babycat

Unexpected End of JSON Input: Debugging a Tool Call That Streamed Half a Brace

The state table I wish I had drawn first

Reproduce it without a key, a quota, or a network

Root cause one: I parsed a delta like a document

Root cause two: finish_reason: "length" is not an exception

The accessibility contract for half-finished output

Where I reproduced it, and why that matters

A QA matrix, because one browser lies

Limitations, and who should skip this

The question I now ask before every stream

The Health Check Said 200 While the Model Said 401: Debugging a Silent Endpoint Fallback

Why this failure got common in the last few months

The symptom, written as a state table

Step 1: Stop trusting the app and run the request yourself

Reading rung 3 without over-reading it

Step 2: Dump the config the app actually resolved

The trailing /v1 trap

Step 3: Replace the health check with a readiness probe

Step 4: Map every transport outcome to one UI state

The accessibility rules that keep that table honest

Step 5: Wrap it in a typed state machine

A verification matrix you can run in an afternoon

Limitations, and who should not do this

The Retry Never Got Announced: Debugging a Stuck aria-busy in a Streaming Chat

The report was suspiciously specific

First hypothesis: "we forgot the live region" (wrong)

Reproducing it in one file

The buggy client, in eleven lines

Why the happy path hid it

The state table I should have written first

Fix: derive aria-busy, never set it

Tests that would have caught it

A manual pass you fill in, not one I fill in for you

Limits, and who should skip this

What I check first next time

A Retry Button Sent the Same Prompt Twice: Debugging Idempotency in a Streaming Chat

The failure is two different requests wearing one button

Reproduce it with one idempotency key

The client fix: reuse the key, guard the click

What the screen reader and keyboard need

A QA matrix you can repeat

Where MonkeyCode fits, and where this design stops

The Stop Button Worked Once: Debugging a Reused AbortController in a Streaming Chat

Reproduce it before you theorise

The root cause was a useRef with a lifetime problem

Fix: bind the controller to the attempt, not the component

What the assistive technology actually heard

My test plan, and the matrix I run it in

Where MonkeyCode genuinely fit into this loop

Limitations and who should skip this

What I check first next time

Focus Left the Copy Button Every 200 ms: Debugging a Streaming Markdown Panel

Focus Left the Copy Button Every 200 ms: Debugging a Streaming Markdown Panel

The symptom, written down before touching anything

Step 1: Turn the report into a failing test

Step 2: Bisect the surface, not the source

Step 3: The root cause is node identity

Step 4: Fix it with stable nodes and a commit boundary

Step 5: Regressions that catch this whole class of bug

The QA matrix I now fill in

Where the reproduction lived

Limitations, and who should skip this approach

Reproduce it and tell me what breaks

A Token Stream That Arrives All at Once: Debugging Buffering From Symptom to Fix

Write the state table before you touch the network tab

Rule out the model before you blame the model

The three places a stream actually gets held

A relay that lies, in about thirty lines

The fix, and why "just add flush" is only half a fix

Why localhost cannot reproduce this, and what to do about it

Limitations, and who should skip this

The QA matrix I would run before closing the ticket

A Token Stream Needs a Quiet Buffer, Not an Assertive Live Bubble

What looked finished and what sounded broken

A symptom table I refused to skip

How I read the rows

Three listeners before any CSS change

A repeatable local burst

Root cause, underneath the costume it wore

Root cause two: `finish_reason: "length"` is not an exception

The trailing `/v1` trap

The root cause was a `useRef` with a lifetime problem