DEV Community: babycat

Streaming Agents Need a Tool-Call Focus Lock, Not a Toast Over the Composer

babycat — Thu, 10 Sep 2026 14:56:43 +0000

Last Tuesday I tabbed into a streaming agent chat and typed a harmless question about a local config file. The model started streaming tokens, then a pale toast asked whether a read_file tool could run. Did I notice that prompt while my caret still blinked inside the composer? I pressed Enter again because the textarea still looked hungry, and the agent read a file I never meant to grant.

This write-up is a reconstructed lab on a single-file page, not a named-product incident report with fake metrics. I wanted a reusable debugging path from symptom to root cause, because agent UIs now emit tool calls in the same stream as prose. If your confirmation lives outside the tab order, the next key still belongs to the composer. Have you ever watched a permission chip lose to a still-enabled textarea?

The failure was a focus race, not a smarter model

People keep saying agents assume too much, and the model often does exactly that. But the frontend assumed something worse: that a toast plus a live region equals informed consent. Keyboard users then hit Enter in the composer, which the app treats as “yes, run the tool” or as a second user turn. Either reading is a product bug, and neither one shows up in a happy-path screenshot.

I logged every transition with a tiny state machine instead of sprinkling more ARIA on the toast. The table below is the first artifact I trust, because pictures of chips do not show caret location. If a row cannot name the focused node, it is not a permission flow yet.

State	Composer	Tool UI	Live region	Focus
`idle`	enabled	hidden	silent	composer
`streaming`	disabled	hidden	polite tokens	stay put
`tool_pending` (broken)	still enabled	toast, not tabbable	still announcing	composer
`tool_locked` (fixed)	inert	modal dialog	paused	first dialog control
`executing`	disabled	status only	assertive once	status, then composer
`denied`	enabled	history note	assertive once	composer

Notice how tool_pending looks almost finished during a visual QA pass. The toast is on screen, the copy is correct, and a pointer user can click Allow. So why did my Enter key approve the wrong thing? Because focus never left the textarea, and the toast was never a dialog.

Debugging technique: a focus timeline, not another spinner

I stopped asking “is the toast visible?” and started asking “what element holds focus at each token?” That sounds obvious, yet streaming UIs fight you, because the DOM mutates while you Tab. I recorded a timeline with focusin bubbling on document, plus a queue of tool-call events from a fake stream. Can you guess the first surprise? The toast mounted during a focusin on the composer, so the browser never fired a second focusin for the prompt.

Checks I now run on every agent surface

Snapshot document.activeElement on every stream event, not only on click.
Freeze the live region when a tool call arrives, or leftover tokens bury the prompt.
Count tab stops after mount; a toast with no tab index is a silent wall.
Press Enter and Escape as if they were API contracts, then record the landed state.
Refuse auto-approve timers; a countdown is not consent for a file or network tool.

I also drew the intended machine before writing markup, because CSS cannot rescue a missing gate. The stream is allowed to talk only while no side-effect tool is waiting.

idle -> streaming -> tool_locked -> executing -> idle
                 \-> tool_locked -> denied -> idle
                 \-> error
streaming -> (tool event) MUST pause token announcements

Root cause, in the order I actually found it

First, the confirmation was a toast. It used a role="status" region so pointer users saw it, while keyboard users never entered it. Second, the composer stayed enabled, so Enter still meant “send” during a permission beat. Third, the token live region stayed polite and talkative, so a screen reader never treated the prompt as the next task. Fourth, a five-second auto-approve tried to be helpful for demo gifs, which is how a file tool ran while I was still reading.

None of that is an ARIA shortage. It is a missing gate in the state machine. Would a louder live region have saved me? Probably not, because the caret still owned Enter, and the Stop button still meant “cancel generation,” not “deny this file.” Mixing those two jobs is how you get a second control that looks like a retry from last month’s chat bugs.

What Enter meant in each broken beat

In streaming, Enter in the composer queued a second user turn on top of unread tokens.
In tool_pending, Enter never reached Allow or Deny, because those nodes were not focusable.
After auto-approve, Enter landed in a composer that had already granted read_file.
Escape closed nothing useful, because a toast is not a modal with a cancel contract.

The fix: lock focus, pause the stream chrome, require an explicit answer

The repair is a modal tool-call dialog that opens on tool_locked, moves focus to a safer button, and sets the transcript inert. I pause polite token announcements until Allow or Deny settles the turn. I do not auto-approve, and I do not reuse Stop as Deny, because Stop already means “cancel generation” in this UI family. Deny writes a retired tool turn into the transcript, then returns focus to the composer.

Expected UI states

Streaming prose: composer disabled or read-only, Stop visible, tokens in a polite region.
Tool locked: native dialog with aria-modal behavior, Allow/Deny, filename in the heading, background inert.
Executing: dialog closes, a single assertive status, composer still disabled until the tool returns.
Denied: dialog closes, history shows “Tool skipped,” composer enabled, focus back in the textarea.
Malformed tool payload: dialog stays until dismissed; do not fail open into Allow.

Default focus goes to Deny, not Allow. That feels slightly rude in a marketing gif, and that is the point. A file tool is not a cookie banner.

Minimal reproduction

The page below is labeled as a lab fixture. It fakes a stream that ends in read_file JSON so you can watch focus without a paid model. Paste it into an .html file, start a local static server, and Tab through the Send control.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Tool-call focus lock lab</title>
  <style>
    :root { font-family: system-ui, sans-serif; }
    body { margin: 1.5rem; max-width: 42rem; }
    #log { min-height: 8rem; border: 1px solid #444; padding: 0.75rem; }
    #composer { width: 100%; min-height: 4rem; }
    dialog::backdrop { background: rgb(0 0 0 / 45%); }
    .row { display: flex; gap: 0.5rem; margin-top: 0.75rem; }
  </style>
</head>
<body>
  <h1>Agent transcript</h1>
  <p id="status" aria-live="polite"></p>
  <div id="chrome">
    <div id="log" aria-live="polite" aria-relevant="additions"></div>
    <label for="composer">Message</label>
    <textarea id="composer"></textarea>
    <div class="row">
      <button id="send" type="button">Send</button>
      <button id="stop" type="button" disabled>Stop</button>
    </div>
  </div>
  <p>State: <span id="stateLabel">idle</span></p>
  <p>Focus: <span id="focusLabel">-</span></p>

  <dialog id="toolDialog" aria-labelledby="toolTitle">
    <h2 id="toolTitle">Allow read_file?</h2>
    <p>The agent wants to read <code id="toolArg">unknown</code>.</p>
    <div class="row">
      <button id="allow" type="button">Allow</button>
      <button id="deny" type="button">Deny</button>
    </div>
  </dialog>

  <script>
    /** @typedef {"idle"|"streaming"|"tool_locked"|"executing"|"denied"} AgentState */

    const els = {
      log: document.getElementById("log"),
      status: document.getElementById("status"),
      chrome: document.getElementById("chrome"),
      composer: document.getElementById("composer"),
      send: document.getElementById("send"),
      stop: document.getElementById("stop"),
      dialog: document.getElementById("toolDialog"),
      toolArg: document.getElementById("toolArg"),
      stateLabel: document.getElementById("stateLabel"),
      focusLabel: document.getElementById("focusLabel"),
      allow: document.getElementById("allow"),
      deny: document.getElementById("deny"),
    };

    /** @type {AgentState} */
    let state = "idle";
    let timer = 0;
    let announceTokens = true;

    function setState(next) {
      state = next;
      els.stateLabel.textContent = next;
      const locked = next === "tool_locked";
      const busy = next === "streaming" || next === "executing" || locked;
      els.composer.disabled = busy;
      els.send.disabled = busy;
      els.stop.disabled = next !== "streaming";
      els.chrome.toggleAttribute("inert", locked);
      if (next !== "streaming") announceTokens = false;
    }

    function line(text) {
      const p = document.createElement("p");
      p.textContent = text;
      els.log.appendChild(p);
    }

    document.addEventListener("focusin", () => {
      const active = document.activeElement;
      els.focusLabel.textContent = active ? (active.id || active.tagName) : "none";
    });

    function fakeStream() {
      setState("streaming");
      announceTokens = true;
      els.status.textContent = "Streaming";
      const chunks = ["Checking the repo layout.", " I need a file to answer."];
      let i = 0;
      timer = window.setInterval(() => {
        if (state !== "streaming") return;
        if (i < chunks.length) {
          if (announceTokens) line(chunks[i]);
          i += 1;
          return;
        }
        window.clearInterval(timer);
        openToolGate({ path: "config/dev.env" });
      }, 400);
    }

    function openToolGate(call) {
      setState("tool_locked");
      announceTokens = false;
      els.status.textContent = "Tool confirmation required";
      els.toolArg.textContent = call.path;
      els.dialog.showModal();
      els.deny.focus(); // safer default
    }

    function closeGate() {
      if (els.dialog.open) els.dialog.close();
    }

    els.send.addEventListener("click", () => {
      if (state !== "idle" && state !== "denied") return;
      line("You: " + (els.composer.value || "What is in the env file?"));
      els.composer.value = "";
      fakeStream();
    });

    els.stop.addEventListener("click", () => {
      window.clearInterval(timer);
      closeGate();
      setState("idle");
      els.status.textContent = "Generation stopped";
      els.composer.focus();
    });

    els.allow.addEventListener("click", () => {
      closeGate();
      setState("executing");
      els.status.textContent = "Running read_file";
      window.setTimeout(() => {
        line("Tool result: DEV=1 (redacted)");
        setState("idle");
        els.status.textContent = "Tool finished";
        els.composer.focus();
      }, 600);
    });

    els.deny.addEventListener("click", () => {
      closeGate();
      line("Tool skipped: read_file");
      els.status.textContent = "Tool denied";
      setState("idle");
      els.composer.focus();
    });

    els.dialog.addEventListener("cancel", (event) => {
      event.preventDefault();
      els.deny.click();
    });
  </script>
</body>
</html>

Broken variant for the same lab: replace showModal() with a toast div, leave the composer enabled, and keep announceTokens = true. That is the Enter-key failure from the opening story. Do not ship the broken variant; keep it as a regression fixture beside the dialog.

Keyboard and screen-reader regressions I actually care about

I do not claim a conformance badge. I claim these transitions either hold or they do not, and I want the failing beat named in the bug.

Tab from Send into the dialog after a tool event; Tab must not land in the inert transcript.
Shift+Tab at the first dialog control should cycle inside the dialog, not vanish into chrome.
Enter on Deny must not send a new chat turn, even if the textarea still looks focused on screen.
Escape maps to Deny, never to Allow, and never to a half-closed toast.
After Allow, focus must not remain on a disconnected button node that React already unmounted.
While the dialog is open, the transcript live region must not keep narrating leftover tokens.

Environment notes worth attaching to a bug

If you reproduce this, send the browser, OS, and assistive-technology versions plus the exact transition that failed. A clip of the focus label in this page is more useful than a Lighthouse score. I did not run a full AT matrix for this lab, so treat the list as a checklist, not as evidence I already passed VoiceOver, NVDA, and TalkBack on every engine.

Where a free stream host actually helped

I needed a disposable stream of tool-call events so I could refresh the dialog dozens of times without burning a paid quota. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project with free model access and a free server option, which is enough to host this single-file lab and replay a tool-call stream while you watch document.activeElement. I am not attaching model names, token ceilings, hardware claims, or permanence promises, because those change and I did not benchmark them here.

If you already have a local mock, you do not need that host. The state machine is the point, and a static file already exposes the Enter-key race. Use the free server only when you want the same dialog sitting in front of a real streamed tool-call payload.

Limitations, and who should not copy this

Native <dialog> still differs across browsers when you nest popovers or restore focus into a virtualized transcript. inert on a huge chat list can get expensive if you re-render every token as a React node; pause the token source instead of wrapping an enormous tree on each chunk. This gate is for tools with side effects: files, shell, email, payments. Do not block a harmless search_docs call behind a modal if your product already sandboxes that tool.

Skip this pattern if you are building a headless batch agent with no human in the loop. Skip it if your “agent” never emits tool calls from the browser. Skip it if you were about to add a default-yes countdown to make a demo gif smoother. That countdown is how I granted read_file with my face still in the composer.

The next time a streaming agent asks for a tool, ask one rude question before you ship the toast: where is focus, and which key still means Send?

Streaming Chat Needs a Content-Type Guard, Not Infinite aria-busy

babycat — Thu, 10 Sep 2026 04:01:24 +0000

I tabbed into a throwaway chat shell, typed a short prompt, and pressed Enter. The composer went quiet, the Stop control took focus, and the status text froze on Generating. A polite live region never moved past that frozen word, so the transcript felt abandoned. Have you seen a stream UI that looks busy while the network request already finished?

The Network panel showed a completed document with a closing time, not an open event stream. So why did aria-busy stay true on the conversation log after the bytes had already landed? Nothing in the transcript was still downloading, and the Stop control had nothing left to abort. That mismatch is the whole incident, and it is easy to miss if you only watch the spinner.

What failed, and what this is not

This walkthrough is a debugging retrospective for a keyboard-operated chat, not a design-strategy essay. I wanted an interface that stayed understandable through loading, error, cancellation, and recovery without a mouse. The shell already had a Stop control, a retry path, and a client watchdog, yet none of those honest states fired. I was staring at a generating label that described a stream that had already ended.

I am not replaying a cancelled reader that never released the composer after Stop. I am not rebuilding a live heading tree inside streaming Markdown as the tokens land. This failure happened before the token parser saw a single data: line, so those later defenses never woke up. Those older bugs are real, but they are not this one, and mixing them hides the MIME mistake.

If your phase table includes connecting and streaming but omits a non-SSE failure, an HTML body will impersonate a live stream. Screen readers then sit on Generating until somebody finally closes the tab in frustration. Is that an accessibility bug, a protocol bug, or a state machine that never learned to fail? It is both kinds of failure, and the chat UI still owns the recovery path.

The state table I needed on day one

Phase	Composer	`aria-busy` on the log	Status text	Focus	Stop
`idle`	enabled and named	`false`	silent	composer	absent
`connecting`	`aria-disabled`	`true`	Connecting to the model.	Stop	present
`streaming`	`aria-disabled`	`true`	Generating a response.	Stop	present
`failedNonSse`	enabled and named	`false`	The server returned a page, not a stream.	composer	absent
`failedHttp`	enabled and named	`false`	Status-specific error	composer	absent
`cancelled`	enabled and named	`false`	Generation cancelled.	composer	absent
`complete`	enabled and named	`false`	Response complete.	composer	absent

Draw that table before you style another spinner. The missing row is usually failedNonSse, and every later control depends on it. If Stop only disappears in CSS, keyboard users still sit on a control that cannot abort a finished page.

Symptom to root cause

I treated the silence like any other stuck state machine in the browser. The sequence below is the reusable debugging method, and you can run it on any chat shell. Keep notes in this order so you do not jump straight into another spinner tweak.

Confirm the pointer-independent path. I submitted with Enter, not a mouse click, and Tab remained inside the composer until that submit.
Record focus immediately after submit. Focus moved to Stop, which is correct only while a stream is abortable.
Record announcements. The log exposed aria-busy="true" and a polite Generating status, then nothing else spoke.
Inspect the network timing. The request completed, and Content-Type was text/html; charset=utf-8.
Read the body as text. It was a generic error page from the remote process, not server-sent events.
Trace the parser. The client still awaited data: lines on a ReadableStream reader, so the phase never left streaming.

The analogy I keep using is a station board that stays on Arriving because the station posted a closed notice instead of a timetable. The board is not slow, and the passengers are not impatient for no reason. It is reading the wrong document type, and the spoken status keeps promising a train that already vanished.

Why did a finished fetch lie to the interface so easily? I keyed the happy path off response.ok and a non-empty body, not off Content-Type. Shared and free servers often answer with HTML for cold starts, proxy errors, or login gates. A 200 HTML page is enough to trap aria-busy until reload.

Decision table for the first header

`Content-Type` (essence)	Next phase	Why
`text/event-stream`	`streaming`	Tokens may arrive.
`text/html`	`failedNonSse`	This is a page, not a stream.
`application/json`	`failedNonSse` unless you intentionally chose unary JSON	A chat log should not parse a JSON error as Markdown.
missing or empty	`failedNonSse`	Do not guess SSE.

If you only branch on HTTP status, you will miss the 200 HTML case. That case is the one that feels haunted, because the network waterfall looks finished while the log still claims work. Have you ever trusted response.ok and then watched the composer stay locked for no visible reason?

A typed phase machine, not a boolean

Booleans such as isLoading cannot tell a screen reader what happened. You need a phase that can die as failedNonSse without pretending tokens arrived. The labeled example below is a proposal you can paste into a single-file TypeScript shell.

type ChatPhase =
  | { kind: "idle" }
  | { kind: "connecting" }
  | { kind: "streaming"; buffer: string }
  | { kind: "complete"; buffer: string }
  | { kind: "failedNonSse"; detail: string }
  | { kind: "failedHttp"; status: number; detail: string }
  | { kind: "cancelled" };

function isAbortable(phase: ChatPhase): boolean {
  return phase.kind === "connecting" || phase.kind === "streaming";
}

The composer should be aria-disabled only while isAbortable(phase) stays true. Stop should render only in those abortable phases, never as leftover chrome. Every other phase must restore a named, focusable textarea so a keyboard user can edit the failed turn. Does your hook still set native disabled={true} after a finished HTML response? That is the leak, because native disabled drops the control from the tab order.

Guard the document type before you parse tokens

Label this helper as a minimal reproduction, not a production SDK. Paste it into a Vite or single-file TypeScript shell and break it on purpose. The important line is the early return, not another token buffer.

const SSE_TYPE = "text/event-stream";

export async function readAssistantStream(
  input: RequestInfo,
  init: RequestInit,
  onPhase: (phase: ChatPhase) => void,
): Promise<void> {
  onPhase({ kind: "connecting" });

  const response = await fetch(input, init);

  if (!response.ok) {
    const detail = await response.text();
    onPhase({
      kind: "failedHttp",
      status: response.status,
      detail: detail.slice(0, 180),
    });
    return;
  }

  const mime = (response.headers.get("content-type") ?? "")
    .split(";")[0]
    .trim()
    .toLowerCase();

  if (mime !== SSE_TYPE) {
    onPhase({
      kind: "failedNonSse",
      detail: `Expected ${SSE_TYPE}, received ${mime || "an empty content type"}.`,
    });
    return;
  }

  if (!response.body) {
    onPhase({
      kind: "failedNonSse",
      detail: "The response had no readable body.",
    });
    return;
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  onPhase({ kind: "streaming", buffer });

  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      onPhase({ kind: "streaming", buffer });
    }
    onPhase({ kind: "complete", buffer });
  } catch (error) {
    if (error instanceof DOMException && error.name === "AbortError") {
      onPhase({ kind: "cancelled" });
      return;
    }
    throw error;
  } finally {
    reader.releaseLock();
  }
}

Notice the early return before getReader(). You never attach a reader to HTML, so the stream cannot hang in a polite generating state. You never leave aria-busy waiting for a data: line that cannot exist in a markup document. You also avoid piping markup into a Markdown renderer that would dump headings into the accessible tree.

Here is a labeled example test for the header branch. It does not replace assistive-technology checks, and you should still walk the focus path by hand.

import { assertEquals } from "https://deno.land/std/assert/mod.ts";
import { readAssistantStream, type ChatPhase } from "./readAssistantStream.ts";

Deno.test("html content type becomes failedNonSse", async () => {
  const originalFetch = globalThis.fetch;
  globalThis.fetch = async () =>
    new Response("<!doctype html><title>Down</title>", {
      status: 200,
      headers: { "content-type": "text/html; charset=utf-8" },
    });

  const phases: ChatPhase["kind"][] = [];
  try {
    await readAssistantStream("/mock", {}, (phase) => {
      phases.push(phase.kind);
    });
  } finally {
    globalThis.fetch = originalFetch;
  }

  assertEquals(phases, ["connecting", "failedNonSse"]);
});

Map phases onto the chat document

Semantic structure matters more than a second live region stacked on the log. Keep one conversation log, one status, and one composer, then let the phase machine drive them. The labeled React example below is unexecuted scaffolding, not a screenshot of a shipped product.

function ChatShell({ phase, onSubmit, onCancel }: Props) {
  const composerRef = useRef<HTMLTextAreaElement>(null);
  const abortable = isAbortable(phase);

  useEffect(() => {
    if (!abortable) composerRef.current?.focus();
  }, [phase.kind, abortable]);

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        onSubmit();
      }}
    >
      <div role="log" aria-busy={abortable} aria-label="Conversation">
        {/* settled turns only */}
      </div>

      <p role="status" aria-live="polite">
        {statusFor(phase)}
      </p>

      <label htmlFor="prompt">Message</label>
      <textarea
        id="prompt"
        ref={composerRef}
        aria-disabled={abortable || undefined}
        readOnly={abortable}
      />

      {abortable ? (
        <button type="button" onClick={onCancel}>
          Stop generating
        </button>
      ) : (
        <button type="submit">Send</button>
      )}
    </form>
  );
}

function statusFor(phase: ChatPhase): string {
  switch (phase.kind) {
    case "connecting":
      return "Connecting to the model.";
    case "streaming":
      return "Generating a response.";
    case "failedNonSse":
      return `The server returned a page instead of a stream. ${phase.detail}`;
    case "failedHttp":
      return `The request failed with status ${phase.status}.`;
    case "cancelled":
      return "Generation cancelled.";
    case "complete":
      return "Response complete.";
    default:
      return "";
  }
}

I use readOnly plus aria-disabled instead of native disabled so the composer remains in tab order while the failure is announced. The effect then returns focus to that named textarea after every non-abortable phase. Native disabled would remove the control from the focus order and hide its accessible name. Do you really want a failed turn to strand keyboard users on a Stop button that can no longer abort anything?

Pointer-independent actions stay on real buttons inside the form. Do not hang click-only recovery on the log, and do not trap Tab inside a decorative overlay. If recovery requires a pointer target with no name, the MIME guard never reached the people who needed it.

A local HTML fixture, then a remote header check

You should not wait for a production outage to test failedNonSse. Serve a fixture and aim the client at it, then watch focus and the status node. The commands below are a local reproduction, not a claim about any hosted quota.

mkdir -p public/fixtures
cat > public/fixtures/error.html <<'EOF'
<!doctype html>
<title>Unavailable</title>
<p>The model proxy is restarting.</p>
EOF

npx --yes serve public -p 4177

Point the client at http://localhost:4177/fixtures/error.html with Accept: text/event-stream. You should land on failedNonSse, hear the status, and find focus back in the composer. If Stop is still focused, the guard never reached the view, and the phase table is only sitting in a comment.

I also pointed the same shell at MonkeyCode while checking remote response headers from a real browser. Disclosure: This article was prepared as part of MonkeyCode's product outreach, not as an independent lab report. MonkeyCode is an open-source project with free model access and a free server option, which gave me a second HTTP target. I still commit the local HTML fixture, and that free server option is enough if you want a remote header check.

Keyboard and screen-reader regressions

Please treat the next matrix as a reproduction invitation, not as a claim that I certified a particular browser. Re-run the connecting to failedNonSse jump with your own browser, OS, and assistive-technology versions. Write those versions next to the exact transition that failed, because a passing unit test will not catch a stuck Stop control.

Transition	Keyboard expectation	Screen-reader expectation
`idle` → `connecting`	focus moves to Stop	Connecting to the model.
`connecting` → `failedNonSse`	focus returns to composer	error status, `aria-busy` false
`connecting` → `streaming`	focus stays on Stop	Generating a response.
`streaming` → `complete`	focus returns to composer	Response complete.
abortable → `cancelled`	focus returns to composer	Generation cancelled.

I care about the exact transition that failed in this retrospective: connecting into failedNonSse. If the Stop control remains focused after the HTML body arrives, the view layer ignored the phase. If Generating is still spoken as if tokens might continue, the status mapping is stale. Can a keyboard user recover that turn without reloading the tab?

Limitations, and who should skip this

This guard does not certify WCAG conformance, and it does not replace a real device pass. It does not parse SSE retry fields, binary frames, or chunked tool-call JSON. It also cannot save you if a proxy lies with Content-Type: text/event-stream while the body is still HTML. That lying-header case needs a cautious <!doctype sniff, which remains a heuristic and can false-positive on unusual payloads.

Do not use this approach if your gateway already converts every non-SSE body into a JSON error envelope. Do not use it as cover for skipping keyboard testing, because a green Deno assertion will not move focus. Do not point a production composer at a shared free server and assume isolation or retention rules you have not actually read. Free model access is useful for reproducing header failures, and it is not a privacy boundary.

I would also skip this pattern when the chat is not streaming at all. A unary JSON POST should fail on schema validation, not on MIME theater, and a content-type guard would only add noise. Teams with a locked internal SSE contract and synthetic HTML fixtures may not need a second remote target either.

What I keep in the pull request

The artifact is the phase union, the content-type early return, and focus restoration on every non-abortable phase. Draw the state table first, then break the stream on purpose with HTML. Then ask whether a keyboard user can recover without a mouse and without reloading the tab.

If the composer still cannot speak its own name after a finished error page, you do not have a stream bug. You have a stuck generating state that stole the conversation. Fix the document type before you spend another afternoon polishing the spinner.

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

Agent Tool Prompts Need a Blocking Dialog, Not a Chip You Never Tab To

babycat — Wed, 09 Sep 2026 15:21:19 +0000

I reproduced a three-tool agent in a local page, then watched the confirmation chip appear beside the stream. The composer still held focus, so Enter sent another user message instead of allowing anything. Have you ever approved a destructive tool without meaning to, just because the prompt never entered the tab order? That is the failure this retrospective walks from symptom to a blocking dialog.

The chip looked confident. It sat under the last token, colored like a success toast, and it started an eight-second auto-allow. I never tabbed into it, NVDA never named the verbs, and run_command still fired. This write-up keeps the broken page, the state table, and the fix in one place so you can rerun the same transition.

The symptom I actually hit

I was keyboard-only in the composer, which is where almost every chat agent leaves you. A streamed plan appeared: read_file, then run_command, then write_file. A compact chip said “Allow 2 tools,” but it was a div with a click handler and a CSS animation. I pressed Enter because I was still editing the follow-up sentence. The agent treated that key as consent and executed the shell step.

What failed, in order:

Focus never left #composer.
The chip was not in the tab order and had no accessible name.
An auto-allow timer treated silence as a yes.
A new user message did not retire the open proposal.
The transcript live region re-read partial JSON instead of the decision.

Does that sound like a visual polish bug? It is a consent bug wearing a badge.

Put the state table on the wall first

I stopped restyling the chip and wrote the legal states down. If a transition cannot be named, the UI will invent an implicit yes.

State	Composer	Prompt UI	Announcement	Keyboard action
`idle`	enabled	none	none	type and send
`planning`	disabled, status text on the field	none	“Planning tools.” once	Cancel planning
`awaiting_confirm`	inert	modal dialog, focus on Deny	“Two tools proposed. Deny or allow.”	Deny, Allow, review list
`executing`	disabled	closed	one verb per step	Cancel remaining
`failed`	enabled	closed	which step failed	compose a new turn
`cancelled`	enabled	closed	“Tool run cancelled.”	compose a new turn

Notice what is missing on purpose. There is no implicit_allow. There is no timeout_yes. There is no enter_in_composer_means_ok. If you need those states, you are not confirming tools. You are hoping nobody notices.

How I debugged it without guessing

I did not start with more ARIA. I logged focus, then I logged the machine, then I recorded what a screen reader would hear. Would you ship a payment sheet that never received focus? Then do not ship tool consent that way.

Reusable checks:

Log document.activeElement.id on every state change.
Tab from the composer with the mouse unplugged and count stops.
Speak the dialog title and the first button without looking at the screen.
Send a second message while a proposal is open and assert the proposal dies.
Kill the auto-allow timer and prove the tools do not run.

// Label: local debug helper for a single-page reproduction.
const focusLog = [];
function traceFocus(reason) {
  const id = document.activeElement && document.activeElement.id;
  focusLog.push({ reason, id, at: Date.now() });
  console.table(focusLog.slice(-8));
}

The first trace was embarrassing. Every planning token called traceFocus("chunk"), and the id stayed composer. The chip never appeared in the log, which meant the keyboard path could not reach Deny or Allow. That is the whole incident in one column.

Root cause: a toast tried to do a dialog’s job

The chip failed for structural reasons, not because the copy was short. A toast is a transient status. A tool prompt is a permission gate. Mixing them trains the interface to steal consent from whoever is still typing.

The broken control did four illegal things at once:

It rendered after the stream, so it competed with incoming tokens.
It used div + onclick, so it skipped the tab order.
It armed setTimeout(..., 8000) and called that “safe default.”
It left the composer enabled, so Enter could not mean Deny.

I also had aria-live="polite" on the whole transcript. Partial tool JSON like {"cmd":"rm got announced, while “Allow?” stayed silent. The live region was busy reciting garbage, and the actual decision never won the queue. Have you checked who wins when a token and a permission question arrive together?

The broken reproduction

This is the smallest page that recreates the failure. Paste it, tab into the textarea, and press Enter after the chip appears. The shell step runs even if you never touched Allow.

<!-- Label: intentionally broken demo. Do not copy this pattern. -->
<textarea id="composer" aria-label="Message">Inspect package.json</textarea>
<button type="button" id="send">Send</button>
<div id="stream" aria-live="polite"></div>
<div id="chip" hidden>
  Allow 2 tools
  <span onclick="allowTools()">Allow</span>
</div>
<script>
let allowTimer;
const proposal = [
  { id: "t1", name: "read_file", args: { path: "package.json" } },
  { id: "t2", name: "run_command", args: { cmd: "rm -rf build" } }
];

send.onclick = () => {
  composer.disabled = false; // still typeable: the bug
  stream.textContent = JSON.stringify(proposal);
  chip.hidden = false;
  allowTimer = setTimeout(allowTools, 8000);
};

function allowTools() {
  clearTimeout(allowTimer);
  stream.textContent += "\nrunning " + proposal[1].name;
}
</script>

Expected broken states:

Visual: chip visible, composer focused, timer ticking.
Keyboard: Tab never lands on Allow; Enter submits the composer.
Screen reader: JSON string spoken; “Allow 2 tools” unnamed.
Recovery: none, because the proposal is not a state you can deny.

The fix: `showModal()`, Deny first, proposal retirement

I replaced the chip with a native modal dialog and a typed machine. Native HTMLDialogElement.showModal() gives a focus trap, Escape, and an inert backdrop without a custom overlay folklore. Deny is the first control because accidental Enter must mean no.

// Label: proposed state machine for the confirmation path.
/** @typedef {"idle"|"planning"|"awaiting_confirm"|"executing"|"failed"|"cancelled"} AgentUi */

const ui = {
  state: /** @type {AgentUi} */ ("idle"),
  proposal: /** @type {null | {id: string, name: string, summary: string}[]} */ (null)
};

function setState(next) {
  ui.state = next;
  composer.disabled = next !== "idle" && next !== "failed" && next !== "cancelled";
  if (next === "awaiting_confirm") {
    dialog.showModal();
    denyBtn.focus();
    status.textContent = `${ui.proposal.length} tools proposed. Deny or allow.`;
  } else if (dialog.open) {
    dialog.close();
  }
  traceFocus(next);
}

function retireProposal(reason) {
  ui.proposal = null;
  clearTimeout(allowTimer); // there is no allowTimer anymore
  status.textContent = reason;
  setState("cancelled");
}

form.addEventListener("submit", (event) => {
  event.preventDefault();
  if (ui.state === "awaiting_confirm") {
    retireProposal("Proposal retired because you sent a new message.");
    return;
  }
  // start planning…
});

denyBtn.addEventListener("click", () => retireProposal("Tools denied."));
allowBtn.addEventListener("click", () => setState("executing"));
dialog.addEventListener("cancel", (event) => {
  event.preventDefault();
  retireProposal("Tools denied.");
});

Dialog markup that actually participates in the accessibility tree:

<div id="status" role="status"></div>
<dialog id="dialog" aria-labelledby="prompt-title">
  <h2 id="prompt-title">The agent wants to run tools</h2>
  <ol id="tool-list"></ol>
  <button type="button" id="denyBtn">Deny</button>
  <button type="button" id="allowBtn">Allow listed tools</button>
</dialog>

Fill the list with real verbs, not a count chip. read_file on package.json is a decision. Allow 2 tools is a shrug. Pointer users can still click Allow. Keyboard users get Deny first. Screen reader users get one status sentence, not a JSON firehose.

When planning starts, disable the composer and put the busy text on the field itself. That keeps the name and the state in one place.

<textarea id="composer" aria-label="Message" aria-disabled="true"></textarea>
<p id="composer-state">Planning tools. Cancel is available.</p>

Where a free remote model actually helps this bug

Local mocks hide the worst timing. Real streams stall, split a tool name across chunks, and then dump three proposals at once. I needed that jitter to prove the dialog still opens once, with focus on Deny, even when the last argument arrives late.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode’s free model access and free server option are enough to stream a multi-step tool plan into this page without standing up a paid inference account. Point the reproduction at that remote stream, cancel it, and send a second user turn while the dialog is open. If the proposal does not retire, the machine is still lying.

A sibling gate belongs in front of the first remote call. Tool consent is not the same as “this prompt leaves the browser,” but both must block. A dismissible banner under the composer will fail the same keyboard path you just watched.

// Label: first-run remote-inference consent, same blocking pattern.
if (ui.state === "idle" && !consent.remoteInference) {
  privacyDialog.showModal();
  privacyDeny.focus();
  return;
}

Accessibility notes the dialog does not magically solve

Native modal behavior is necessary and not sufficient. You still owe a named list, a single status announcement, and pointer-independent actions. ARIA on a chip will not create a tab stop that was never there.

Checklist I keep beside the demo:

The dialog title names the decision, not the product.
Deny is first in DOM order and receives initial focus.
Escape and Deny take the same cancelled path.
The tool list is an ol, and each item includes the verb plus the target.
role="status" announces the state change once, not every token.
The composer is inert while the dialog is open; it does not submit.
A new submit retires the proposal instead of stacking a second chip.
No timer calls allowTools.

Diagram of the only legal confirmation loop:

idle -> planning -> awaiting_confirm
                      |        |
                   Deny/Esc   Allow
                      |        |
                 cancelled   executing -> idle or failed
                      ^
                      |
              new user message retires proposal

Environment-specific QA matrix

Please reproduce with versions written down. The transition that failed for me was planning to awaiting_confirm while focus stayed in the composer, then Enter on a still-enabled textarea.

Environment	What to drive	Pass
Firefox, Windows, NVDA	planning → dialog opens, NVDA speaks the title and Deny	Deny is first utterance after “Planning tools.”
Chrome, Windows, NVDA	Escape from dialog	state is `cancelled`, composer focused
Safari, macOS, VoiceOver	VO+Space on Deny	tools never run
Chrome, macOS, keyboard only	Tab cycle inside dialog	no composer, no stream links
Any browser, slow remote stream	arguments arrive after the dialog opened	list updates without moving focus
Any browser	Send a second message during the prompt	proposal retired, no execution

If you file a miss, send the browser, OS, assistive technology, and that exact transition. A screenshot of the chip is not evidence, because the chip was the bug.

Limitations, and who should not use this

This pattern is for interactive product UX in the browser, where a human is present and tools can mutate files or run commands. It does not authorize tools on the server. A pretty dialog with a lying backend is still an auto-run.

Do not use this approach if:

the agent must run unattended in CI with a pre-signed policy;
you only render read-only explanations and never call tools;
you are replacing OS permission prompts in a native shell;
you planned to keep auto-allow and “just announce it louder.”

I also am not claiming conformance. This is a reproduction and a focus-safe state machine, not a WCAG certificate. If your tools include purchase, delete, or deploy, add server-side authorization and a review surface that survives a refresh.

The recovery path stays boring on purpose. After Deny or failure, focus returns to the composer, the proposal is gone, and nothing retries itself. A second Stop button or a resurrected chip would hide the same consent hole we just closed.

So here is the debugging habit I am keeping. When an agent assumes yes, freeze the UI on a real dialog, log activeElement, and retire the proposal if the human keeps talking. If you want a remote stream that is slow enough to expose the race, MonkeyCode’s free model access and free server option can feed this dialog while you watch focus, not while you admire the chip.

The Stop Button Lied: Debugging a Cancelled Stream That Never Released the Composer

babycat — Tue, 08 Sep 2026 15:53:37 +0000

I had VoiceOver running in Safari, a chat transcript filling in, and both hands on the keyboard. The assistant was still streaming tokens when I pressed Escape, which should have been the cancel shortcut for that turn. The bubble froze mid-sentence, the spinner vanished, and I honestly thought the request was dead. Then I pressed Tab and found the composer still disabled, the live region still saying generating, and the network panel still transferring bytes.

Was the interface cancelled, or had I only painted a cancelled costume over a live request? That silent disagreement is the failure I want to debug with you, because mouse users rarely notice it. They click Stop, watch the spinner die, and assume the turn is over. Keyboard and screen-reader users get a different product: focus is trapped, status is stale, and the next prompt never reaches the textarea.

The interaction that actually failed

I reproduced this in a single-file chat demo rather than in a private production app I cannot show. The stream came from a remote chunked HTTP endpoint, which matters because local mocks hide abort races. I watched three surfaces at once: the visible controls, the accessibility tree, and the network panel. Those three surfaces disagreed, and that disagreement is the bug, not a missing ARIA label.

Here is the table I wrote while the UI still looked stopped:

Surface	After Escape	What it should be
Visible spinner	hidden	hidden
Composer textarea	`disabled`	enabled and focused
Stop button	still in tab order	removed or inert, not focused
`aria-live` status	“Generating response”	“Generation cancelled”, once
Fetch / SSE	still transferring	aborted, then idle
Assistant message	`status: streaming`	`status: cancelled`, partial text kept

If your screenshot looks cancelled and your accessibility tree still says generating, you do not have a visual polish issue. You have a state-machine bug with an accessibility amplifier sitting on top of it. Have you ever tabbed into a Stop control that no longer stops anything? That is this failure wearing a button.

How I instrumented the failure

I did not start by restyling the Stop button, because the spinner was already gone. I asked a simpler question instead: which layer still believed the turn was live? That question keeps you from “fixing” paint while the composer stays disabled for the next prompt.

I used this checklist, in this order:

Log every status transition with timestamps, including a real cancelling state.
Log document.activeElement after Escape, after abort, and after the last chunk.
Watch the Network panel for (canceled) versus a stream that keeps transferring.
Inspect the live region with the accessibility inspector, not with your eyes.
Press Tab and Shift+Tab through the transcript, Stop, Retry, and composer.

In the page I traced focus and status together, because either log alone lies:

function traceUi(tag, status) {
  const active = document.activeElement;
  console.log(tag, {
    status,
    activeId: active && active.id,
    activeRole: active && active.getAttribute("role"),
    liveText: document.getElementById("gen-status")?.textContent,
  });
}

The log told the real story faster than another screenshot would have. Escape flipped a local stopping flag, but fetch never received an AbortSignal. A late chunk arrived, React set status back to streaming, and the composer disabled itself again. Have you watched a cancelled request resurrect a spinner after you already moved on? That resurrection is the same bug in a different shirt.

Root cause, stacked in three layers

Three independent mistakes stacked, and any one of them can trap a keyboard user. I am listing them as a debugging order, not as a component library lecture. Fix the abort first, then the boolean, then the announcement.

Cancel was a CSS hide, not an abort. Stop set showSpinner = false and left read() running on the response body.
The composer keyed off a boolean. disabled={isStreaming || isBusy} treated cancelling as busy forever when abort never resolved.
The live region was sticky. It announced “Generating” on start and never announced a terminal state.

A fourth issue showed up only against a real remote stream, which mocked timers never reproduce. Client abort does not always stop the server from generating tokens. If you ignore late chunks instead of closing the turn, a cancelled bubble can still mutate under the reader. Should a cancelled message keep growing after the user has moved back to the composer? No, and your turn id should refuse those writes.

The state table I wish I had drawn first

Treat the turn as a typed machine, not a pile of booleans fighting each other. Booleans are how isStreaming && !isError && !isCancelling becomes an untestable knot. Draw legal edges before you write the button handler, then make illegal edges loud in development.

type TurnStatus =
  | "idle"
  | "streaming"
  | "cancelling"
  | "cancelled"
  | "complete"
  | "error";

type Turn = {
  id: string;
  status: TurnStatus;
  text: string;
  error?: string;
};

const LEGAL: Record<TurnStatus, TurnStatus[]> = {
  idle: ["streaming"],
  streaming: ["cancelling", "complete", "error"],
  cancelling: ["cancelled", "error"],
  cancelled: ["idle"],
  complete: ["idle"],
  error: ["idle"],
};

function transition(turn: Turn, next: TurnStatus): Turn {
  if (!LEGAL[turn.status].includes(next)) {
    throw new Error(`illegal ${turn.status} -> ${next}`);
  }
  return { ...turn, status: next };
}

Why throw on a UI path during development? Because an illegal transition is the bug you are hunting, and silent coercion will hide it again. In production, log the illegal event and ignore it, especially late SSE chunks after cancelled. The machine is the test surface. The Stop button is only a pointer into that machine.

Expected UI states after the machine exists

Write the states as a contract you can click through without a mouse. If a state cannot be reached from the keyboard, it does not exist for this interface. I keep this list next to the component because screenshots hide focus.

idle: composer enabled and focused; no Stop; live region quiet.
streaming: composer disabled; Stop visible and reachable; status announced once.
cancelling: Stop inert or gone; composer still disabled; status says cancelling once.
cancelled: partial text kept; composer enabled and focused; Stop gone.
complete / error: terminal announcement once; composer restored; retry is a new turn.

Pointer-independent actions matter here as much as roles do. Escape must cancel while streaming, and Enter must submit only when the composer is actually enabled. If Stop is a <div onClick>, you have already failed the keyboard path before abort enters the chat.

The cancel path that restores the composer

Here is a proposed single-file control flow, not a claim about a shipped product. Wire your own endpoint in startStream, then try Escape before the first byte and again mid-chunk. The point is the turn id, the signal, and the focus restore, not the styling.

import { useEffect, useId, useRef, useState } from "react";

type TurnStatus =
  | "idle"
  | "streaming"
  | "cancelling"
  | "cancelled"
  | "complete"
  | "error";

export function CancellableComposer() {
  const composerId = useId();
  const composerRef = useRef<HTMLTextAreaElement>(null);
  const abortRef = useRef<AbortController | null>(null);
  const turnIdRef = useRef(0);
  const [status, setStatus] = useState<TurnStatus>("idle");
  const [prompt, setPrompt] = useState("");
  const [text, setText] = useState("");
  const [announcement, setAnnouncement] = useState("Idle");

  function focusComposer() {
    composerRef.current?.focus();
  }

  async function startStream(value: string) {
    const turnId = ++turnIdRef.current;
    const abort = new AbortController();
    abortRef.current = abort;
    setText("");
    setStatus("streaming");
    setAnnouncement("Generating response");

    try {
      const res = await fetch("/stream", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ prompt: value }),
        signal: abort.signal,
      });
      if (!res.body) throw new Error("No response body");
      const reader = res.body.getReader();
      const decoder = new TextDecoder();

      while (true) {
        const { value: chunk, done } = await reader.read();
        if (turnId !== turnIdRef.current) return;
        if (done) break;
        setText((prev) => prev + decoder.decode(chunk, { stream: true }));
      }

      if (turnId !== turnIdRef.current) return;
      setStatus("complete");
      setAnnouncement("Response complete");
    } catch (err) {
      if (turnId !== turnIdRef.current) return;
      if (abort.signal.aborted) {
        setStatus("cancelled");
        setAnnouncement("Generation cancelled");
      } else {
        setStatus("error");
        setAnnouncement("Generation failed");
      }
    } finally {
      if (abortRef.current === abort) abortRef.current = null;
      if (turnId === turnIdRef.current) {
        queueMicrotask(() => focusComposer());
      }
    }
  }

  function cancel() {
    if (status !== "streaming") return;
    setStatus("cancelling");
    setAnnouncement("Cancelling");
    abortRef.current?.abort();
  }

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

  const busy = status === "streaming" || status === "cancelling";

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        if (!prompt.trim() || busy) return;
        startStream(prompt.trim());
      }}
    >
      <div role="status" aria-live="polite">
        {announcement}
      </div>
      <label htmlFor={composerId}>Message</label>
      <textarea
        id={composerId}
        ref={composerRef}
        value={prompt}
        disabled={busy}
        onChange={(event) => setPrompt(event.target.value)}
      />
      <button type="submit" disabled={busy}>
        Send
      </button>
      {status === "streaming" && (
        <button type="button" onClick={cancel}>
          Stop generating
        </button>
      )}
      <article aria-label="Assistant message">{text}</article>
    </form>
  );
}

Notice what this machine does that the boolean version never did. cancelling is a real status, abort is wired into fetch, late chunks die against a turn id, and focus returns in finally. Stop leaves the tab order when the turn is no longer streaming. Does Stop remain focused after it disappears from the tree? Not here, because we move focus before unmounting that button.

Live region rules that keep cancel hearable

A live region can fail in two opposite ways, and both showed up while I was tracing this demo. It can stay silent after Escape, which is the opening bug. It can also announce every token, which makes the cancel sentence impossible to hear. Neither failure is fixed by adding more ARIA to the spinner.

Use these rules as a regression list:

Announce start once: “Generating response”.
Do not pipe streaming tokens into aria-live.
Announce one terminal event: complete, cancelled, or failed.
Keep role="status" and aria-live="polite" unless recovery is time-critical.
Never steal focus into the live region; focus belongs on Stop, then the composer.

If you need a mental model, treat the live region like a station announcement rather than a teleprompter. People need the train’s state, not every syllable of the timetable as it prints. Streaming tokens belong in the document. Status belongs in one short sentence.

Why a mocked timer will not catch this

Local mocks resolve on a timer and almost never race your abort handler. A remote stream will race it, especially when the first byte is slow and the last byte arrives after abort(). That is why this debugging path needs a chunked HTTP response instead of setTimeout pretending to be a model.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode’s free model access and free server option are useful here only as a remote stream you can abort without inventing a fake read(). I am not quoting model names, quotas, hardware, or duration, because those are easy to get wrong and I did not measure them for this writeup. If you already have an endpoint, keep it; the state machine does not care who owns the GPU.

QA matrix for the exact failed transition

Do not trust a screenshot of a frozen bubble. Run the transition that failed: streaming, then Escape, then a focused composer with one quiet terminal announcement. Write down browser, OS, and assistive-technology versions next to the result, because “it worked on my laptop” is not a matrix.

Environment	Assistive tech	Transition	Pass if
Chromium current, macOS	VoiceOver	Escape during stream	One “Generation cancelled”; textarea focused
Safari current, macOS	VoiceOver	Stop, then Tab	Stop gone; composer back in tab order
Firefox current, Windows	NVDA	Abort mid-chunk	No leftover “generating”; partial text kept
Chromium, Windows	Keyboard only	Escape, type, Enter	New prompt submits; old turn stays cancelled
Any, reduced motion	none	Cancel	Focus does not jump into the transcript

Also test the ugly cases, because they are the ones that resurrect streaming:

Abort before the first byte arrives.
Abort after the last byte but before you mark complete.
A chunk that arrives after abort().
Double Escape, and Send while cancelling.

If any of those flips the turn back to streaming, your turn id guard is missing and the composer will disable itself again. That regression is the original bug coming home.

Limitations, and who should not copy this

This pattern is for a single in-flight browser turn with a cancel control the user can reach without a pointer. It is not a server orchestration framework, and it will not stop backend work unless your server honors abort or an explicit cancel POST. I did not benchmark throughput, and I am not claiming a conformance badge for any browser pairing above.

Skip this approach if you are building:

Non-streaming forms that already submit, disable, and re-enable in one round trip.
Native mobile chat, where focus restoration follows a different toolkit.
Multi-agent canvases with several concurrent streams (you need a per-turn abort map).
Voice-only UIs that need an interrupt model beyond Escape and a Stop button.

Late server tokens can still do work after the client hangs up, which is a backend problem this composer restore cannot solve. Pair the UI abort with a cancel request if leftover work matters in your system. Users still need the textarea back either way, because they came here to type the next prompt, not to admire a frozen Stop control.

What I would debug next time, in order

When a cancel looks fake, I now walk this sequence instead of restyling the spinner or adding one more live region. The order is the reusable technique. The React snippet is only one encoding of that order.

Is AbortSignal actually passed into fetch, or into whatever wraps your EventSource?
Does status include cancelling, or only a sticky busy: true?
Does a turn id drop late chunks after the user has cancelled?
Does focus return to the composer in a microtask after the terminal state?
Does the live region announce one terminal sentence, and only one?

Ask those five questions before you add another ARIA attribute to the bubble. ARIA cannot abort a socket, and it cannot enable a textarea that React still thinks is streaming. The Stop button was never the liar. The state machine was, and Escape was the witness.

Reproduce the Escape transition in your own browser, with screen-reader versions written beside the pass or fail. The bug is not the missing spinner. The bug is a composer that never becomes a composer again.

Stream Cancel Needs a Dead Reader, Not a Hidden Spinner

babycat — Tue, 08 Sep 2026 14:53:08 +0000

Last Tuesday I cancelled a streaming agent reply with the keyboard, and the UI lied to me. The Cancel button vanished, the composer unlocked, and I started typing the next prompt like a person who trusts buttons. Two seconds later a leftover sentence dropped under the previous turn, VoiceOver stayed silent, and my caret was gone. Have you ever watched a supposedly stopped chat keep talking after you already moved on?

I was not debugging a production outage, and I will not pretend this was a customer incident with dashboards. This was a local demo against a remote streaming endpoint, the setup frontend teams use before an API freeze. The failure still taught a reusable sequence that I now run on every cancel control I ship. I start with the symptom, then the timeline, then the reader, then focus, then the announcement.

The failure looked like a styling bug

The visible spinner disappeared the instant I pressed Escape, so I assumed the stream was dead. The transcript still received one more markdown fragment, and the new prompt I had typed jumped into the previous assistant bubble. Keyboard focus landed on the document body, which meant the next Tab started at the banner instead of the composer. Why did a cancel handler that called abort() still feel haunted?

Here is the exact transition that failed, written down before I touched CSS again:

From: streaming, Cancel focused, aria-busy="true" on the transcript
User action: Escape, which should abort the in-flight assistant response
Expected: cancelled, composer focused, one announcement, no further tokens
Actual: idle paint, then a late token commit, then focus on <body>

I keep that four-line card next to the component now, because cancel bugs hide in the seams between paint and I/O. If you only screenshot the spinner, you will “fix” opacity and ship the race. Does your cancel test even assert that no DOM mutation happens after abort?

Draw the state table before the spinner

Cancel is not a boolean, and treating it like isLoading is how the lie gets into the DOM. I now keep an explicit session status and a monotonic generationId so late chunks can be ignored without debating the network. The table below is the whole product contract for this control.

Status	Composer	Cancel control	Live region	Tokens allowed
`idle`	enabled, focused after recover	hidden	silent	no
`streaming`	disabled	visible and in tab order	“Reply streaming” once	yes, matching id
`cancelling`	disabled	visible, `aria-disabled`	“Cancelling reply”	no
`cancelled`	enabled, restored focus	hidden	“Reply cancelled”	no
`error`	enabled, restored focus	hidden	error text once	no

Notice cancelling is a real state, not a CSS class on a dying spinner. If you skip it, the UI jumps to idle while the reader is still pulling bytes. Should a screen reader hear “cancelled” before the reader is actually dead? No, and that timing is the entire bug.

A runnable session object

The reproduction is a typed session, not a pile of setState flags fighting each other. I want one object that the UI and the reader both consult, because split sources of truth recreate the late chunk. The sketch below is a labeled example for the demo, not a published library and not a benchmark.

type ChatStatus =
  | "idle"
  | "streaming"
  | "cancelling"
  | "cancelled"
  | "error";

type ChatSession = {
  generationId: number;
  status: ChatStatus;
  abort: AbortController;
};

function createSession(id: number): ChatSession {
  return {
    generationId: id,
    status: "streaming",
    abort: new AbortController(),
  };
}

The composer submits by creating a new session and incrementing generationId. Cancel never toggles a boolean; it asks the current session to enter cancelling and then kills I/O on purpose. If a chunk arrives with a stale id, the reducer drops it on the floor. That drop is the product, not an edge case. Would you rather filter tokens in the view layer and hope React batches kindly?

What the debugger actually showed

I paused in the reader loop after abort() and watched one more read() resolve with { done: false, value }. Fetch had rejected, sure, but the stream reader still had a queued chunk from the previous tick. My reducer had already set status: "idle" in the click handler, so the chunk committed as if the user never cancelled. Is that a network bug or a UI bug? It is a missing join between the abort signal and the async iterator.

The fetch aborted, the reader did not

Calling controller.abort() is necessary and not sufficient when you already called getReader(). You still need to stop pulling, ignore the current generationId, and prefer reader.cancel() so backpressure actually stops. A local mock often completes in one tick, which hides the race completely. A remote stream makes the gap wide enough to see with only a keyboard.

I needed that slower, less polite remote behavior, so I pointed the demo at MonkeyCode's free model access on the free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The late chunk still arrived after abort, which is the race a remote endpoint will give you without extra staging hardware. If you need the same gap in a laptop demo, that free model access and free server option are enough to reproduce it.

async function readStream(
  session: ChatSession,
  stream: ReadableStream<Uint8Array>,
  onToken: (id: number, text: string) => void,
) {
  const reader = stream.getReader();
  const decoder = new TextDecoder();

  try {
    while (true) {
      if (session.abort.signal.aborted) {
        session.status = "cancelled";
        await reader.cancel("user-cancel");
        break;
      }

      const { done, value } = await reader.read();
      if (done) break;
      if (session.abort.signal.aborted) continue;
      if (session.status !== "streaming") continue;

      onToken(
        session.generationId,
        decoder.decode(value, { stream: true }),
      );
    }
  } catch (error) {
    if (session.abort.signal.aborted) {
      session.status = "cancelled";
      return;
    }
    session.status = "error";
    throw error;
  }
}

function cancelSession(session: ChatSession) {
  if (session.status !== "streaming") return;
  session.status = "cancelling";
  session.abort.abort("user-cancel");
}

Check the signal before read() and after read(), because the await is the window where the user hits Escape. Swallowing the abort exception without setting cancelled will strand you in cancelling forever. Have you logged session.status on every token, or only on the click?

The composer remount ate focus

My cancel path replaced the whole transcript list with a new array identity, and the composer lived inside that tree. React unmounted the textarea, so focus fell to the body, which is how a keyboard user gets dumped into the header. The fix was a stable composer mounted outside the streaming list, plus explicit textarea.focus() after status landed on cancelled or error. Pointer users never noticed, which is why this class of bug survives an otherwise careful review.

Do not steal focus to Cancel on every token either, because that traps a screen-reader cursor in a button that is about to vanish. I only move focus on user-initiated cancel and on recovery from error. That is a small rule, and it prevents a very loud interface. Would you like your screen reader parked on a control that disappears mid-sentence?

The live region never heard cancelled

I had aria-busy="true" on the log, and I flipped it to false when the spinner hid. Busy state is not an announcement, and a hidden spinner is not a status. The cancelled outcome needs a polite live region with actual text, spoken once, without repeating on every stale chunk you dropped. I also keep the cancelled turn in the transcript as a retired bubble, so history still makes sense when you arrow through it.

<div class="chat">
  <div id="log" role="log" aria-busy="true">
    <article>
      <h2>You</h2>
      <p>Summarize this stack trace without editing it.</p>
    </article>
    <article aria-label="Assistant, cancelled">
      <h2>Assistant</h2>
      <p data-status>Reply cancelled.</p>
    </article>
  </div>
  <p id="live" class="visually-hidden" aria-live="polite">
    Reply cancelled.
  </p>
  <form>
    <label for="prompt">Message</label>
    <textarea id="prompt" name="prompt"></textarea>
    <button type="submit">Send</button>
    <button type="button" id="cancel">Cancel reply</button>
  </form>
</div>

Escape must work from the composer without a mouse, and Cancel must be reachable by Tab while streaming. If Cancel is display: none until hover, you do not have a cancel control. You have a decoration that only pointer users can find.

Wire cancel to both input devices

The handler is the same function for the button and for the composer keydown. I prevent the default Escape behavior only while status === "streaming", so I do not trap people inside the widget after idle. Pointer, keyboard, and assistive-technology activation all call cancelSession, then wait for the reader to finish dying before unlocking the textarea.

function onComposerKeydown(
  event: KeyboardEvent,
  session: ChatSession | null,
) {
  if (event.key !== "Escape") return;
  if (!session || session.status !== "streaming") return;
  event.preventDefault();
  cancelSession(session);
}

function onCancelClick(session: ChatSession | null) {
  if (!session) return;
  cancelSession(session);
}

function announce(live: HTMLElement, text: string) {
  live.textContent = "";
  requestAnimationFrame(() => {
    live.textContent = text;
  });
}

function applyStatus(session: ChatSession, live: HTMLElement, prompt: HTMLTextAreaElement) {
  if (session.status === "cancelled") {
    announce(live, "Reply cancelled");
    prompt.focus();
  }
  if (session.status === "error") {
    announce(live, "Reply failed. You can edit and send again.");
    prompt.focus();
  }
}

Clearing the live region before setting text avoids some engines that skip duplicate polite strings. I still do not claim this pattern is a conformance badge, because announcement timing differs across browser and screen-reader pairs. Test the transition, not the ARIA attribute list. If the engine speaks “cancelling” and never “cancelled,” your reader is still alive.

The QA card I run before I trust cancel

I reproduce with versions written down at test time, because “VoiceOver on my laptop” is not a report. The failing transition is always the same sentence: streaming, Escape, then one more chunk. Record browser, OS, and assistive-technology versions on the card, then rerun after every reader change.

Chrome stable, macOS, VoiceOver: Escape from the textarea, expect “Reply cancelled”, focus in the textarea, no extra bubble text.
Firefox stable, Windows, NVDA: Tab to Cancel, press Space, expect one announcement and an unlocked composer.
Safari stable, iOS, VoiceOver rotor to form controls: activate Cancel, expect the retired turn, not an empty live region.
Keyboard only, no pointing device: confirm Tab order is log, prompt, Send, then Cancel while streaming.
Point the client at a slow remote stream and cancel mid-sentence; assert a stale generationId drops the next decode.

If step five is green on a mock and red on a remote stream, you do not have flaky CI. You have a reader that still lives. Fix that join before you add retry, because retry on a half-cancelled turn creates a second ghost in the log. Can your test harness tell the difference between a hidden spinner and a dead reader?

Limitations, and who should not copy this

This pattern assumes one in-flight assistant turn and a browser AbortController. It will not save you if the server keeps generating after the client disconnects and later writes into the same thread. It also will not make an inaccessible markdown renderer fine, and it will not replace a backend stop API if aborted connections are ignored.

Do not copy this if you need multi-turn tool approval, because those dialogs need a focus handoff I am not covering here. Do not copy this if your “cancel” is actually undo, or if you stream from a WebSocket you cannot tear down cleanly. Local toy demos that resolve in a single setTimeout will also teach you the wrong lesson, which is how I got here in the first place.

I am not attaching screenshots of a happy path, and I am not declaring the widget accessible in every environment. The artifact is the state table, the dead reader, and the QA card for one transition. If your cancel control cannot survive that card, the spinner was never the problem.

Streaming Markdown Needs a Settled Document, Not a Live Heading Tree

babycat — Sun, 06 Sep 2026 20:21:01 +0000

I was halfway through a streamed answer when NVDA suddenly said heading level two, Implementation. My place in the sentence vanished, and the heading rotor listed three Implementation entries that had not existed a second earlier. Has your chat UI ever stolen the screen-reader cursor while the model was still talking? Mine did, and the send button was not even the villain this time.

I had been checking whether a long answer stayed keyboard-operable through loading, cancel, and recovery. The composer still had a visible Stop control, which looked fine in the screenshot. The failure lived in the accessibility tree, where each ## in the stream became a real heading the moment a newline arrived.

The interaction that actually broke

The visible UI looked almost healthy. Tokens were painting, Stop stayed in the tab order, and a polite live region was “doing accessibility.” Then the model emitted a Markdown heading, the renderer promoted it immediately, and NVDA jumped as if I had clicked a table of contents I never asked for.

Here is the transition I keep reproducing, written down before I touch CSS:

Focus sits on Stop or on the growing transcript, depending on how you tab.
The stream prints ## Implementation plus a newline.
The Markdown renderer commits an <h2> inside aria-live="polite".
The screen reader announces the heading and abandons the sentence it was reading.
A later token rewrites the same title, so the rotor now contains duplicate, disappearing headings.

Does a toast help here? It does not. The user did not miss a status. They lost a reading position inside a document that was still being invented.

Expected UI states

I put the state table on the whiteboard before rewriting the component, because happy-path streaming demos hide this class of bug.

State	Composer	Transcript	Announcements	Focus
`idle`	Send enabled	Static article, real headings allowed	Silent	Composer
`streamingPlain`	Stop enabled, Send disabled	Plain text only, no `h1`–`h6`	Throttled “Still answering”	Unchanged
`settlingRich`	Both disabled briefly	Markdown parsed once	“Answer ready, N headings”	Stay put
`ready`	Send enabled	Settled article	Silent	Composer unless user is reading
`cancelled`	Send enabled	Partial plain text plus cancelled label	“Answer cancelled”	Composer
`error`	Send enabled	Error in `role="alert"`	Error text once	Alert, then composer

If your table only has loading and done, the heading injection path has nowhere to live. That is how it ships.

How I isolated it without guessing

I stopped arguing about ARIA and started logging the tree. Analogies help, but the accessibility tree is the crime scene.

Think of a live region as a news ticker, not as a book. A ticker can shout “still answering.” A book can contain headings, lists, and skip targets. When you feed a book through a ticker, every chapter title becomes a breaking-news interruption. Why would we expect NVDA to stay calm?

Reusable debugging steps that actually moved the needle:

Open Chrome DevTools → Accessibility on the transcript node and watch it while tokens arrive.
Enable NVDA Speech Viewer so you can see announcements you would otherwise talk over.
In the page console, attach a MutationObserver to every [aria-live] node and log added h1–h6 elements.
Replay the same prompt with a slow stream, not a mocked setTimeout of three words.
After cancel, inspect whether those headings remained in the rotor.

The observer that made the bug undeniable looks like this:

// Proposed reproduction helper — paste into DevTools on the chat page.
const lives = document.querySelectorAll("[aria-live]");
const obs = new MutationObserver((records) => {
  for (const record of records) {
    for (const node of record.addedNodes) {
      if (!(node instanceof Element)) continue;
      const heading = node.matches("h1,h2,h3,h4,h5,h6")
        ? node
        : node.querySelector("h1,h2,h3,h4,h5,h6");
      if (heading) {
        console.warn("heading entered a live region", {
          live: record.target.getAttribute("aria-live"),
          tag: heading.tagName,
          text: heading.textContent,
        });
      }
    }
  }
});
lives.forEach((el) => obs.observe(el, { childList: true, subtree: true }));

The first run printed three warnings in four seconds. That is not a screen-reader quirk. That is your renderer committing document structure into a region whose job is to interrupt.

Root cause: promoting Markdown before the turn is a document

The client was doing something that looks responsible in code review. It streamed tokens into a buffer, parsed GitHub-flavored Markdown on every animation frame, and set aria-live="polite" on the same article so “users hear the answer.”

// Buggy sketch — do not ship this pattern.
function StreamingAnswer({ buffer }: { buffer: string }) {
  return (
    <article aria-live="polite" aria-busy="true">
      <Markdown>{buffer}</Markdown>
    </article>
  );
}

Two independent mistakes stacked. First, aria-live on a container that grows real headings, lists, and links. Second, parsing Markdown during the stream, when ## Imp may become ## Implementation and then ## Implemented steps a moment later.

Screen readers do not owe you a stable cursor across those mutations. Headings are navigation landmarks. If you create and destroy them at token speed, you are animating the document outline. Would you animate the skip link too?

I also saw a quieter cousin of the same bug: an empty ## heading for one frame, announced as “heading level two” with no name. That is worse than silence, because it sounds like a broken page, not like a model that is still thinking.

Typed states, then one settled parse

The fix is not “more ARIA.” The fix is to stop treating a partial string as a document. I keep a tiny state machine so cancel, error, and settle cannot fight each other.

type TurnState =
  | { status: "idle" }
  | { status: "streamingPlain"; plain: string }
  | { status: "settlingRich"; plain: string }
  | { status: "ready"; plain: string; html: string; headingCount: number }
  | { status: "cancelled"; plain: string }
  | { status: "error"; message: string };

type TurnEvent =
  | { type: "START" }
  | { type: "TOKEN"; text: string }
  | { type: "DONE" }
  | { type: "CANCEL" }
  | { type: "FAIL"; message: string }
  | { type: "SETTLED"; html: string; headingCount: number };

During streamingPlain, the transcript is textContent. No Markdown. No headings. A separate, visually hidden live region may announce a throttled status, not the tokens themselves. After DONE, I parse once, count headings, swap in the rich article, and announce a single summary.

function statusAnnouncement(state: TurnState): string {
  switch (state.status) {
    case "streamingPlain":
      return "Still answering.";
    case "cancelled":
      return "Answer cancelled.";
    case "error":
      return state.message;
    case "ready":
      return state.headingCount > 0
        ? `Answer ready, ${state.headingCount} headings.`
        : "Answer ready.";
    default:
      return "";
  }
}

Pointer users still see a preview if you want one. Put that preview outside the live region, or mark it aria-hidden="true" until settle, and keep a plain-text twin for AT. Dual rendering sounds heavy until you watch a heading rotor fill with ghosts.

Minimal reproduction

This single-file sketch is a proposed demo, not a production chat client. Wire onToken to your existing stream reader.

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

function reduce(state: TurnState, event: TurnEvent): TurnState {
  switch (event.type) {
    case "START":
      return { status: "streamingPlain", plain: "" };
    case "TOKEN":
      if (state.status !== "streamingPlain") return state;
      return { ...state, plain: state.plain + event.text };
    case "CANCEL":
      if (state.status !== "streamingPlain") return state;
      return { status: "cancelled", plain: state.plain };
    case "FAIL":
      return { status: "error", message: event.message };
    case "DONE":
      if (state.status !== "streamingPlain") return state;
      return { status: "settlingRich", plain: state.plain };
    case "SETTLED":
      if (state.status !== "settlingRich") return state;
      return {
        status: "ready",
        plain: state.plain,
        html: event.html,
        headingCount: event.headingCount,
      };
    default:
      return state;
  }
}

export function StreamingTurn({
  parseMarkdown,
}: {
  parseMarkdown: (plain: string) => { html: string; headingCount: number };
}) {
  const [state, dispatch] = useReducer(reduce, { status: "idle" });
  const liveRef = useRef("");

  useEffect(() => {
    const next = statusAnnouncement(state);
    if (next && next !== liveRef.current) liveRef.current = next;
  }, [state]);

  useEffect(() => {
    if (state.status !== "settlingRich") return;
    const id = requestAnimationFrame(() => {
      dispatch({ type: "SETTLED", ...parseMarkdown(state.plain) });
    });
    return () => cancelAnimationFrame(id);
  }, [state, parseMarkdown]);

  const busy = state.status === "streamingPlain" || state.status === "settlingRich";

  return (
    <section aria-labelledby="answer-label">
      <h2 id="answer-label">Assistant</h2>
      <div aria-live="polite" className="sr-only">
        {liveRef.current}
      </div>
      {state.status === "streamingPlain" || state.status === "cancelled" ? (
        <p data-plain-preview="">{state.plain}</p>
      ) : null}
      {state.status === "ready" ? (
        <article
          aria-busy={false}
          dangerouslySetInnerHTML={{ __html: state.html }}
        />
      ) : null}
      {state.status === "error" ? (
        <p role="alert">{state.message}</p>
      ) : null}
      {state.status === "cancelled" ? (
        <p>Answer cancelled. Partial text is still on screen.</p>
      ) : null}
      <button type="button" disabled={!busy} onClick={() => dispatch({ type: "CANCEL" })}>
        Stop
      </button>
    </section>
  );
}

Yes, dangerouslySetInnerHTML still needs sanitization in a real app. The point of this demo is when headings exist, not how you bleach HTML.

Why a mocked three-token stream never caught it

Unit tests that await screen.findByText("hello") will pass forever. Heading injection needs a stream long enough to emit ##, a newline, a rewrite, and a cancel. Short mocks never build a rotor.

I needed a live completion that actually talks like a product answer: sections, lists, a stray heading, then more prose. Standing up a private GPU box for that client bug would have been theater. I pointed the same AbortController fetch reader at MonkeyCode’s free model access on their free server option so the stream was real enough to mutate the accessibility tree. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

I am not quoting model names, quotas, or hardware I cannot verify from this chair. The workflow is boring on purpose: one throwaway prompt, one slow answer, Speech Viewer open, observer logging headings. If the server is shared, I still do not paste secrets into the composer. The subject here is the client’s document outline, not prompt hygiene.

A reader-owned ReadableStream is enough to drive the reducer:

async function readPlainStream(url, { signal, onToken }) {
  const response = await fetch(url, { signal });
  if (!response.ok || !response.body) {
    throw new Error(`Stream failed with ${response.status}`);
  }
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    onToken(decoder.decode(value, { stream: true }));
  }
}

Cancel must abort the fetch and dispatch CANCEL so the UI does not stay in streamingPlain with a dead socket. Have you ever tabbed to Stop, pressed it, and heard nothing because the live region only spoke tokens? That is the same family of bug, just quieter.

Keyboard, cancel, and recovery

Pointer-independent behavior I now treat as required for this control:

Tab reaches Stop while streaming, then returns to the composer after ready, cancelled, or error.
Escape cancels when focus is inside the transcript or composer, not only when Stop is focused.
Stop is a real <button>, not a clickable <div>.
After cancel, partial plain text remains, labeled as cancelled, and is not promoted to headings.
After error, role="alert" holds the message; retry is a separate control that starts a new turn.

I do not move focus into the rich article on settle. If someone is reading with the virtual cursor, stealing focus to an <h2> you just created is the original incident with extra steps.

Environment-specific QA matrix

Please reproduce with versions written down. My request is the exact transition, not a vibe check.

Environment	Transition	Pass if
Windows + NVDA + Chrome	Stream emits `##` + newline	Speech Viewer does not say “heading” until settle
Windows + NVDA + Firefox	Cancel mid-heading	Rotor has no leftover empty headings
macOS + VoiceOver + Safari	Settle after a long answer	One “Answer ready” summary, headings appear only then
Keyboard only, any browser	Tab during stream	Stop remains reachable; focus does not jump to the transcript
Keyboard only	Escape during stream	State becomes `cancelled`; composer focuses
Screen magnifier	Settle	Layout shift from plain preview to rich article is visible but does not cover Stop

If your team only dogs-foods with a mouse and a short mocked stream, this bug will look theoretical until a customer files it as “the chat is broken.”

Limitations, and who should not copy this blindly

This pattern is a client recovery mechanism, not a conformance certificate. I am not claiming WCAG, and a demo with dangerouslySetInnerHTML is not a sanitizer.

Do not use this approach when:

You must expose live, navigable structure during generation (some tutoring and pair-programming UIs want that, and they need a different design).
You stream untrusted HTML and think settle-time parsing makes it safe.
You send private customer content to a shared free server just to debug CSS.
You throttle the status live region so aggressively that cancel and error stay silent.

There is also a product tradeoff: sighted users who like watching Markdown snap into lists will see a plainer stream. I would rather give them a non-live visual preview than give AT users a haunted heading rotor. You can CSS the preview; you cannot CSS a screen-reader cursor back into a sentence.

What I would test next

The next failure I want on the matrix is list injection: a lone - becoming a list, then becoming a paragraph again. Same family, different landmark. Code blocks that open without closing before cancel are next after that.

If you ship streaming Markdown into a live region today, you already have a document that rewrites its own outline. Can your heading rotor survive one long answer? If you need a throwaway live stream to watch the accessibility tree mutate, MonkeyCode’s free model access and free server option are enough to reproduce the heading-injection path on a real completion rather than three fake tokens.

Chat Retry Needs a Retired Turn, Not a Second Stop Button

babycat — Sat, 05 Sep 2026 19:01:54 +0000

I tabbed out of the composer after a failed generation and landed on a Stop button that should not have existed. The visible error said the turn had failed, but that control was still sitting in the tab order. I pressed Enter, expecting a quiet no-op, and the retry stream died halfway through a sentence. Have you ever shipped a Retry button that quietly revived a corpse of UI state from the last request?

This was not a model-quality problem, and it was not a sprinkle-aria-live-on-it problem either. It was a state-machine bug that only appeared on the keyboard path after an error. Mouse users clicked the large Retry control and never noticed the old Stop button. Keyboard and screen-reader users walked the transcript and found two in-flight turns sharing one conversation.

The failure, as a state table

I wrote the table before touching more markup, because the interface had been lying in more than one status. If a status cannot answer whether Stop belongs in the tab order, it is not a real status. Read the failed row twice, because that is the row my build violated. Does your chat UI even have a failed row, or only isLoading?

Turn status	Composer	Stop tabbable?	Retry tabbable?	Live region	Focus after the action
idle	enabled	no	no	silent	composer
streaming	locked	yes, one control	no	polite token updates	remain
failed	enabled	no	yes	assertive error once	Retry or composer
cancelled	enabled	no	optional Retry	polite cancelled	composer
complete	enabled	no	regenerate only	polite completed	composer

The broken client violated the failed row in three ways at once. Stop remained focusable beside a brand new Stop from the retry. The live region still advertised aria-busy="true" on an article whose fetch had already died. Which control should Enter activate when two Stop buttons and one Retry share the same toolbar?

What the keyboard path actually did

The prototype handled the happy path well enough for a local demo. Tokens painted into an article, the assistant content grew, and focus stayed in the composer like a decent messenger window. Then the stream failed after a few chunks, which is exactly when chat UI starts improvising states. I reproduced it with a mock that died on chunk four, then later with a real abort from a free shared endpoint.

Here is the exact transition that broke:

The user submits a prompt, and a stream begins with requestId = "turn-14".
The network errors after a few chunks, and the bubble shows a generic failure.
Retry is activated with Enter, and turn-15 starts streaming new tokens.
Tab order still contains Stop for turn-14, Stop for turn-15, then the composer.
The failed article still exposes aria-busy="true" and a leftover live name.

Does that look like a CSS leftover from a loading spinner? It looks like one until you count Stop buttons in the accessibility tree. I asked myself a rude question about ownership: if Stop is visible, which request id does it abort? The component could not answer, because it did not store an id on the button.

Root cause: retry mounted a new turn without retiring the old one

The renderer treated existing assistant markdown as a sign that the turn might still be streaming. Failed turns reused the streaming component, including its Stop button and its busy flag. Retry appended a sibling assistant article instead of committing the failed turn to a terminal status. Why would a boolean named isLoading know the difference between this id failed and some other id is live?

One AbortController ref for the whole thread

I had a single abortRef on the screen, not on the turn. Ghost Stop called abortRef.current.abort() after retry had already replaced the ref. Sometimes that aborted turn-15 and looked like a flaky model instead of a UI bug. Sometimes the ref was already null, so the button clicked, announced nothing, and stayed enabled.

Two symptoms came from one shared mutable slot. A conversation is a list of turns, and each inflight turn needs its own controller. If Stop cannot name its requestId, it should not be in the document. Would you ship a close button that closed a random tab?

A renderer that equated "not complete" with "stoppable"

The template mapped Stop buttons with a check like status !== "complete". Failed and cancelled are also not complete, so they inherited a deadly control. Disabled styling was applied inconsistently, and an undisabled button stayed in the tab order. Unmount the control when the turn is terminal, instead of hiding it with CSS and hoping keyboard users cannot find it.

visibility: hidden is not a state machine. pointer-events: none is not a state machine either. If the accessibility tree can still focus Stop, the turn is still streaming as far as the keyboard is concerned. That is the whole bug in one sentence, and it is easy to miss with a mouse.

Give every turn a terminal status

I threw away the boolean soup of isLoading, isError, and canStop. Each turn now carries a status union and a stable requestId. The conversation machine allows at most one inflight id. If you cannot point to that id, you do not render Stop.

type TurnStatus = "streaming" | "failed" | "cancelled" | "complete";

type ChatTurn = {
  requestId: string;
  role: "user" | "assistant";
  markdown: string;
  status: TurnStatus;
  error?: string;
  abort?: AbortController;
};

type ChatMachine =
  | { phase: "idle"; turns: ChatTurn[]; inflight: null }
  | { phase: "streaming"; turns: ChatTurn[]; inflight: string }
  | { phase: "recoverable"; turns: ChatTurn[]; inflight: null; recoverFrom: string };

Stop renders only when phase === "streaming", and aria-controls equals inflight. Retry renders only when phase === "recoverable". That pairing sounds strict, and it is strict on purpose. Can a ghost Stop exist if the phase forbids it? Only if you bypass the machine and render from a leftover turn field.

The retry reducer retires first

Retry is not call fetch again and hope React reconciles the right bubble. Retry is a commit that retires the failed assistant article, then opens a new streaming article with a new id. I keep the original user prompt as a single user turn so the transcript does not hear the question twice. Should a screen reader really hear the same prompt stacked like a stutter?

function retireTurn(
  turns: ChatTurn[],
  requestId: string,
  status: "failed" | "cancelled",
  error?: string
): ChatTurn[] {
  return turns.map((turn) => {
    if (turn.requestId !== requestId) return turn;
    turn.abort?.abort();
    return { ...turn, status, error, abort: undefined };
  });
}

function retryFrom(machine: ChatMachine, failedId: string): ChatMachine {
  if (machine.phase === "streaming") {
    return machine; // ignore double Enter while a stream is live
  }

  const requestId = crypto.randomUUID();
  const abort = new AbortController();

  return {
    phase: "streaming",
    inflight: requestId,
    turns: [
      ...retireTurn(machine.turns, failedId, "failed"),
      {
        requestId,
        role: "assistant",
        markdown: "",
        status: "streaming",
        abort,
      },
    ],
  };
}

Notice the early return when a stream is already live. Double-activating Retry with Enter is a classic keyboard failure, and swallowing the second activation is kinder than mounting a third article. The retired turn keeps its error text so screen-reader users can still read what went wrong. Its Stop button is gone because status is failed and abort is undefined.

Ignore stale chunks after you retire a turn

AbortController rejects the fetch, but the browser may already have buffered SSE bytes. If the reader loop appends those bytes without checking identity, a failed article starts speaking again after you announced the error. I guard both the loop and the reducer, because either hole is enough to revive a corpse. Have you logged request ids next to markdown length while clicking Stop?

function applyChunk(
  machine: ChatMachine,
  requestId: string,
  chunk: string
): ChatMachine {
  if (machine.inflight !== requestId) return machine;

  return {
    ...machine,
    turns: machine.turns.map((turn) => {
      if (turn.requestId !== requestId || turn.status !== "streaming") return turn;
      return { ...turn, markdown: turn.markdown + chunk };
    }),
  };
}

async function pumpStream(
  turn: ChatTurn,
  dispatch: (chunk: string) => void
) {
  const response = await fetch("/stream", {
    method: "POST",
    signal: turn.abort?.signal,
    headers: { Accept: "text/event-stream" },
  });

  if (!response.ok || !response.body) {
    throw new Error(`Stream HTTP ${response.status}`);
  }

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

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    if (turn.status !== "streaming") break;
    dispatch(decoder.decode(value, { stream: true }));
  }
}

The inflight !== requestId check is the one I missed first. Without it, a late chunk from turn-14 writes into whichever article your map function finds, or worse, into turn-15. Visual tokens lie about ownership when two articles are growing in the same frame. The reducer has to refuse work that belongs to a retired id.

Focus, Escape, and the live region

Unmounting ghost Stop is not the whole accessibility job. You still owe people a focus place, a cancel key, and an announcement that does not replay the entire thread. I used four rules and a tiny focus helper. None of these rules require a new ARIA role on the transcript itself.

Unmount Stop on terminal turns; do not leave a disabled duplicate unless it is the only way to preserve focus.
If focus was on Retry when the new stream started, move it to the new Stop control.
If focus was in the composer, leave it there so typing is not stolen mid-thought.
Bind Escape to cancel only while phase === "streaming", and announce "Generation stopped" once.

function moveFocusAfterRetry(args: {
  previousActive: Element | null;
  nextStop: HTMLButtonElement | null;
  composer: HTMLTextAreaElement;
}) {
  const { previousActive, nextStop, composer } = args;
  if (
    previousActive instanceof HTMLElement &&
    previousActive.dataset.action === "retry"
  ) {
    nextStop?.focus();
    return;
  }
  if (!composer.contains(document.activeElement)) {
    composer.focus();
  }
}

For announcements, I keep one polite status node outside the transcript, not a live region wrapped around every token. Token painting stays in a regular article with aria-busy tied to the inflight id. Failure uses a single assertive sentence, then the region returns to polite. If you leave assertive on during retry, the next few tokens will interrupt each other like a broken auctioneer.

Escape handling belongs on a keydown listener at the chat layout, not only on the Stop button. Users cancel from the composer, and a button-only shortcut will miss them. Clear the inflight id in the same tick you abort, so a second Escape cannot resurrect a ghost controller. Do we need the whole thread re-read when one turn fails? Almost never.

A small reproduction you can paste

The following sketch is a proposed single-file driver, not a production chat SDK. Wire form submit, Retry, Stop, and Escape to the machine above, then watch the button count. I want the accessibility tree to show zero Stop controls in failed, and exactly one in streaming. If the count is ever two, the lab has failed before any model answer matters.

<section aria-labelledby="chat-title">
  <h1 id="chat-title">Retry lab</h1>
  <p id="status" aria-live="polite" aria-atomic="true"></p>
  <ol id="log"></ol>
  <form id="composer-form">
    <label for="composer">Message</label>
    <textarea id="composer" name="prompt"></textarea>
    <button type="submit">Send</button>
    <button type="button" id="stop" hidden>Stop generating</button>
  </form>
</section>
<script type="module">
  // Plug retryFrom / applyChunk here.
  // After a forced fail, count document.querySelectorAll("[data-role=stop]").
  // Expected: 0 before retry, 1 after retry, 0 after the retry fails too.
</script>

Expected UI states for that lab:

After fail: error text in the list, Retry visible, Stop hidden, composer enabled.
After retry: one empty assistant article busy, Stop visible, Retry not in tab order.
After cancel: polite "Generation stopped", Stop hidden, focus in the composer.
After stale chunk: markdown length on the failed article does not change.

Force the first failure with a mock that throws after four chunks, because you want a deterministic keyboard path. Then Tab from the composer through the transcript and count Stop. If you cannot describe that walk in one sentence, the machine is still leaking controls.

Reproducing the network half without lying in the UI

A local mock that errors on chunk four is the honest first tool, because it is deterministic. I still wanted one run against a real stream boundary, where abort, HTTP errors, and partial bodies show up without my timers. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project with free model access and a free server option. I used that option only as a disposable network boundary for this client-side retry lab. I am not listing model names, quotas, or uptime, because those claims go stale and they are not the bug. If you already have a mock that can fail, keep it; swap in that free server only when the ghost Stop is gone and you need a genuine abort.

QA matrix I want you to run

I am not attaching a conformance badge, because I cannot see your browser, operating system, or assistive technology. Please record versions next to the exact transition that failed. The interesting path is fail, then retry, then Tab, not the first-token happy path. Will your matrix still pass if Retry is activated from the keyboard twice?

Transition	Keyboard expectation	Screen reader expectation
stream → fail	Tab never lands on Stop	Assertive error, busy false on the failed article
fail → retry	Exactly one Stop, old Retry gone or not tabbable	"Retrying the previous prompt" once
retry → Escape	Only the inflight id aborts	"Generation stopped", focus returns to composer
stale chunk after fail	Failed markdown stays frozen	No second token announcement on the dead turn
double Enter on Retry	Second press ignored while streaming	No duplicate assistant articles

Try it with the pairs you actually have: Chromium plus NVDA, Firefox plus NVDA, Safari plus VoiceOver. If Tab still finds two Stop buttons, the machine is not the source of truth yet. If announcements concatenate the old error with new tokens, your live region is still shared across request ids. Send the failing transition, not a screenshot of the happy path.

Limitations, and who should not copy this blindly

This pattern assumes one inflight generation per transcript, which matches most product chats and fights ghost controls. Multi-pane agent dashboards that run parallel tool streams need a list of inflight ids, each with its own Stop and its own article. Voice-primary UIs may park focus on Stop during streaming; this lab parks on the composer so typing is not stolen.

Do not point a free shared server at prompts that contain secrets, customer data, or API keys. The state machine does not redact anything, and a disposable endpoint is still someone else's process. I also do not replace the failed article in place, so error history grows; if you collapse errors, keep a textual summary or you will hide the reason Retry exists.

This is not a WCAG certificate, and it is not a benchmark of any model host. It is a debugging record of a ghost Stop button, a shared abort ref, and a retry path that forgot to retire the previous turn. If your chat can fail, it can fail while someone is holding a keyboard. Does your Retry control know which request it is allowed to start?

Agent Clarifying Questions Need a Focus Handoff, Not a Noisier Live Region

babycat — Fri, 04 Sep 2026 16:55:40 +0000

Last Tuesday I asked a browser agent to draft an accessible confirmation dialog, and it started streaming tokens immediately. I kept focus in the composer because that is where every chat teaches your hands to stay. Halfway through the answer, a clarifying card asked which heading level I wanted, but nothing spoke. Have you ever submitted a follow-up while the agent was still waiting on a yes or no?

I hit Enter in the textarea, sent a half thought, and watched the card collapse without an error. VoiceOver was still reciting leftover tokens from the stream, so the question never interrupted that noise. Keyboard focus never left the composer, which meant the radios existed only for a pointer I was not using. This is the retrospective of that silent state change, not another aria-live pep talk.

The failure, in the order it happened

The visual transcript looked busy and healthy, which is exactly how this class of bug hides. Tokens kept painting into a markdown bubble, then a pale card slid in above the composer with two choices. I never tabbed to it because Tab from a textarea usually jumps to Send, not to a sibling that was injected later. Why would I hunt for a control that never announced itself as the new task?

Here is the sequence I could reproduce with a stubbed stream, without blaming any particular model vendor.

Composer focused, aria-live="polite" attached to the streaming bubble.
Token chunks replace the live-region text several times per second.
The agent switches intent and renders a clarifying card as markdown paragraphs.
The live region still holds the last token string, so the question is overwritten.
Enter in the composer submits a user message and the card unmounts.

[ streaming bubble | aria-live polite | FOCUS stays here in <textarea> ]
[ clarifying card  | two unlabeled <p> tags | not in tab order yet     ]
[ Send button ]

The pointer path still worked, which is how this shipped past a happy-path demo. Keyboard and speech users got a different product: a composer that swallowed the agent's only question. That is not a content problem. That is turn-taking UI with one control too few.

Put the state table up front

I stopped tweaking ARIA first and wrote the turn states the interface actually has. If a state cannot answer where focus lives, it is not a state yet, it is a spinner costume. Does your chat distinguish streaming from awaiting_user, or do both look like "the model is thinking"?

Turn state	Composer	Question card	Announcement	Focus target
`idle`	enabled, submits	hidden	none	composer
`streaming`	disabled, no Enter submit	hidden	once: "Generating answer"	composer (do not jump)
`awaiting_user`	disabled, no Enter submit	visible fieldset	once: "Question needs an answer"	legend or first radio
`error`	enabled	hidden	error text	retry or composer
`cancelled`	enabled	hidden	"Generation cancelled"	composer

Notice what is missing on purpose: per-token announcements. Streaming text is a visual progress channel, not a speech channel, unless you like a novel read one syllable at a time. The clarifying turn is the one that must steal the microphone, because it is the only turn that cannot complete without the keyboard.

A single-file reproduction

The demo below is labeled as a local stub. It does not call a production model, and it does not prove conformance. It only makes the race obvious: a timer pretends to stream, then flips into awaiting_user while focus is still in the textarea. Load it, start the stub, and keep your hands on the keyboard the whole time.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Clarifying-card focus handoff demo</title>
  <style>
    body { font: 1rem/1.4 system-ui; max-width: 40rem; margin: 2rem auto; }
    textarea, button, [role="status"], [role="alert"] { display: block; width: 100%; margin: 0.5rem 0; }
    .card { border: 2px solid #222; padding: 1rem; margin: 1rem 0; }
    textarea:disabled { background: #f3f3f3; }
  </style>
</head>
<body>
  <h1>Accessible clarifying turn</h1>
  <div id="status" role="status" aria-atomic="true"></div>
  <div id="alert" role="alert" aria-atomic="true"></div>
  <div id="stream" aria-hidden="true"></div>
  <div id="questionHost"></div>
  <label for="composer">Message</label>
  <textarea id="composer" rows="3"></textarea>
  <button type="button" id="send">Send</button>
  <button type="button" id="cancel">Cancel generation</button>

  <script>
    /** @typedef {"idle" | "streaming" | "awaiting_user" | "error" | "cancelled"} Kind */
    /** @type {{ kind: Kind, questionId?: string }} */
    let turn = { kind: "idle" };
    const statusEl = document.getElementById("status");
    const alertEl = document.getElementById("alert");
    const streamEl = document.getElementById("stream");
    const host = document.getElementById("questionHost");
    const composer = document.getElementById("composer");
    const send = document.getElementById("send");
    let timer = 0;

    function announceStatus(text) { statusEl.textContent = ""; statusEl.textContent = text; }
    function announceError(text) { alertEl.textContent = ""; alertEl.textContent = text; }

    function render() {
      const waiting = turn.kind === "streaming" || turn.kind === "awaiting_user";
      composer.disabled = waiting;
      send.disabled = waiting;
      if (turn.kind !== "awaiting_user") host.innerHTML = "";
    }

    function startStream() {
      turn = { kind: "streaming" };
      streamEl.textContent = "";
      announceStatus("Generating answer");
      render();
      let n = 0;
      timer = window.setInterval(() => {
        n += 1;
        streamEl.textContent += " token" + n;
        // Broken behavior for comparison: uncomment to starve the question.
        // statusEl.textContent = streamEl.textContent;
        if (n === 8) {
          window.clearInterval(timer);
          askQuestion();
        }
      }, 80);
    }

    function askQuestion() {
      turn = { kind: "awaiting_user", questionId: "heading-level" };
      announceStatus("Question needs an answer");
      host.innerHTML = `
        <form class="card" id="qform">
          <fieldset>
            <legend id="qlegend" tabindex="-1">Which heading level should the dialog use?</legend>
            <label><input type="radio" name="level" value="h2" /> h2</label>
            <label><input type="radio" name="level" value="h3" /> h3</label>
          </fieldset>
          <button type="submit">Continue</button>
        </form>`;
      render();
      document.getElementById("qlegend").focus();
      document.getElementById("qform").addEventListener("submit", (event) => {
        event.preventDefault();
        const picked = new FormData(event.currentTarget).get("level");
        if (!picked) {
          announceError("Choose a heading level to continue");
          return;
        }
        turn = { kind: "idle" };
        announceStatus("Answer received, ready for the next message");
        render();
        composer.focus();
      });
    }

    send.addEventListener("click", () => {
      if (turn.kind !== "idle") return;
      startStream();
    });
    composer.addEventListener("keydown", (event) => {
      if (event.key === "Enter" && !event.shiftKey) {
        event.preventDefault();
        if (turn.kind === "idle") startStream();
      }
    });
    document.getElementById("cancel").addEventListener("click", () => {
      window.clearInterval(timer);
      turn = { kind: "cancelled" };
      announceStatus("Generation cancelled");
      render();
      composer.focus();
    });
    document.addEventListener("keydown", (event) => {
      if (event.key === "Escape" && turn.kind === "awaiting_user") {
        turn = { kind: "cancelled" };
        announceStatus("Question dismissed");
        render();
        composer.focus();
      }
    });
  </script>
</body>
</html>

If you uncomment the starved live-region line, the status node keeps echoing tokens and the later question announcement is easy to miss. That is the whole bug in one assignment. Should a progress string ever share the node that must carry the next required action?

How I replayed the timing without burning a paid quota

Streaming races are origin-sensitive, because cold connections, chunk buffering, and UI commit timing refuse to line up the same way twice. I needed a disposable host that could stream slowly enough for the card to appear mid-keystroke, and I did not want that experiment glued to a production key. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option were the throwaway origin I used to restage the same streaming to awaiting_user flip, then I copied the failure back into the stub above so the article stays runnable offline.

The product is not the fix. The fix is the state table, the second live region, and the focus handoff. If you already have a local mock that can pause a stream and inject a question, you do not need another host at all.

What the root cause actually was

Three independent mistakes stacked, which is why "add aria-live" kept failing in review. The first mistake was treating token text as status text, so polite announcements queued behind a paragraph that never finished. The second was rendering the question as markdown p tags, so there was no fieldset, no legend, and no tab stop. The third was leaving the composer enabled, so Enter still meant Send while the agent meant Answer me.

I also had a focus-loss variant that looked like the opposite bug. An early patch called card.focus() on a div without tabindex="-1", which silently did nothing in Chrome, and then a later patch focused the first radio before the name was announced. Have you watched VoiceOver say "radio button, one of two" with no legend, and trusted the user to guess the question? That is not an interruption. That is a riddle.

Root cause, compressed:

One live region served tokens, status, errors, and questions.
Interactive turns were painted, not focused, and not semantically a form.
The composer kept the submit keystroke that belonged to the new turn.
Cancel did not restore focus, so Escape felt like the page died.

The fix: typed turns, two channels, one handoff

I keep role="status" for milestones and role="alert" for failures, and I never write token leftovers into either node. The streaming bubble can stay in the DOM for eyes, with aria-hidden="true" if you already announced "Generating answer" once. When the turn becomes awaiting_user, I render a real fieldset, announce once, and move focus to the legend that has tabindex="-1". Pointer users can still click radios. Keyboard users are already inside the question.

The composer disables for both streaming and awaiting_user, which answers the Enter question without a special-case key map. Escape cancels only the interactive turn and returns focus to the composer, which is the same recovery I want after a network error. Retry is just idle plus the last user message, and it must allocate a new logical turn so a dead timer cannot resurrect a dismissed card.

Implementation notes I actually rely on:

Clear then set textContent on live regions so repeated identical strings still fire.
Use aria-atomic="true" so speech gets the whole question status, not a suffix.
Do not aria-live the fieldset itself; focus plus a short status is enough.
Keep Send disabled while waiting, or you will recreate the original Enter bug.
Return focus after Continue, otherwise the next stream starts from the leftover radio.

Is a modal dialog better? Sometimes, if the question is blocking and short. A modal still needs the same state machine, because a dialog opened during streaming can trap focus on a half-rendered label. The card pattern stays in flow, which is kinder when the transcript is the document. Pick one and type it. Do not mix a toast, a card, and a dialog for the same turn.

Keyboard and screen-reader regressions

I do not ship this without a matrix, and I do not treat a green Lighthouse score as speech coverage. Fill the last column with the exact build you ran, because AT plus browser plus OS is the unit, not "VoiceOver" as a brand name. The transition that failed for me was streaming → awaiting_user with focus in the textarea and Caps Lock VO on.

Environment	Transition	Expected
Chrome + VoiceOver + macOS	`streaming` → `awaiting_user`	Status once, focus on legend
Safari + VoiceOver + macOS	Tab from legend	First radio, then Continue
Firefox + NVDA + Windows	Enter in composer during stream	No submit
Keyboard only, no AT	Escape on question	Card gone, composer focused
Screen magnification	Card appears	Card not offscreen above a sticky header

Regression scripts I keep next to the demo:

Start stub, do not touch the mouse, wait for the question, speak the legend.
Tab through radios, submit without a choice, hear the alert, stay in the form.
Escape, confirm composer focus, Send should work again.
Repeat with the starved live-region line enabled, and notice speech never reaches the question.

If your team only click-tests the card, you will reintroduce the bug the first time someone wires markdown rendering back in. Ask whether the clarifying UI is a form in the accessibility tree, not whether it looks like a card in Figma.

Limitations, and who should not copy this

This pattern does not certify WCAG, and it does not replace a real design review for multi-step agent plans. It also steals focus, which is hostile if you fire awaiting_user for optional suggestions the user never requested. I would not use a focus handoff for inline citations, token progress, or tool-call heartbeats. Those are status. They can wait.

Skip this approach when your agent never asks questions and only streams a final bubble. Skip it in native shells that already route focus through platform alerts. Skip it if your "card" is three questions long, because a legend plus two radios is not a wizard, and you will need a different stepper with its own recovery. And please do not announce every token to make the interface feel alive. Alive is not the same as usable.

The reusable debugging move is smaller than the demo. When an AI surface fails, freeze the turn type, print focus, and print the live-region text at the moment of the transition. If those three lines disagree, you do not have an agent-quality problem. You have a chat that cannot take turns with a keyboard.

Fix Silent 30s AI Stream Timeouts with a Client Watchdog

babycat — Fri, 04 Sep 2026 15:00:44 +0000

Your AI stream can die silently at exactly 30 seconds because the proxy's read timeout kills idle connections—not because the model stopped. I traced this while testing a chat widget against MonkeyCode's free server, and the fix is a client-side watchdog that turns a lying spinner into an honest state machine.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The product wasn't misbehaving; the architecture around it was. The same silent death awaits anyone who streams AI responses through a proxy that has opinions about time.

Why AI streams die silently at 30 seconds

The stream died at exactly 30.0 seconds. Not 29.4, not 31.2—30.0, like a metronome. The chat widget sat there with its spinner spinning, the last token rendered halfway through a sentence, and no error, no close event, no status change. Just silence. I waited, then refreshed. The response was gone, and so was whatever the server had been generating.

Before changing anything, I instrumented the stream with timestamps on every chunk:

Time	Event
0.0s	Request sent, first token arrives
0.0–29.8s	Tokens arrive steadily
29.8s	Last chunk rendered
60.0s+	Nothing. No error, no close, no timeout

The stream did not die after 30 seconds of total time. It died after 30 seconds of silence. The model had paused—likely thinking, or waiting on a tool boundary—and the proxy treated that pause as a dead connection. It was not measuring activity; it was measuring the gap between reads.

This is classic proxy_read_timeout behavior in reverse proxies like Nginx. The timer resets on every read from the upstream. When the upstream goes quiet for 30 seconds, the proxy closes the socket without sending a response. The client's fetch stream just ends: no status code, no error body, no close event with a reason. The promise chain waits for a done that never comes. From the UI's perspective, the model is still thinking.

How I isolated the timeout layer by layer

I ran the classic debugging ladder, one layer at a time, so I would not "fix" the wrong thing. A stall that only happens in Chrome is a fetch quirk. A stall that also happens in curl is infrastructure.

Reproduce outside the browser. Same prompt, same endpoint, no UI.
Hit the provider directly, bypassing the proxy. If generation continues past 30 seconds, the model is not the problem.
Build a minimal local proxy that pauses. If a 35-second sleep between two SSE frames dies only when routed through the gateway, you have found the timeout.

curl -N https://free-server.example/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Write a very long story..."}'

Same result: tokens flow, then stop at 30.0s. Not a browser issue. The same prompt through the upstream API kept generating past 30 seconds without a pause. The provider was not the problem.

Then I simulated a thinking pause:

app.post('/api/chat', async (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/event-stream' });
  res.write('data: first\n\n');
  await new Promise(r => setTimeout(r, 35000)); // simulate a model thinking pause
  res.write('data: second\n\n');
  res.end();
});

When I ran this through the free server's gateway, the client never received second. Locally, it worked. The gateway was killing connections that went silent for 30 seconds.

Root cause: the gateway enforces a 30-second proxy_read_timeout. That timer measures the gap between consecutive reads from upstream. Bytes flowing reset it. A quiet stretch—a reasoning pause or a tool call waiting on an API—expires it, and the gateway closes the socket.

Add a client-side watchdog to the streaming loop

You often cannot change the gateway timeout on a free server, so the fix has to live on the client. I added a watchdog to the streaming loop. If no chunk arrives within a threshold, the UI moves to a visible stalled state. If silence lasts past the known timeout, it offers recovery.

function createWatchdog(onStall, onTimeout, stallMs = 15000, timeoutMs = 30000) {
  let timer;
  const reset = () => {
    clearTimeout(timer);
    timer = setTimeout(() => {
      onStall();
      timer = setTimeout(onTimeout, timeoutMs - stallMs);
    }, stallMs);
  };
  const clear = () => clearTimeout(timer);
  return { reset, clear };
}

Reset the watchdog on every chunk:

const watchdog = createWatchdog(
  () => setState({ status: 'stalled' }),
  () => setState({ status: 'timed_out' })
);

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  watchdog.reset();
  buffer += decoder.decode(value, { stream: true });
  onToken(buffer);
}

Honest states instead of a perpetual spinner:

type ChatState =
  | { status: 'idle' }
  | { status: 'streaming' }
  | { status: 'stalled'; received: number }
  | { status: 'timed_out'; received: number }
  | { status: 'recovering'; attempt: number }
  | { status: 'error'; message: string };

ReadableStream gives you no signal when the socket is killed silently—MDN notes that read() just never resolves. The watchdog is how you detect the gap.

Compare the two UX paths:

Spinner-only: the user waits, assumes the model is thinking, then refreshes and loses the partial answer.
Watchdog states: the user sees stalled after 15 seconds of silence, then timed_out at 30 seconds, with a choice to continue or restart.

Recover the partial answer and announce the stall

A model cannot resume a dead stream—it is stateless. You can send the partial transcript and ask it to continue. That is reconstruction, not resume, but it works surprisingly well:

async function continueFrom(buffer) {
  const continuationPrompt = `
The previous response was interrupted mid-sentence.
Here is exactly what was generated so far:

${buffer}

Continue from the exact point where it stopped.
Do not repeat any of the text above. Do not summarize it.
`;

  return stream(continuationPrompt);
}

Offer an explicit choice: "The connection stalled after 340 tokens. [Continue from here] [Restart]". Let the user decide, rather than silently reconnecting and duplicating tokens.

A silent stall is worse for screen reader users: they hear nothing, the accessibility tree does not change, and they reasonably assume the response is complete. Announce state changes through a live region:

function setState(next) {
  state = next;
  if (next.status === 'stalled') {
    statusRegion.textContent = 'The connection stalled. Waiting for more data.';
  } else if (next.status === 'timed_out') {
    statusRegion.textContent = 'The connection timed out. You can continue from the last received text or restart.';
  }
}

Recovery buttons need keyboard focus. Escape should cancel a stalled stream just like an active one: pointer-independent, announced, and honest about the in-between state.

Skip or simplify this pattern when:

You need the original ending, not a reconstructed continuation.
Your stall threshold is so low that "model thinking" looks dead. Fifteen seconds worked for me.
The provider bills for the abandoned generation and the continuation.
The proxy already supports SSE comment-frame heartbeats—prefer those.
The provider has a resumable stream API or generation ID. Use that instead of a prompt hack.
A simple "Try again" button is enough. Watchdogs are for long generations where restarting hurts.

The 30-second curse taught me to instrument first, isolate layer by layer, and never trust a spinner. Free tiers surface these failures because their gateways protect cost, not long generative sessions. MonkeyCode's free server is a fine place to reproduce this: you can afford to break things and learn the failure modes before they hit production.

Try it now: spin up MonkeyCode's free server, reproduce the 30-second stall, and add the watchdog to your streaming client. Your users deserve an honest spinner.

MonkeyCode provides free models that can run this workflow.

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

Streaming AI Watermarks Change Mid-Response—Test the Announcement Before You Ship It

babycat — Fri, 04 Sep 2026 14:00:21 +0000

A screen reader user asks a chat interface to summarize a rental agreement. The first sentence readout sounds fine, the next few words arrive, and then the same sentence is spoken again from the beginning. The text did not change; a watermark verifier had changed its classification from unverified to detected. The assistant was not trying to be annoying. The live region was.

Streaming AI UIs already carry a surprising number of invisible states: partial answer, retryable error, cancelled request, exhausted quota, and network reconnect. A watermark adds another state that arrives asynchronously and often changes mid-stream. If you tie that state to the same live region as the answer text, every background classification event becomes speech. The problem is not that a model produces a watermark; it is that the frontend has no separate, low-frequency channel for provenance.

Start by writing the state table before you touch a component. It forces you to decide what is visually salient and what is screen-reader salient.

State	Visual treatment	Screen reader announcement	Focus expectation
pending	muted gray dot near the result	'Watermark check pending.' announced once	focus stays on the Stop button
detected	visible badge next to the result	'This response appears to be AI-generated.' announced once	focus does not move
inconclusive	outline-only warning	'Watermark check could not determine provenance.' announced once	focus does not move
failed	badge with a retry button	'Watermark check failed. Use the retry button to run it again.'	retry button is next in tab order, not focus-stealing

The live region should expose only the status, not the answer. Here is a runnable mock that reproduces the duplicate announcement and shows the fix.

<div id='stream-root'>
  <div id='answer' aria-live='polite' aria-atomic='false'></div>
  <p id='watermark-status' role='status'></p>
  <button id='stop' type='button'>Stop</button>
</div>

const answerEl = document.getElementById('answer');
const statusEl = document.getElementById('watermark-status');
const stopButton = document.getElementById('stop');

let lastAnnouncedWatermark = '';
let aborted = false;

const tokenStream = [
  { text: 'The ', state: 'pending' },
  { text: 'agreement ', state: 'pending' },
  { text: 'ends ', state: 'pending' },
  { text: 'auto-renewal ', state: 'detected' },
  { text: 'after ', state: 'detected' },
  { text: 'one year.', state: 'detected' }
];

const messages = {
  pending: 'Watermark check pending.',
  detected: 'This response appears to be AI-generated.',
  inconclusive: 'Watermark check could not determine provenance.',
  failed: 'Watermark check failed. Use the retry button to run it again.'
};

function updateWatermark(nextState) {
  if (nextState === lastAnnouncedWatermark) return;
  lastAnnouncedWatermark = nextState;
  statusEl.textContent = messages[nextState] || '';
}

async function runStream() {
  answerEl.textContent = '';
  statusEl.textContent = '';
  lastAnnouncedWatermark = '';
  aborted = false;

  for (const chunk of tokenStream) {
    if (aborted) return;
    answerEl.textContent += chunk.text;
    updateWatermark(chunk.state);
    await new Promise((resolve) => setTimeout(resolve, 180));
  }
}

stopButton.addEventListener('click', () => {
  aborted = true;
  updateWatermark('failed');
});

runStream();

The two important lines are the separate <p role='status'> and the lastAnnouncedWatermark guard. role='status' already maps to a polite live region, so you do not need aria-live on the answer container. More importantly, the status element is not inside the answer element. If it were, a screen reader could announce the whole answer again when the badge appeared, because the parent region changed. The guard prevents the status from announcing pending twice on the next chunk.

When I tested this with VoiceOver and Safari, NVDA and Chrome, and JAWS and Chrome, the important behavior was not that the badge became visible. It was that focus stayed on the Stop button while the status line changed. If the status change had focused the badge, keyboard users would have lost their place in the conversation. That is the accessibility regression you should encode in a test: every watermark transition must be focus-neutral.

The abort and retry paths are where most implementations fall apart. Use an AbortController around the real fetch call. If the stream is cancelled, announce 'Response stopped before it finished.' once, not 'Watermark check failed.' If the network fails mid-stream, announce 'Response interrupted. I did not receive the full answer.' The user needs to know whether content was lost, not whether a provenance check was complete. Confusing one error with the other is the same class of bug as announcing a duplicate answer.

Where does a free endpoint fit? If you are iterating on this, you will run the stream many times to catch repeated announcements, missed cancellations, and focus jumps. Metered API calls can make you stop after one or two runs. According to MonkeyCode's outreach materials, the open-source project offers a free allowance of 30 million tokens and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. That makes the proxy route cheap to run while you test the frontend state machine. The free tier is not a substitute for a real verifier; it is a sandbox for the part you own, which is the accessible presentation of a state transition.

There are cases where this pattern is not worth the extra state. If your model does not expose a watermark state, you cannot announce one. If you need strong provenance for legal or adversarial purposes, use the model provider's verified detector rather than a client-side badge. If you are not streaming, a single completion status after the answer is enough. But if your interface streams generated text and also reports provenance, you already have two channels: the message and the status. Give them two live regions, announce each transition once, and keep every transition focus-neutral. The watermark may be new, but the interaction failure is old: a state changed outside the user's attention, and the interface spoke when nobody needed to hear it.

MonkeyCode provides free models that can run this workflow.

Streaming Tool Calls Need a Working State, Not a Forever Spinner

babycat — Fri, 04 Sep 2026 13:00:07 +0000

I pressed Enter on a short prompt and watched the composer freeze like a stuck elevator door. The stop button took focus, which felt correct, and then nothing visible happened for several seconds. Was the stream dead, or was my loading state lying to every keyboard user in the room? The Network panel kept appending tiny SSE frames, so the socket was alive while the UI played dead.

Then the polite live region finally spoke a curly brace, followed by a quoted key, and the bug stopped looking like downtime. Have you ever trusted a spinner more than the shape of the events feeding it? I had, and the transcript paid for that shortcut.

The hang was a missing phase, not a dead socket

I was wiring an accessible chat client against a streaming completion endpoint on a spare box. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I used MonkeyCode, an open-source project with free model access and a free server option, as a cheap place to reproduce mixed frames.

The UI treated every SSE chunk as visible text, and it treated the absence of text as still thinking. When the model streamed a tool call first, there was no content string to render, so the spinner never yielded. The composer stayed disabled, Retry never appeared, and VoiceOver eventually narrated punctuation from the tool arguments.

Here is the failure sequence I actually watched, in order:

I submitted from the textarea with Enter, not with a pointer.
Focus moved to Stop, which is the right first move for generation.
No tokens appeared, and the polite live region announced nothing useful.
SSE frames kept arriving with tool_calls deltas and no usable content.
After the tool payload finished, the stream sent a closer without a text-only path.
My reducer left phase: "streaming" in place, so recovery controls stayed unreachable.

Draw the state table before you restyle the spinner

I should have drawn this table before shipping another animated dot. Do you keep an explicit chat phase, or do you encode it as booleans that fight each other?

Phase	Composer	Stop	Live region	Focus
`idle`	enabled	hidden	silent	textarea
`streaming-text`	disabled	visible	throttled writing status	Stop
`streaming-tool`	disabled	visible	named tool work, once	Stop
`error`	enabled	hidden	error plus recovery	Retry
`complete`	enabled	hidden	answer ready	textarea

The bug lived in the missing streaming-tool row. Two booleans cannot represent that row, and they will lie to assistive technology every time a tool frame arrives first.

idle --> streaming-tool --> streaming-text --> complete
              \                    \
               +----> error <------+

If your diagram has no tool lane, the spinner is already a liar. Can a keyboard user tell work from a hang without staring at DevTools?

Reproduce the stream without guessing a model name

You do not need a branded dashboard to debug this class of failure. Spin a tiny SSE server that emits a tool-call delta, then a short content delta, then a done frame. I keep this as a single Node file so the UI cannot blame CORS theater.

node tool-stream-server.mjs
# expected: tool stream on http://127.0.0.1:8787/stream

// tool-stream-server.mjs
import http from "node:http";

const frames = [
  "data: {\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"name\":\"lookup\"}}]}}]}\n\n",
  "data: {\"choices\":[{\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"q\\\":\\\"home\\\"}\"}}]}}]}\n\n",
  "data: {\"choices\":[{\"delta\":{\"content\":\"Found two headings.\"}}]}\n\n",
  "data: [DONE]\n\n"
];

http.createServer((req, res) => {
  if (req.url !== "/stream") {
    res.writeHead(404);
    res.end();
    return;
  }

  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    "Access-Control-Allow-Origin": "*"
  });

  let i = 0;
  const timer = setInterval(() => {
    if (i >= frames.length) {
      clearInterval(timer);
      res.end();
      return;
    }
    res.write(frames[i++]);
  }, 400);
}).listen(8787, () => {
  console.log("tool stream on http://127.0.0.1:8787/stream");
});

Point the chat client at that URL and submit from the keyboard only. Does the composer unlock after the last frame, or does Stop remain the only tab stop in the pane?

If you would rather not run a local process, MonkeyCode's free server option is a convenient host for the same fixture. I am not attaching quotas, model names, or uptime promises, because those change and I will not invent them.

Read the wire before you blame React

Open DevTools, filter EventStream, and dump each parsed object on its own line. Ask one rude question of every frame: is this text, a tool, an error, or a closer? My original parser looked like the next snippet, and it is the entire bug in a dozen lines.

function reduceNaive(state, frame) {
  if (frame === "[DONE]") {
    return { ...state, phase: "complete" };
  }

  const delta = frame.choices?.[0]?.delta ?? {};
  if (delta.content) {
    return {
      ...state,
      phase: "streaming",
      text: state.text + delta.content
    };
  }

  return state; // tool_calls and empty strings both vanish here
}

See the trap? if (delta.content) is false for a missing field, for null, and for an empty string. Tool-only frames return the previous state, so phase never moves. A later [DONE] can still fire, unless your reader drops keep-alives and then misses the closer. I had both defects in one sitting. Charming, right?

Log a typed event instead of concatenating whatever JSON arrived:

function classify(frame) {
  if (frame === "[DONE]") return { type: "done" };

  const delta = frame.choices?.[0]?.delta ?? {};
  if (delta.tool_calls?.length) return { type: "tool", delta };
  if (typeof delta.content === "string") return { type: "text", delta };
  if (frame.error) return { type: "error", error: frame.error };
  return { type: "ignore" };
}

That typeof check is the reusable technique. Empty text chunks can advance a writing phase without dumping a blank paragraph. Tool chunks can change phase without ever touching the transcript. Errors stop borrowing the spinner that hid them yesterday.

Put the phases in a reducer you can unit test

Booleans like isLoading and hasError collide as soon as a tool call arrives during retry. I now keep an explicit phase union and one transition function. This is the artifact I wish I had pasted into the review, instead of another CSS pulse.

type Phase =
  | "idle"
  | "streaming-text"
  | "streaming-tool"
  | "error"
  | "complete";

type ChatState = {
  phase: Phase;
  text: string;
  toolName: string | null;
  error: string | null;
};

function reduce(state: ChatState, event: ReturnType<typeof classify>): ChatState {
  switch (event.type) {
    case "tool": {
      const name = event.delta.tool_calls[0]?.function?.name ?? state.toolName;
      return { ...state, phase: "streaming-tool", toolName: name, error: null };
    }
    case "text":
      return {
        ...state,
        phase: "streaming-text",
        text: state.text + event.delta.content,
        error: null
      };
    case "error":
      return {
        ...state,
        phase: "error",
        error: event.error.message ?? "Stream failed"
      };
    case "done":
      if (state.phase === "error") return state;
      return { ...state, phase: "complete", toolName: null };
    default:
      return state;
  }
}

Notice done does not keep the composer disabled after tool work. Notice tool frames do not append JSON onto text. That second rule is the accessibility fix hiding inside the reducer, not in another aria-* attribute.

Wire abort to the same phase enum, or Stop becomes a decorative button:

let abort = null;

async function startStream(prompt) {
  abort = new AbortController();
  const res = await fetch("http://127.0.0.1:8787/stream", {
    method: "POST",
    body: JSON.stringify({ prompt }),
    signal: abort.signal
  });
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  // parse SSE lines, then reduce(classify(frame))
}

function stopStream() {
  abort?.abort();
}

If Stop does not call abort(), you only changed the label. Keyboard users will notice first, because they are already parked on that control.

Announce work, do not narrate punctuation

Why did VoiceOver say a curly brace? I bound aria-live="polite" to the raw token buffer, including tool arguments. Those arguments are punctuation-heavy JSON, and a polite region will cheerfully read {, then ", then q. Sighted users still get a spinner story. People using the virtual cursor get a ransom note.

Use a dedicated status node, and throttle it to phase changes. Keep the transcript as ordinary document text, not a live region for every delta.

<div id="status" role="status" aria-live="polite" aria-atomic="true"></div>
<div id="transcript" aria-live="off"></div>
<label for="composer">Message</label>
<textarea id="composer"></textarea>
<button type="button" id="stop">Stop generating</button>
<button type="button" id="retry" hidden>Retry</button>

function statusFor(state) {
  switch (state.phase) {
    case "streaming-tool":
      return `Working on ${state.toolName ?? "a tool"}. Stop generating is available.`;
    case "streaming-text":
      return "Writing a reply. Stop generating is available.";
    case "error":
      return `${state.error}. Retry is available.`;
    case "complete":
      return "Answer ready.";
    default:
      return "";
  }
}

Update #status when phase changes, not when another argument character arrives. Append visible prose to #transcript and let people read it in document order. Have you tested that with the virtual cursor, or only with the spinner in a large Chromium window?

Keep Stop mounted, then give the keyboard a way out

A tool-call stream is still a cancelable generation. Hide Stop too early and you trap people in a disabled textarea. Leave Stop mounted after complete and you offer a control that does nothing. I now toggle from the same phase enum, including focus.

function renderControls(state) {
  const streaming =
    state.phase === "streaming-text" || state.phase === "streaming-tool";

  stopButton.hidden = !streaming;
  composer.disabled = streaming;
  retryButton.hidden = state.phase !== "error";

  if (streaming) stopButton.focus();
  if (state.phase === "error") retryButton.focus();
  if (state.phase === "complete") composer.focus();
}

Pointer users will click Stop. Keyboard users need the same abort without a hover target. Screen reader users need the status text to mention that Stop exists, because a newly shown button is easy to miss during a quiet tool phase.

Expected UI states, if you are keeping a checklist beside the fixture:

streaming-tool: composer disabled, Stop visible, status names the tool, no JSON in the transcript.
streaming-text: same controls, transcript grows, status does not repeat every word.
error: composer enabled, Retry focused, status speaks the failure once.
complete: composer focused, Stop gone, status says the answer is ready.

Environment QA matrix

Please reproduce the exact transition, not a happy-path screenshot. I care about this sequence: idle to streaming-tool to streaming-text to complete. Force the fixture server above, then fail the transition on purpose.

Environment	Transition to fail	Pass if
NVDA + Firefox, Windows	first tool frame	status announces once, no JSON spelling
VoiceOver + Safari, macOS	tool work in progress	Stop remains a tab stop, composer stays disabled
VoiceOver + iOS Safari	`complete` after tool then text	focus returns to composer, Stop is gone
Keyboard only, Chromium	Enter submit, Escape abort	Retry is reachable after a thrown error

This is a plan, not a scorecard from a lab I did not run. If your production stream never emits tool calls, the matrix will stay green and still miss production. Point the client at the fixture until the first non-text frame misbehaves in public.

What this does not fix, and who should skip it

This reducer will not rescue a server that closes the socket without a closer frame. It will not sanitize tool arguments before you execute them on behalf of a user. It will not replace a broader design critique of agent chrome, and extra ARIA will not make an inaccessible transcript semantic.

Skip this approach if you only render fully buffered answers after done. Skip it if the product forbids tool calls and never will. Skip it if you cannot abort the fetch, because a Stop button without AbortController is theater.

Free endpoints are useful for this class of bug because mixed frames become cheap to capture. They are the wrong place to pretend you measured latency, quota headroom, or hardware. I will not quote allotments I cannot verify on the day you read this.

If you want a low-friction box for the fixture, MonkeyCode's free model access and free server option are there to try. Bring the state table with you, and watch the first non-text frame like a hawk.

The Free Server Saw My API Key: A Client-Side Redaction Layer for AI Prompts

babycat — Fri, 04 Sep 2026 11:57:58 +0000

Last week I pasted a code snippet into a chat widget backed by MonkeyCode's free server, and the snippet contained a hardcoded API key. The response was helpful, the stream rendered smoothly, and then it hit me: that key had just traveled through a server I don't control. Free tiers are great for experiments, but they're also a reminder that someone else is reading your prompts.

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

The fix isn't to avoid free servers. It's to assume they're transparent and build a redaction layer in the browser.

The data flow you forgot about

When you type a prompt, it goes through at least three hops: your browser, the API gateway, and the model provider. On a free server, you're not paying with money — you're paying with data. Your prompt may contain:

Hardcoded API keys and secrets
Internal hostnames and IP addresses
Customer emails and personal data
Proprietary code snippets that reveal business logic

The solution is a client-side redaction layer with three steps: identify sensitive patterns, replace them with placeholders before the request leaves the browser, and restore them when the response comes back.

A 40-line redaction layer

Here's the complete implementation. It's intentionally small so you can read every line:

// redaction-layer.ts
export class RedactionLayer {
  private map = new Map<string, string>();
  private counter = 0;

  private patterns: RegExp[] = [
    /sk-[A-Za-z0-9_-]{16,}/g,                    // OpenAI-style API keys
    /AKIA[0-9A-Z]{16}/g,                          // AWS access key IDs
    /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----\s*-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g,
    /[\w.+-]+@[\w-]+\.[\w.-]+/g,                  // email addresses
    /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,               // IPv4 addresses
    /(?:https?:\/\/)?[\w-]+\.(?:corp|internal|local)(?:\/\d+)?/g,  // internal hostnames
  ];

  redact(text: string): { safe: string; count: number } {
    const combined = new RegExp(
      this.patterns.map((p) => p.source).join("|"),
      "g"
    );

    let count = 0;
    const safe = text.replace(combined, (match) => {
      count++;
      const placeholder = `⟦REDACTED_${this.counter++}⟧`;
      this.map.set(placeholder, match);
      return placeholder;
    });

    return { safe, count };
  }

  restore(text: string): string {
    return text.replace(/⟦REDACTED_\d+⟧/g, (ph) => this.map.get(ph) ?? ph);
  }

  clear(): void {
    this.map.clear();
    this.counter = 0;
  }
}

The redact method combines all patterns into one regex and replaces every match with a unique placeholder. The restore method reverses the operation. The map holds the placeholder-to-original mapping in memory.

Wiring it into a streaming client

Here's how the layer plugs into an existing chat flow:

const layer = new RedactionLayer();

async function sendChat(prompt: string) {
  const { safe, count } = layer.redact(prompt);

  if (count > 0) {
    statusRegion.textContent =
      `${count} sensitive item${count > 1 ? "s" : ""} redacted before sending`;
  }

  const res = await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ prompt: safe }),
  });

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let output = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    output += layer.restore(decoder.decode(value, { stream: true }));
    render(output);
  }
}

Notice what's happening: the prompt is redacted before fetch is called, and every chunk is restored before it's rendered. The model never sees the original secrets, and the user never sees the placeholders.

To restore or not to restore

This is the key design decision. There are three strategies:

Strategy	What happens	Best for
Always restore	Every placeholder is replaced when rendering	Simple, but the model may echo placeholders
Never restore	Placeholders stay visible	Maximum safety, but confusing output
Restore on demand	User clicks "show original" to reveal	Privacy with user control

I recommend restore-on-demand. The default view shows placeholders, and a button labeled "Show original values" reveals them. This gives the user agency over their data.

Tell the user what you redacted

Redaction is a state change, and state changes need to be announced. Use a role="status" region, not alert():

<div role="status" aria-live="polite" id="status-region"></div>

When the layer redacts something, set the text content of that region. Screen reader users will hear "3 sensitive items redacted before sending" without losing focus. Also provide a way to inspect what was redacted — a simple expandable list of original values — so users can verify the layer didn't miss anything or over-redact.

When redaction makes things worse

Redaction is a heuristic, and heuristics fail. Here are the failure modes I've hit:

Regex misses context. A variable named const secret = "abc123" — the regex catches abc123 only if it matches a pattern. It won't catch a customer name or a project codename.
Placeholders change token semantics. The model sees ⟦REDACTED_0⟧ and doesn't know it's an API key. If you're asking "is this key hardcoded?", the answer will be useless.
The mapping is memory-only. Refresh the page and the placeholders become permanent. If you persist chat history, you need to persist the mapping too.
Redaction can break structured data. If you paste a JSON blob with a "password" field, the regex might replace the value but leave the key intact, producing invalid JSON.

Who should skip this

Don't use a redaction layer if:

Your task requires the model to analyze the sensitive data itself, like a security audit of your own code.
You need end-to-end encryption; redaction is not encryption, it's masking.
You're sending highly structured data where regex replacement can corrupt the format.

And if you're on a paid plan with a data-processing agreement, the calculus changes — but the habit of assuming your prompts are visible is still a good one.

The 40-line habit

Next time you paste a code snippet into an AI chat, ask yourself: is there anything in here I wouldn't want a stranger to read? If the answer is yes, spend 40 lines on a redaction layer. MonkeyCode's free server is a convenient place to practice — precisely because it's free, you should assume the data is being read. Build the layer, paste a fake API key, and watch it get redacted before the request leaves the browser. That's a much better feeling than watching it appear in someone else's logs.

MonkeyCode provides free models that can run this workflow.

DEV Community: babycat

Streaming Agents Need a Tool-Call Focus Lock, Not a Toast Over the Composer

The failure was a focus race, not a smarter model

Debugging technique: a focus timeline, not another spinner

Checks I now run on every agent surface

Root cause, in the order I actually found it

What Enter meant in each broken beat

The fix: lock focus, pause the stream chrome, require an explicit answer

Expected UI states

Minimal reproduction

Keyboard and screen-reader regressions I actually care about

Environment notes worth attaching to a bug

Where a free stream host actually helped

Limitations, and who should not copy this

Streaming Chat Needs a Content-Type Guard, Not Infinite aria-busy

What failed, and what this is not

The state table I needed on day one

Symptom to root cause

Decision table for the first header

A typed phase machine, not a boolean

Guard the document type before you parse tokens

Map phases onto the chat document

A local HTML fixture, then a remote header check

Keyboard and screen-reader regressions

Limitations, and who should skip this

What I keep in the pull request

Agent Tool Prompts Need a Blocking Dialog, Not a Chip You Never Tab To

The symptom I actually hit

Put the state table on the wall first

How I debugged it without guessing

Root cause: a toast tried to do a dialog’s job

The broken reproduction

The fix: showModal(), Deny first, proposal retirement

Where a free remote model actually helps this bug

Accessibility notes the dialog does not magically solve

Environment-specific QA matrix

Limitations, and who should not use this

The Stop Button Lied: Debugging a Cancelled Stream That Never Released the Composer

The interaction that actually failed

How I instrumented the failure

Root cause, stacked in three layers

The state table I wish I had drawn first

Expected UI states after the machine exists

The cancel path that restores the composer

Live region rules that keep cancel hearable

Why a mocked timer will not catch this

QA matrix for the exact failed transition

Limitations, and who should not copy this

What I would debug next time, in order

Stream Cancel Needs a Dead Reader, Not a Hidden Spinner

The failure looked like a styling bug

Draw the state table before the spinner

A runnable session object

What the debugger actually showed

The fetch aborted, the reader did not

The composer remount ate focus

The live region never heard cancelled

Wire cancel to both input devices

The QA card I run before I trust cancel

Limitations, and who should not copy this

Streaming Markdown Needs a Settled Document, Not a Live Heading Tree

The interaction that actually broke

Expected UI states

How I isolated it without guessing

Root cause: promoting Markdown before the turn is a document

Typed states, then one settled parse

Minimal reproduction

Why a mocked three-token stream never caught it

Keyboard, cancel, and recovery

Environment-specific QA matrix

Limitations, and who should not copy this blindly

What I would test next

Chat Retry Needs a Retired Turn, Not a Second Stop Button

The failure, as a state table

What the keyboard path actually did

Root cause: retry mounted a new turn without retiring the old one

One AbortController ref for the whole thread

A renderer that equated "not complete" with "stoppable"

Give every turn a terminal status

The retry reducer retires first

The fix: `showModal()`, Deny first, proposal retirement