V2: paragraphs with an inline br/tab/footnote reference cost ~2x per keystroke, and fast typing queues up

[Nathaniel-260]

What happened?

Typing into a paragraph that contains an inline <w:br/>, a <w:tab/> or a <w:footnoteReference/> is noticeably slower per keystroke than typing into a plain paragraph of the same document — roughly twice the delay between the key press and the character appearing. The number of formatting runs does not matter (paragraphs with 20 and 60 runs but none of those elements behave like a single-run paragraph), and neither do w:jc="distribute", a run with large w:spacing, or a character style on the first word.

Because each keystroke is handled on its own — every key produces its own render, and keys that queue up while one is being rendered are not merged — the extra cost accumulates when typing fast. In a plain Chrome or Edge tab the editor still kept up with ~10 keys/s on the real document; inside our embedding (WebView2 in a Flutter desktop app, on a 2-core laptop) the same paragraphs fell behind and the last characters of a fast burst appeared seconds late, while plain paragraphs in the same document kept up. The host adds its own overhead, but the per-paragraph difference is the same in all three environments.

The real document is a rabbinic-style Hebrew text: every body paragraph opens with a short line, a <w:br/>, a wide-spaced space, then the body, and ends with a <w:tab/> — so every body paragraph is on the slow path, and the sub-headings (single run, no inline elements) are not. That is why it felt like "the two-column section is slow" until the paragraphs were compared one by one.

Expected: the per-keystroke cost of a paragraph should not depend on an inline line break, tab or footnote reference; or, failing that, queued keystrokes should be coalesced so the delay does not grow with typing speed.

Steps to reproduce

The documents are generated (synthetic text, nothing customer-specific) by a self-contained Node script: https://gist.github.com/Nathaniel-260/8e9be315500f89e6ae7b32eb7c89d4e4

node repro-typing-lag-docx.mjs bisect typing-bisect.docx
node repro-typing-lag-docx.mjs full   typing-full.docx

1. Open typing-bisect.docx (one page, nine labelled paragraphs A–I; same text and length, eight runs each, one extra inline feature per paragraph).
2. Click into A (plain) and type a quick burst of ~20 characters. Then do the same in C (trailing <w:tab/>), D (<w:br/> after the first run) and G (footnote reference).
3. C, D and G respond visibly slower per key than A; B (jc=distribute), E (wide-spacing run) and F (character style) behave like A. H (all features) and I (all features, single run) are slow too — so it is the inline elements, not the run count.
4. typing-full.docx has the shape of the real document (heading in a one-column section, then a continuous two-column section with ~45 body paragraphs and footnotes). Typing fast in body paragraph B vs. the one-run sub-heading A makes the difference easy to feel, especially on a slower machine.

The DOM shows the same thing: with the developer tools open, each keystroke in a slow paragraph produces its own DOM update, one at a time, and the caret overlay updates well before the character itself appears.

SuperDoc version

2.12.0 (@superdoc/docx-engine 0.11.0), V2 layout.

Browser

Chrome 152 and Edge 152 (Windows 10), and WebView2 (Edg/152) inside a Flutter desktop host.

Additional context

Found while diagnosing typing latency in the Otzaria Word plugin (open source, SuperDoc-based). We can share our per-keystroke measurements and traces privately with the SuperDoc team on request; they are deliberately not posted here.

[Nathaniel-260]

Correction on the host part of the report above. The observation that inside our embedding (WebView2 in a Flutter desktop app) "the last characters of a fast burst appeared seconds late" was measured while another session on the same 2-core laptop was running a full Flutter build and a test suite. Re-measured with the machine idle — same document, same paragraphs, same build — the editor inside our host keeps up at ~10 keys/s in the slow paragraphs too: the last character of a 20-key burst appears a fraction of a second after the last key, in the same range as Chrome and Edge on the same machine at the same time. So the host does not add meaningful per-key overhead; please disregard that sentence.

What stands, and what the issue is about: the per-keystroke cost of a paragraph roughly doubles when it contains an inline <w:br/>, <w:tab/> or footnote reference (independent of the run count and of jc, spacing or character styles), and queued keystrokes are not coalesced — which is what turns any moment of CPU starvation into a backlog that grows with typing speed rather than a single delayed character. The generator and the steps to reproduce are unchanged.

[jelkes1]

Thanks for the detailed repro, this is helpful.

It looks like this was tested on 2.12.0. Since then we’ve shipped a meaningful set of V2 performance improvements, including work specifically around localized editing and footnote-heavy documents.

On our 300-page test document with heavy footnote usage, the 50-character typing burst improved from 8.05s in an earlier build to 3.82s in 2.12.0-next.9, which is close to the 3.75s scripted input time. The following keystroke improved from 194ms to 46ms. We also removed a delayed footnote-renumbering pass so updated footnote numbers now appear with the edit.

Could you rerun the same br/tab/footnoteReference repro on the latest version of SuperDoc, 2.13.0-next.11, and let us know how it compares? That will help us understand how much of what you’re seeing has already improved and what, if anything, remains specific to those inline elements.

cc @tupizz

[Nathaniel-260]

Thank you so much — to the whole team, honestly. The pace and the care in the replies here are amazing, and it's a pleasure to report to people who actually dig in.

What I did. I rebuilt our plugin against superdoc@2.13.0-next.11 (it pulls @superdoc/docx-engine 0.12.0-next.10) in a separate checkout, and ran the exact same repro — the two generated documents from the gist, the same typing harness, real Chrome 152, same machine — alternating between 2.12.0 and next.11 with the machine otherwise idle (I check for stray CPU load before and after every run now, after last time).

What changed. Plain paragraphs (no inline w:br / w:tab / footnote reference) did get a bit faster in next.11 — noticeable in the sub-heading of typing-full.docx. Nice.

What remains. Paragraphs that contain an inline w:br, w:tab or a footnote reference behave exactly as they did in 2.12.0: the per-keystroke cost is the same as before, so the gap to plain paragraphs in the same document is unchanged (if anything slightly wider, since only the plain ones improved). The behaviour is also the same in kind: every keystroke still gets its own render and keystrokes that queue up while one is rendering are not merged. In typing-bisect.docx that means C, D, G, H and I still stand out against A, B, E and F, and in typing-full.docx a fast burst in body paragraph B still ends noticeably after the last key while the same burst in sub-heading A ends with it. So the footnote-renumbering and large-document work you describe doesn't seem to touch this path — our documents are small (one and six pages), the effect is per paragraph, not per document size, and it's typing inside the body text, not editing the footnotes. On an idle machine both versions keep up with ~10 keys/s; the difference only turns into a visible backlog when CPU is scarce — which, on my hardware, is most of the time.

And a small personal note: I hope I'm not driving you crazy with the number of issues I've opened. I have a few more in the pipeline, but unfortunately my computer is a bit of a clunker — a 2017 Dell Latitude 7280 with a 2015-era Intel Core i7-6600U (2 cores / 4 threads), Intel HD 520 graphics, 16 GB RAM, Windows 10 — so a proper test run for a single issue can tie up my machine for a couple of hours, and as a student that's what I have for now. Once some of the open ones are resolved I'll continue with the rest. Thanks again.

[jelkes1]

Not driving us crazy at all. Quite the opposite. We love this kind of feedback.

Our goal is to make SuperDoc the best DOCX editor for developers, and every issue you share helps us get closer to that. The care you’re putting into isolating the behavior and giving us reproducible cases makes these especially useful.

This retest is also super helpful. It gives us a much clearer signal that the remaining cost is specific to the inline-element path rather than the broader footnote and large-document work we’ve already done.

Next step on our side is to reproduce and profile this specific w:br / w:tab / footnote-reference path and determine the right fix. We’ll keep the issue updated with what we find and the path forward.

Please keep them coming at whatever pace works for you. And no need to apologize for the hardware. We want SuperDoc to perform well on real developer machines, not only the newest ones.

Thanks again for putting this much effort into helping us improve it.

[linear-code]

IT-1592

[Nathaniel-260]

That is really good to hear, thank you. Knowing the inline-element path is now yours to profile is exactly what I was hoping for.

One honest note about pace, since you kindly said "at whatever pace works for you": each of these cycles costs me the machine for a couple of hours. Building a second copy of our plugin against the version you ask about, running the bursts alternately against the current one, and keeping everything else off the two cores means I cannot really use the laptop for anything else while it runs, and it is the same machine I study on. So the ones still in my pipeline will arrive slowly, in the gaps between other things. Not for lack of interest.

Which brings me to something that might save you a step. Would you like me to send you, privately by email, the actual document I have been testing in? The generator in the gist reproduces the shape faithfully, but the real file is a Hebrew rabbinic-style text I am writing: continuous two-column section, footnotes, and every body paragraph built as a short opening line, a <w:br/>, a wide-spaced space, the body, and a trailing <w:tab/>. Roughly 45 such paragraphs across six pages. If profiling the real thing is more useful than the synthetic one, it is yours. It is unpublished writing of mine, so I would rather not attach it in a public thread, but I am glad to send it privately.

I can include my per-keystroke measurements and the traces from these runs in the same email, if those help you compare against your own profiling. Just tell me where to send it.

[jelkes1]

Yes, absolutely. The real document plus the per-keystroke measurements and traces would be extremely helpful.

Please send them to me at josh@superdoc.dev and Caio at caio@superdoc.dev. We’ll keep the document private and use it only to help reproduce and profile the issue.

And no rush at all on the other reports. The work you’ve already put into these has been incredibly useful, and we’d much rather you send things when it works for you than tie up the machine you need for school.

Thanks again. Having the real fixture should help us get closer to the underlying path much faster.