Streamlit reruns rebuild the chart, so maidr loses all client state

[jooyoungseo]

Streamlit reruns the whole script on any widget interaction, so the embed is torn down and rebuilt from scratch every time. maidr loses everything it holds in the browser: focus position, the current data point, open braille/text panels, and audio state. On use_cdn=False the ~1.9 MB bundle is also re-parsed each time.

For a keyboard-driven, sonification-first interface this is worse than it sounds. A reader partway through navigating a chart who touches any control on the page is returned to the start, with no announcement that it happened.

Mitigations available today (both documented in docs/examples.qmd as part of #459):

• Cache the HTML string rather than the render call — maidr_html() exists for exactly this. Note the cached function needs an explicit hashable key alongside the underscore-prefixed figure, or the cache key is constant and the first chart is returned forever.
• Avoid frequently-rerunning st.fragment around the chart.

Neither restores client state; they only avoid rebuilding the string.

A real fix needs a bidirectional component that updates in place instead of being replaced — and that is blocked. Streamlit's own app binds r, c and esc at the document level, exempting only form fields, and maidr binds all three. The iframe is currently what keeps maidr's keybindings working at all, so moving to an embedding that renders into the Streamlit page would trade state preservation for the keyboard interface. See the module docstring in maidr/widget/streamlit.py for why components v2 is not the target.

Filing this as a known ceiling rather than a plan. Worth revisiting if Streamlit ever offers a documented opt-out from its document-level key handling.

Follow-up from #459.

[jooyoungseo]

The iframe justification, measured

This issue and maidr/widget/streamlit.py's module docstring both assert that Streamlit binds keys at the document level and that the iframe is what keeps maidr's keyboard interface working. That came from reading Streamlit's source, not from measuring. Browser testing turns out to be available in my environment after all (see #457), so here is the measurement, against Streamlit 1.61.1 in Chromium 141.

The app carries a st.session_state run counter, so "the script ran again" is unambiguous — an innerText diff would not move on an otherwise identical rerun.

On the Streamlit page, nothing focused:

key	RUNCOUNT	reran
r	1 → 2	yes
c	2 → 2	no
Escape	2 → 2	no

With the text input focused: r and c land in the field (input value: 'rc'), no rerun. The form-field exemption is real.

With focus inside the chart's iframe:

key	chart announces	Streamlit reran
ArrowRight	a, 1	no
ArrowRight	b, 2	no
b	Braille is on	no
r	Review is on	no

That last row is the whole argument, and it is now evidence rather than inference: the same keystroke that reruns the app from the page reaches maidr's review mode from inside the frame, and the app does not rerun. Both bindings exist because the frame separates them.

Checked deliberately that the chart received the key rather than the frame swallowing it — "no rerun" would be equally true of a dead frame, and would prove nothing. The announcements are what rule that out.

One correction to my own wording

The docstring and this issue say Streamlit binds "r, c and esc". I can only show r. Neither c nor Escape produced a rerun in this measurement.

That does not prove they are unbound — they may drive something I did not measure, such as a cache dialog or dismissing an overlay, and either could still collide with maidr's use of them. But I asserted three keys and have evidence for one, so the wording overstates what is known. Worth narrowing to r unless someone measures the other two, since the conclusion does not depend on them: one document-level collision is enough to make the frame load-bearing.

The ceiling this issue describes is unchanged, and so is the reason it is filed as a ceiling rather than a plan.

---

Generated by Claude Code

[jooyoungseo]

This issue's "blocked" rests on one claim, and that claim did not survive measurement.

A real fix needs a bidirectional component that updates in place instead of being replaced — and that is blocked. Streamlit's own app binds r, c and esc at the document level, exempting only form fields, and maidr binds all three.

Reproduced against Streamlit 1.61.1 in Chromium (full reproduction and controls on #461). Two corrections:

• esc is not bound on a bare page, and c does not rerun — it opens a dialog. Only r reruns. The exemption rule is confirmed.

• A component can take the keys back. Suppressing keydown and keyup at window capture works — either alone does not — and it can be scoped so it costs the app nothing:

  focus in the chart, r	no rerun — maidr keeps its key
  focus elsewhere, r	reran — the user keeps Streamlit's shortcut
  typing record charts into st.text_input	intact

So this is not blocked; it has a cost. The cost is that the defence is a window capture hook every component must reinvent, sanctioned by no documentation and liable to break on a Streamlit release — which is still worth asking upstream to replace with a supported opt-out (#461), but is a maintenance burden rather than an impossibility.

That reopens the question this issue closed off. It does not answer it: a no-iframe Streamlit embedding would also inherit the host-CSS problem measured on #457, where *:focus { outline: none !important } strips the chart's focus ring — a WCAG 2.4.7 failure that the iframe prevents by construction. That cost is unchanged and is the one that actually decides the embedding.

Suggest retitling the ceiling: the blocker is CSS isolation, not key conflicts. Leaving the edit to a maintainer rather than rewriting someone else's issue body.

Nothing here was tested against a real no-iframe maidr embed — the suppression was measured on a stand-in <div>, Chromium only, one Streamlit version.

---

Generated by Claude Code