MarkdownDocument: typed source reads after a pause off the main thread; texts past 2 MiB are never read

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -13,7 +13,7 @@ Ely GPUI Component. A component library for GPUI, in light and dark.
 - Web views: `wry` 0.57 (Apache-2.0 OR MIT, default features off, macOS only) lays a child WKWebView over the window.
 - Terminal: `alacritty_terminal` 0.26 (Apache-2.0, default features off, native only) for the grid, its parser and the pseudo-terminal; `futures` carries its events. `vte` 0.15 (Apache-2.0 OR MIT), the parser it re-exports, reads `AnsiText`'s codes alone, so colored output builds for wasm32.
 - Diffs: `similar` 3.2 (Apache-2.0) for line and word diffs and three-way merges; its `unicode` feature splits words at punctuation.
-- Markdown: `markdown` 1.0.0 (markdown-rs, MIT) reads GitHub's flavor and math into a syntax tree with byte positions for `MarkdownRenderer`, `MarkdownEditor`, the highlights, block ranges and outline. `MarkdownRenderer` draws display math through `typography::Latex`, a ```` ```mermaid ```` block through `documents::Diagram`, and pictures from the owner's folder (`base`) or `data:` addresses (`base64` 0.22, MIT OR Apache-2.0); web pictures stay unloaded. Inline math shows as TeX: gpui text carries no inline pictures. `MarkdownDocument` holds a whole file in one `CodeEditor` (text and undo, colored by `CodeEditor::highlighter` with `markdown_highlights`): visual draws the file's top-level blocks in a gpui `list`, a pressed block opening as its source in a `TextInput` whose typing is the document's text at once and whose write-back is one undo step; source is the editor; preview draws without presses. Texts up to 128 KiB are read at once, longer ones on the background executor, and a new read keeps the list's blocks alike at both ends. One caret serves every mode: the editor's selection, which a written-back block moves; `set_caret` and `set_top_line` set caret and view apart; a top line asked (numbered, so a late frame callback finishes only its own ask; new text places it again, clamped to the text as it then is) waits for the read, lands on its block, then a frame later at its share of the block's height; `reveal` is such an ask with the caret at its line; a switch between source and the list keeps the top line, one between visual and preview keeps the list's scroll as it is. A block opens only when the read is of the text as it is now. A pressed block keeps its identity across the write-back of the one before it. Blocks are Tab stops that Enter or Space opens; preview takes no presses, undo or redo. `CodeEditor` keeps at most 64 MiB of undo and redo text, dropping the oldest undo and then the farthest redo after every record, composition, undo and redo. `BlockData::from_markdown` and its export still read with `pulldown-cmark` 0.13 (MIT, default features off); it adds GitHub's alerts, a callout's form, and reads each field's inline Markdown from the source by offset, as written.
+- Markdown: `markdown` 1.0.0 (markdown-rs, MIT) reads GitHub's flavor and math into a syntax tree with byte positions for `MarkdownRenderer`, `MarkdownEditor`, the highlights, block ranges and outline. `MarkdownRenderer` draws display math through `typography::Latex`, a ```` ```mermaid ```` block through `documents::Diagram`, and pictures from the owner's folder (`base`) or `data:` addresses (`base64` 0.22, MIT OR Apache-2.0); web pictures stay unloaded. Inline math shows as TeX: gpui text carries no inline pictures. `MarkdownDocument` holds a whole file in one `CodeEditor` (text and undo, colored by `CodeEditor::highlighter` with `markdown_highlights`): visual draws the file's top-level blocks in a gpui `list`, a pressed block opening as its source in a `TextInput` whose typing is the document's text at once and whose write-back is one undo step; source is the editor; preview draws without presses. A written-back block, a mode switch or a new text is read at once up to 128 KiB, longer ones on the background executor; typing in source or split reads 300 ms after the last key, off the main thread (markdown-rs grows with the square of a paragraph's lines: 40,000 lines take 0.9 s). Texts past `LARGEST_READ` (2 MiB) are never read: no blocks, no outline. A new read keeps the list's blocks alike at both ends. One caret serves every mode: the editor's selection, which a written-back block moves; `set_caret` and `set_top_line` set caret and view apart; a top line asked (numbered, so a late frame callback finishes only its own ask; new text places it again, clamped to the text as it then is) waits for the read, lands on its block, then a frame later at its share of the block's height; `reveal` is such an ask with the caret at its line; a switch between source and the list keeps the top line, one between visual and preview keeps the list's scroll as it is. A block opens only when the read is of the text as it is now. A pressed block keeps its identity across the write-back of the one before it. Blocks are Tab stops that Enter or Space opens; preview takes no presses, undo or redo. `CodeEditor` keeps at most 64 MiB of undo and redo text, dropping the oldest undo and then the farthest redo after every record, composition, undo and redo. `BlockData::from_markdown` and its export still read with `pulldown-cmark` 0.13 (MIT, default features off); it adds GitHub's alerts, a callout's form, and reads each field's inline Markdown from the source by offset, as written.
 - Pictures: `image` 0.25 (MIT OR Apache-2.0), the crate gpui decodes with, default features off; it turns decoded frames and rims map tiles.
 - Math and diagrams: RaTeX 0.1.14 (`ratex-parser`, `ratex-layout`, `ratex-svg` with `embed-fonts`, `ratex-types`; MIT, KaTeX's fonts OFL) typesets `Latex` to SVG with outlined glyphs; `mermaid-rs-renderer` 0.3.1 (MIT, default features off) draws `Diagram`. Both go through gpui's `SvgRenderer` at the window's scale, loaded as gpui assets off the main thread; `usvg` 0.46, gpui's own, reads a diagram's size. A RaTeX or Mermaid panic on parsed input becomes the element's error. Each element holds its picture through `primitives::held`: a new source, or the element leaving the window, removes the old asset from gpui's cache and drops its image from the atlas after the frame.
 - Maps: Natural Earth's 110m countries (public domain). `assets/maps/countries.geojson`, trimmed by `scripts/countries.py` to an ISO code, a name and positions to 0.01°, backs `maps::WorldMap`; the gallery's tiles are cut from the same file, z0 to z3, by `scripts/tiles.py` with Pillow.

src/documents/document/edit.rs

@@ -36,7 +36,7 @@ impl MarkdownDocument {
         };
         let written = self.commit(cx);
         if written.is_some() {
-            self.reparse(cx);
+            self.reparse(true, cx);
         }
         if !self.read_now(cx) {
             return log::warn!("markdown document: pressed while the text is read again");

src/documents/document/mod.rs

@@ -7,7 +7,7 @@ mod visual;
 
 pub(crate) use visual::bind_keys;
 
-use std::{ops::Range, path::Path, rc::Rc, sync::Arc};
+use std::{ops::Range, path::Path, rc::Rc, sync::Arc, time::Duration};
 
 use gpui::{
     App, AppContext as _, Context, Entity, EventEmitter, FocusHandle, Focusable, ListAlignment,
@@ -26,6 +26,12 @@ use crate::{
 /// Texts this long parse at once; longer ones elsewhere.
 const AT_ONCE: usize = 128 << 10;
 
+/// Longer texts are never read: source alone.
+pub const LARGEST_READ: usize = 2 << 20;
+
+/// Typing waits this long for a pause before a read.
+const PAUSE: Duration = Duration::from_millis(300);
+
 /// What the document tells its owner.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum DocumentEvent {
@@ -121,7 +127,7 @@ impl MarkdownDocument {
             on_link: None,
             _subscriptions: subscriptions,
         };
-        document.reparse(cx);
+        document.reparse(true, cx);
         document
     }
 
@@ -148,6 +154,9 @@ impl MarkdownDocument {
     pub fn set_mode(&mut self, mode: MarkdownMode, window: &mut Window, cx: &mut Context<Self>) {
         self.commit(cx);
         log::info!("markdown document: {:?} to {mode:?}", self.mode);
+        if !self.read_now(cx) {
+            self.reparse(true, cx);
+        }
         let listed = |mode| matches!(mode, MarkdownMode::Visual | MarkdownMode::Preview);
         // Visual and preview share one list and its scroll.
         let top = (!(listed(self.mode) && listed(mode))).then(|| self.top_line(cx));
@@ -215,17 +224,26 @@ impl MarkdownDocument {
         self.replace_top();
         self.edits += 1;
         cx.emit(DocumentEvent::Changed);
-        self.reparse(cx);
+        // Typed source reads after a pause.
+        let typed = matches!(self.mode, MarkdownMode::Source | MarkdownMode::Split);
+        self.reparse(!typed, cx);
     }
 
-    /// Reads the text again, at once when short.
-    fn reparse(&mut self, cx: &mut Context<Self>) {
+    /// Reads the text: short ones now, else after a pause.
+    fn reparse(&mut self, now: bool, cx: &mut Context<Self>) {
         let (text, edits) = (self.editor.read(cx).text().to_string(), self.edits);
-        if text.len() <= AT_ONCE {
+        if text.len() > LARGEST_READ {
+            self._parsing = None;
+            return log::info!("markdown document: {} bytes, too long to read", text.len());
+        }
+        if now && text.len() <= AT_ONCE {
             self._parsing = None;
             return self.adopt(parsed(&text), edits, cx);
         }
         self._parsing = Some(cx.spawn(async move |document, cx| {
+            if !now {
+                cx.background_executor().timer(PAUSE).await;
+            }
             let read = cx.background_spawn(async move { parsed(&text) }).await;
             document
                 .update(cx, |document, cx| document.adopt(read, edits, cx))

src/documents/document/tests/mod.rs

@@ -366,3 +366,33 @@ fn a_press_after_a_write_back_waits_for_the_long_read(cx: &mut TestAppContext) {
 }
 
 mod place;
+
+#[gpui::test]
+fn typed_source_reads_after_a_pause(cx: &mut TestAppContext) {
+    let (document, cx) = open(TEXT, MarkdownMode::Source, cx);
+    let editor = document.read_with(cx, |document, _| document.editor().clone());
+    editor.update(cx, |editor, cx| editor.edit([(0..0, "x".to_string())], cx));
+    cx.run_until_parked();
+    assert!(
+        !document.read_with(cx, |document, cx| document.read_now(cx)),
+        "no read per key"
+    );
+    cx.executor().advance_clock(super::PAUSE);
+    cx.run_until_parked();
+    assert!(
+        document.read_with(cx, |document, cx| document.read_now(cx)),
+        "read after the pause"
+    );
+}
+
+#[gpui::test]
+fn a_text_past_the_largest_read_is_never_read(cx: &mut TestAppContext) {
+    let long = "a\n".repeat(super::LARGEST_READ / 2 + 1);
+    let (document, cx) = open(&long, MarkdownMode::Source, cx);
+    cx.executor().advance_clock(super::PAUSE);
+    cx.run_until_parked();
+    let (read, outline) = document.read_with(cx, |document, cx| {
+        (document.read_now(cx), document.outline(cx).len())
+    });
+    assert!(!read && outline == 0);
+}

src/documents/mod.rs

@@ -34,7 +34,7 @@ pub use blocks::{Align, BlockData, BlockEditor, BlockEvent, BlockKind, Media};
 pub use contents::outline;
 pub use counts::{ReadingTime, WordCount};
 pub use diagram::Diagram;
-pub use document::{DocumentEvent, DocumentHeading, MarkdownDocument};
+pub use document::{DocumentEvent, DocumentHeading, LARGEST_READ, MarkdownDocument};
 pub use epub::{Chapter, EpubReader};
 pub use format::{Format, format};
 pub(crate) use history::Change;