Skip to main content

text_document/
streaming.rs

1// SPDX-License-Identifier: MPL-2.0
2// SPDX-FileCopyrightText: 2026 FernTech
3
4//! Append-only streaming: the log/console path.
5//!
6//! A view tailing output does two things in a loop — append a line at the end,
7//! and drop the oldest once it is over its scrollback cap. Both are expressible
8//! with the ordinary editing API, and both are O(N) that way: appending one line
9//! to a 10 000-line document costs ~15.9 ms, and evicting 20 lines ~55 ms
10//! (`docs/streaming-baseline.md`). Neither cost is inherent — it comes from
11//! general-purpose machinery that a tail-append does not need:
12//!
13//! * `character_count()` / `cursor_at()` each run `get_document_stats`, which
14//!   materializes every block's text to compute a word count the caller never
15//!   asked for — just to locate the end of the document.
16//! * `insert_block` fetches *every* block entity (via
17//!   `collect_block_ids_recursive` and `get_block_multi`) before it can find
18//!   the insertion point. `insert_text` has an O(log n) rope fast path;
19//!   `insert_block` never received one.
20//! * `delete_text` walks the whole `child_order` refreshing every block's stored
21//!   position, with a rope lookup per block, regardless of how little was
22//!   deleted.
23//!
24//! None of that is needed when the insertion point is, by construction, the end:
25//! the rope already knows where the end is, nothing after it needs shifting, and
26//! no block above it is touched. This module takes that shortcut directly, via
27//! the `rope_helpers` primitives (`rope_append_block` is a rope insert at the
28//! tail plus an O(1) amortized `push_block` — nothing shifts, because appending
29//! at the end shifts nothing).
30//!
31//! # Not undoable — and not an oversight
32//!
33//! **Nothing in this module participates in undo/redo.** An appended or evicted
34//! line cannot be brought back with [`TextDocument::undo`](crate::TextDocument::undo), does not appear on
35//! the undo stack, and does not affect [`TextDocument::can_undo`](crate::TextDocument::can_undo).
36//!
37//! That is deliberate on both counts. A million streamed lines must not become a
38//! million undo entries — the stack is unbounded, so that is a leak, not a
39//! feature. And the alternative escape hatch the rest of the crate uses for
40//! non-undoable work (perform, then `clear_stack`, as `set_plain_text` does)
41//! would throw away the *user's* history every time a line arrived from a
42//! background thread.
43//!
44//! So the entity writes are routed through a private stack of their own, cleared
45//! as they go. Note that passing `None` as the stack id would not have achieved
46//! this: `add_command_to_stack` resolves `None` to stack 0 rather than skipping,
47//! so it is not an opt-out.
48//!
49//! Consequences worth being deliberate about:
50//!
51//! * **The document's own undo stack is untouched.** A user's edits stay
52//!   undoable across any amount of streaming, and undo will never surface or
53//!   swallow a streamed line. This is covered by a test.
54//! * **Streaming is not reversible.** Content that arrived from elsewhere is not
55//!   the user's to undo; if a caller needs to drop it, that is
56//!   [`truncate_front`](TextDocument::truncate_front), not undo.
57//! * **`modified` is still set**, and change events are still emitted, so views
58//!   and dirty-tracking behave normally.
59//!
60//! Mixing streaming with ordinary editing on one document works and is tested
61//! (the rope and the block index stay coherent), but it is not the intended
62//! shape: these are for buffers whose content arrives from elsewhere.
63//!
64//! # All-or-nothing
65//!
66//! Every entry point here is atomic: it either lands completely or leaves the
67//! document exactly as it was. That needs saying because it does not come for
68//! free. These paths hand-maintain four things that must agree — the rope, the
69//! block offset index, the frame's `child_order`, and the document's cached
70//! counts — across several fallible calls, and the unit-of-work layer that
71//! normally guarantees that is precisely what they bypass for speed. Without
72//! care, any early `?` would leave text in the rope that no block owns, or a
73//! block the frame never references, or counts describing a document that no
74//! longer exists — none of which surfaces as an error, only as a document that
75//! quietly disagrees with itself.
76//!
77//! So each operation takes a savepoint first and rolls back on any failure,
78//! including a panic. A savepoint is a whole-store snapshot, but a cheap one:
79//! the rope is persistent and the entity tables are `im::HashMap`s, so it is
80//! pointer copies, not a deep clone.
81//!
82//! Note that a rolled-back append still consumes the entity ids it allocated —
83//! the store's counters are deliberately not rewound — so ids may show gaps.
84//! Nothing depends on them being contiguous.
85//!
86//! # This is still O(N) — know the ceiling before using it
87//!
88//! Measured, appending one line (`docs/streaming-baseline.md`):
89//!
90//! | lines in document | ordinary editing path | this |
91//! |---|---|---|
92//! | 1 000 | 986 µs | 174 µs |
93//! | 10 000 | 28.1 ms | 2.90 ms |
94//!
95//! Roughly 10× cheaper — but 174 µs → 2.90 ms is 16.7× for 10× the document, so
96//! **this is still O(N), not O(1)**. It moves the ceiling; it does not remove it.
97//! Around 10 000 lines an append costs ~2.9 ms (~345 lines/second), which suits
98//! an application's own event log. It does not suit `tail -f` of a large file:
99//! at 100 000 lines the cost extrapolates to ~29 ms per line. Cap the buffer
100//! accordingly, and evict with [`truncate_front`](TextDocument::truncate_front).
101//!
102//! `truncate_front` is barely better than the ordinary path (1.19× at 10 000)
103//! and is *slower* below a few thousand lines, because the ordinary path makes a
104//! single bulk `delete_text` call where this makes one entity removal per evicted
105//! block. It exists for the coherence of the streaming API — appending without
106//! being able to evict is useless — not because it is fast.
107//!
108//! The rope is not the reason. `rope_append_block` is O(log n) as intended; the
109//! residual is the generic entity-update path. `UndoableUpdateUseCase::
110//! execute_multi` fetches the old entity for undo and stashes it on every write,
111//! so each `update_frame` clones the `Frame` — its whole `child_order: Vec<i64>`
112//! included — several times over. Every appended line therefore touches the
113//! entire `child_order`, whatever the rope does.
114//!
115//! Reaching O(1) means `child_order` no longer being an N-element `Vec` cloned
116//! per write. That reshapes a core entity the whole engine and its property tests
117//! depend on, and is deliberately out of scope here.
118
119use std::sync::Arc;
120
121use frontend::block::dtos::CreateBlockDto;
122use frontend::commands::{block_commands, document_commands, frame_commands, undo_redo_commands};
123use frontend::common::types::EntityId;
124use frontend::document::dtos::UpdateDocumentDto;
125use frontend::frame::dtos::UpdateFrameDto;
126
127use crate::document::get_main_frame_id;
128use crate::events::DocumentEvent;
129use crate::inner::TextDocumentInner;
130use crate::{DocumentError, Result, TextDocument};
131
132impl TextDocument {
133    /// Append `text` as a new block at the end, returning the document's new
134    /// block count.
135    ///
136    /// The append half of a streaming buffer. Costs the rope insert and one
137    /// entity write, whatever the buffer already holds — against ~15.9 ms per
138    /// line at 10 000 lines through the ordinary editing path
139    /// (`docs/streaming-baseline.md`).
140    ///
141    /// The returned count is what a scrollback cap is checked against, so a
142    /// caller never needs a separate count call — which matters, because
143    /// [`block_count`](Self::block_count) walks the whole document:
144    ///
145    /// ```ignore
146    /// let count = doc.append_line(line)?;
147    /// if count > CAP {
148    ///     doc.truncate_front(count - CAP)?;
149    /// }
150    /// ```
151    ///
152    /// `text` is taken as a single line: it must not contain `\n`, since a block
153    /// is one line by construction here (embedded newlines would desynchronize
154    /// the rope from the block index). Returns [`DocumentError::InvalidArgument`]
155    /// if it does.
156    ///
157    /// **Not undoable**, by design — see the module docs.
158    pub fn append_line(&self, text: &str) -> Result<usize> {
159        if text.contains('\n') {
160            return Err(DocumentError::InvalidArgument(
161                "append_line takes a single line; text must not contain '\\n'".into(),
162            ));
163        }
164        // After the argument is checked: a refused append leaves a composition shown.
165        let _settled = self.settle_transient_edits();
166
167        let mut inner = self.inner.lock();
168        let frame_id = get_main_frame_id(&inner);
169        if frame_id == 0 {
170            return Err(DocumentError::InvalidArgument(
171                "document has no main frame".into(),
172            ));
173        }
174
175        // Everything below either all lands or none of it does.
176        let atomic = Atomic::begin(&inner)?;
177        let appended = append_one(&mut inner, frame_id, text)?;
178        let new_count = commit_counts(&mut inner, 1, text.chars().count() as i64)?;
179        atomic.commit();
180
181        finish(&mut inner, appended.edit_pos, appended.chars_added, 1);
182
183        inner.queue_event(DocumentEvent::BlockCountChanged(new_count));
184        // A pure tail append: the new element lands at the end of the flow, so
185        // the index is the previous count. Emitted directly rather than through
186        // the generic `check_flow_changed`, which diffs the whole `child_order`
187        // on every edit — O(N) again, to rediscover what is known here.
188        inner.queue_event(DocumentEvent::FlowElementsInserted {
189            flow_index: new_count - 1,
190            count: 1,
191        });
192
193        // Notify `on_change` subscribers, like every other mutation — the poll
194        // path alone would leave callback-based observers (a reactive view) blind
195        // to appends. Dispatch outside the lock: a callback may re-enter.
196        let queued = inner.take_queued_events();
197        drop(inner);
198        crate::inner::dispatch_queued_events(queued);
199        Ok(new_count)
200    }
201
202    /// Append several lines in one go, returning the document's new block count.
203    ///
204    /// Equivalent to [`append_line`](Self::append_line) per line, but pays the
205    /// document-count write and the throwaway-stack clear once for the batch
206    /// rather than per line. A view draining a channel once per frame should
207    /// prefer this.
208    ///
209    /// No line may contain `\n`.
210    ///
211    /// **Not undoable**, by design — see the module docs.
212    pub fn append_lines<I, S>(&self, lines: I) -> Result<usize>
213    where
214        I: IntoIterator<Item = S>,
215        S: AsRef<str>,
216    {
217        let lines: Vec<String> = lines.into_iter().map(|s| s.as_ref().to_owned()).collect();
218        if lines.iter().any(|l| l.contains('\n')) {
219            return Err(DocumentError::InvalidArgument(
220                "append_lines takes single lines; none may contain '\\n'".into(),
221            ));
222        }
223        if lines.is_empty() {
224            let inner = self.inner.lock();
225            return Ok(current_block_count(&inner)? as usize);
226        }
227        // After the arguments are checked: a refused or empty append leaves a composition
228        // shown.
229        let _settled = self.settle_transient_edits();
230
231        let mut inner = self.inner.lock();
232        let frame_id = get_main_frame_id(&inner);
233        if frame_id == 0 {
234            return Err(DocumentError::InvalidArgument(
235                "document has no main frame".into(),
236            ));
237        }
238
239        // The batch is one unit: a line failing halfway would otherwise leave
240        // its predecessors appended with the document's counts never updated,
241        // since those are written once at the end.
242        let atomic = Atomic::begin(&inner)?;
243        let mut edit_pos = None;
244        let mut chars_added = 0usize;
245        for line in &lines {
246            let appended = append_one(&mut inner, frame_id, line)?;
247            // The batch's edit starts where its first line did.
248            edit_pos.get_or_insert(appended.edit_pos);
249            chars_added += appended.chars_added;
250        }
251        let edit_pos = edit_pos.unwrap_or(0);
252
253        let chars: i64 = lines.iter().map(|l| l.chars().count() as i64).sum();
254        let new_count = commit_counts(&mut inner, lines.len() as i64, chars)?;
255        atomic.commit();
256
257        finish(&mut inner, edit_pos, chars_added, lines.len());
258
259        inner.queue_event(DocumentEvent::BlockCountChanged(new_count));
260        inner.queue_event(DocumentEvent::FlowElementsInserted {
261            flow_index: new_count - lines.len(),
262            count: lines.len(),
263        });
264
265        // Dispatch to `on_change` subscribers (outside the lock — a callback may
266        // re-enter), the same as an ordinary edit.
267        let queued = inner.take_queued_events();
268        drop(inner);
269        crate::inner::dispatch_queued_events(queued);
270        Ok(new_count)
271    }
272
273    /// Drop the first `n` blocks, returning how many were actually removed.
274    ///
275    /// The eviction half of a streaming buffer. Returns less than `n` when the
276    /// document holds fewer blocks; a document is never emptied completely —
277    /// one block always remains, since an empty document is not a valid state
278    /// here (it is created with one block, and the rest of the API assumes at
279    /// least one exists).
280    ///
281    /// **Not undoable**, by design — see the module docs.
282    pub fn truncate_front(&self, n: usize) -> Result<usize> {
283        let _settled = self.settle_transient_edits();
284        if n == 0 {
285            return Ok(0);
286        }
287
288        let mut inner = self.inner.lock();
289        let frame_id = get_main_frame_id(&inner);
290        if frame_id == 0 {
291            return Err(DocumentError::InvalidArgument(
292                "document has no main frame".into(),
293            ));
294        }
295
296        let stack = streaming_stack(&mut inner);
297
298        // Which blocks to drop, capped so that at least one always survives.
299        let (victims, chars_removed) = {
300            let frame = frame_commands::get_frame(&inner.ctx, &frame_id)?
301                .ok_or_else(|| DocumentError::InvalidArgument("main frame missing".into()))?;
302            let block_ids: Vec<EntityId> = frame
303                .child_order
304                .iter()
305                .filter(|e| **e > 0)
306                .map(|e| *e as EntityId)
307                .collect();
308            let take = n.min(block_ids.len().saturating_sub(1));
309            let victims: Vec<EntityId> = block_ids.into_iter().take(take).collect();
310
311            // Every victim's length must be counted, so a lookup that fails is
312            // an error rather than a silent zero: swallowing it would subtract
313            // too little from `character_count`, and since all later deltas are
314            // relative, the document's count would stay wrong forever with
315            // nothing reporting it.
316            let mut chars: i64 = 0;
317            for id in &victims {
318                let block = block_commands::get_block(&inner.ctx, id)?.ok_or_else(|| {
319                    DocumentError::InvalidArgument(format!(
320                        "block {id} is referenced by the frame but does not exist"
321                    ))
322                })?;
323                let entity: common::entities::Block = block.into();
324                let store = inner.ctx.db_context.get_store();
325                chars += common::database::rope_helpers::block_char_length(&entity, store);
326            }
327            (victims, chars)
328        };
329
330        if victims.is_empty() {
331            return Ok(0);
332        }
333
334        // Everything below either all lands or none of it does. Without this,
335        // a failure partway through the entity loop would leave the rope
336        // already stripped of victims whose blocks still exist and are still
337        // referenced by the frame.
338        let atomic = Atomic::begin(&inner)?;
339
340        // Unmirror from the rope first: `rope_remove_block` resolves each block
341        // through the offset index, which the entity must still exist for.
342        {
343            let store = inner.ctx.db_context.get_store();
344            for id in &victims {
345                common::database::rope_helpers::rope_remove_block(store, *id);
346            }
347        }
348
349        // Drop the entities, then the frame's references to them in one write.
350        for id in &victims {
351            block_commands::remove_block(&inner.ctx, Some(stack), id)?;
352        }
353        {
354            let frame = frame_commands::get_frame(&inner.ctx, &frame_id)?
355                .ok_or_else(|| DocumentError::InvalidArgument("main frame missing".into()))?;
356            let mut update: UpdateFrameDto = frame.into();
357            // Drop exactly the evicted ids, rather than the first N entries:
358            // `remove_block` may already have pruned them, and `child_order`
359            // can hold negative entries (sub-frames) that are not blocks, so
360            // positional removal would take out survivors.
361            let evicted: std::collections::HashSet<i64> =
362                victims.iter().map(|id| *id as i64).collect();
363            let before = update.child_order.len();
364            update.child_order.retain(|e| !evicted.contains(e));
365            if update.child_order.len() != before {
366                frame_commands::update_frame(&inner.ctx, Some(stack), &update)?;
367            }
368        }
369
370        let removed = victims.len();
371        let new_count = commit_counts(&mut inner, -(removed as i64), -chars_removed)?;
372        atomic.commit();
373
374        undo_redo_commands::clear_stack(&inner.ctx, stack);
375
376        // Everything shifts down by what was cut off the front.
377        inner.invalidate_text_cache();
378        inner.adjust_cursors(0, chars_removed as usize + removed, 0);
379        inner.modified = true;
380        inner.queue_event(DocumentEvent::ContentsChanged {
381            position: 0,
382            chars_removed: chars_removed as usize + removed,
383            chars_added: 0,
384            blocks_affected: removed,
385        });
386        inner.queue_event(DocumentEvent::BlockCountChanged(new_count));
387        inner.queue_event(DocumentEvent::FlowElementsRemoved {
388            flow_index: 0,
389            count: removed,
390        });
391
392        // Dispatch to `on_change` subscribers (outside the lock — a callback may
393        // re-enter), the same as an ordinary edit.
394        let queued = inner.take_queued_events();
395        drop(inner);
396        crate::inner::dispatch_queued_events(queued);
397        Ok(removed)
398    }
399}
400
401/// The document's block count, read straight off the entity.
402///
403/// [`TextDocument::block_count`](crate::TextDocument::block_count) answers the same question via
404/// `get_document_stats`, which also computes a word count by materializing every
405/// block's text — 3.18 ms at 10 000 lines. This is the cached value the entity
406/// already carries, which is what `inner.rs`'s own `check_block_count_changed`
407/// reads for exactly the same reason.
408fn current_block_count(inner: &TextDocumentInner) -> Result<i64> {
409    let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
410        .ok_or_else(|| DocumentError::InvalidArgument("document missing".into()))?;
411    Ok(doc.block_count)
412}
413
414/// A private undo stack for streaming writes, created on first use.
415///
416/// The entity commands always push an undo command — passing `None` does not
417/// opt out, it resolves to stack 0 (`add_command_to_stack`). Routing these
418/// writes to a stack of their own, cleared as they go, keeps them off the
419/// document's real history without bounding-problems or clearing what the user
420/// did.
421fn streaming_stack(inner: &mut TextDocumentInner) -> u64 {
422    if let Some(id) = inner.streaming_stack_id {
423        return id;
424    }
425    let id = undo_redo_commands::create_new_stack(&inner.ctx);
426    inner.streaming_stack_id = Some(id);
427    id
428}
429
430/// All-or-nothing around a streaming mutation.
431///
432/// These paths hand-maintain four things that must agree — the rope, the block
433/// offset index, the frame's `child_order`, and the document's cached counts —
434/// across several fallible calls. The ordinary editing path gets that
435/// consistency from the unit-of-work layer; taking the shortcut past it takes
436/// the shortcut past its atomicity too, so every early `?` would otherwise be a
437/// chance to leave the four disagreeing: text in the rope that no block owns, a
438/// block absent from `child_order`, counts describing a document that no longer
439/// exists.
440///
441/// A savepoint is a whole-store snapshot, but a cheap one — the rope is a
442/// persistent structure and the entity tables are `im::HashMap`s, so it is
443/// pointer-copies rather than a deep clone. Restoring it undoes everything
444/// since, the inner commands' own writes included, because each savepoint is an
445/// independent snapshot rather than a stack position.
446///
447/// Deliberately not `Transaction`, which is the same savepoint plus an
448/// O(N) `recompute_all_frame_byte_ranges` on commit — a cost this path exists
449/// to avoid, and one the inner commands' own transactions already pay.
450///
451/// Rolls back on drop unless [`commit`](Self::commit) ran, so an early `?` — or
452/// a panic — cannot leave the document half-written.
453struct Atomic {
454    /// Owned rather than borrowed: holding a reference would borrow the
455    /// document's interior for the guard's whole lifetime, which is exactly the
456    /// span in which the work needs `&mut` access to it.
457    store: Arc<common::database::Store>,
458    savepoint: Option<u64>,
459}
460
461impl Atomic {
462    /// Begun as every write to the store is (`RopeStore::check_write_allowed`): refused
463    /// over transient edits made since the append reverted them, and counted open until
464    /// its savepoint is discarded.
465    fn begin(inner: &TextDocumentInner) -> Result<Self> {
466        let store = Arc::clone(inner.ctx.db_context.get_store());
467        store.check_write_allowed()?;
468        let savepoint = Some(store.create_savepoint());
469        Ok(Self { store, savepoint })
470    }
471
472    /// Keep the mutations and drop the snapshot.
473    fn commit(mut self) {
474        if let Some(sp) = self.savepoint.take() {
475            self.store.discard_savepoint(sp);
476        }
477    }
478}
479
480impl Drop for Atomic {
481    fn drop(&mut self) {
482        // Still holding the savepoint means `commit` never ran: the operation
483        // left early, so put the document back exactly as it was.
484        if let Some(sp) = self.savepoint.take() {
485            self.store.restore_savepoint(sp);
486            self.store.discard_savepoint(sp);
487        }
488    }
489}
490
491/// What one appended line did to the document, as the caller's bookkeeping
492/// needs to describe it.
493struct Appended {
494    /// Document position the insertion began at.
495    edit_pos: usize,
496    /// Characters inserted there — the text, plus the separator when one was
497    /// needed. Not derivable from the text alone, which is the whole reason
498    /// this is reported rather than recomputed.
499    chars_added: usize,
500}
501
502/// Create one block, mirror it into the rope at the tail, and reference it from
503/// the frame.
504fn append_one(inner: &mut TextDocumentInner, frame_id: EntityId, text: &str) -> Result<Appended> {
505    let stack = streaming_stack(inner);
506
507    // Read the frame *before* creating the block: the generic create path adds
508    // the block to the junction table but not to `child_order`, so this sees
509    // exactly the blocks that already existed.
510    let frame = frame_commands::get_frame(&inner.ctx, &frame_id)?
511        .ok_or_else(|| DocumentError::InvalidArgument("main frame missing".into()))?;
512
513    // Blocks after the first in a frame are separated by a `\n` sentinel, and
514    // `rope_append_block` does not add one itself.
515    //
516    // The condition is "does the frame already hold a block", NOT "is the rope
517    // non-empty". A freshly created document already holds one *empty* block,
518    // registered at byte 0, with an empty rope — so keying off the rope would
519    // skip the separator and register the new block at byte 0 as well, leaving
520    // two blocks at the same offset with no `\n` between them. That is not a
521    // hypothetical: `TextDocument::new()` followed by `append_line` is the most
522    // direct way to use this API.
523    let needs_boundary = frame.child_order.iter().any(|entry| *entry > 0);
524
525    let block = block_commands::create_block(
526        &inner.ctx,
527        Some(stack),
528        &CreateBlockDto::default(),
529        frame_id,
530        -1,
531    )?;
532
533    let appended = {
534        let store = inner.ctx.db_context.get_store();
535        // Where the insertion begins — captured before it, so it covers the
536        // separator too when one is written.
537        let edit_pos = store.rope.read().len_chars();
538        if needs_boundary {
539            common::database::rope_helpers::rope_insert_block_boundary(store);
540        }
541        common::database::rope_helpers::rope_append_block(store, block.id, text);
542        Appended {
543            edit_pos,
544            chars_added: text.chars().count() + usize::from(needs_boundary),
545        }
546    };
547
548    // The generic create path adds the block to the junction table but not to
549    // `child_order`, which is what `flow()` reads — `initialize` notes the same.
550    let mut update: UpdateFrameDto = frame.into();
551    update.child_order.push(block.id as i64);
552    frame_commands::update_frame(&inner.ctx, Some(stack), &update)?;
553
554    Ok(appended)
555}
556
557/// Apply deltas to the document's cached counts, returning the new block count.
558fn commit_counts(
559    inner: &mut TextDocumentInner,
560    block_delta: i64,
561    char_delta: i64,
562) -> Result<usize> {
563    let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
564        .ok_or_else(|| DocumentError::InvalidArgument("document missing".into()))?;
565    let stack = streaming_stack(inner);
566    let mut update: UpdateDocumentDto = doc.into();
567    update.block_count = (update.block_count + block_delta).max(0);
568    update.character_count = (update.character_count + char_delta).max(0);
569    let new_count = update.block_count as usize;
570    document_commands::update_document(&inner.ctx, Some(stack), &update)?;
571    Ok(new_count)
572}
573
574/// Post-append bookkeeping shared by the append entry points.
575///
576/// `blocks_affected` is passed rather than assumed: a batch adds as many blocks
577/// as it has lines, and consumers size work off that number.
578fn finish(inner: &mut TextDocumentInner, edit_pos: usize, added: usize, blocks_affected: usize) {
579    let stack = streaming_stack(inner);
580    // Discard the throwaway history: these writes are not undoable, and letting
581    // it grow would leak a command per appended line.
582    undo_redo_commands::clear_stack(&inner.ctx, stack);
583
584    // The document's text just changed, so the lazily-built plain-text cache no
585    // longer describes it. Every ordinary edit clears this; bypassing the
586    // editing path means bypassing that too, and a stale cache is silent —
587    // `blocks()` reads the live document while `to_plain_text()` keeps serving
588    // whatever the text was when it was last asked.
589    inner.invalidate_text_cache();
590    inner.adjust_cursors(edit_pos, 0, added);
591    inner.modified = true;
592    inner.queue_event(DocumentEvent::ContentsChanged {
593        position: edit_pos,
594        chars_removed: 0,
595        chars_added: added,
596        blocks_affected,
597    });
598}
599
600#[cfg(test)]
601mod tests {
602    use super::*;
603
604    /// A streaming append that finds transient edits made since its revert (another
605    /// thread's, between the revert and its lock) is refused before it writes the rope.
606    #[test]
607    fn an_append_finding_transient_edits_is_refused_before_it_writes() {
608        let doc = TextDocument::new();
609        doc.append_line("first").unwrap();
610        doc.cursor_at(2).insert_text_transient("n").unwrap();
611        let shown = doc.to_plain_text().unwrap();
612        let refused = {
613            let inner = doc.inner.lock();
614            Atomic::begin(&inner).err()
615        };
616        assert!(matches!(
617            refused,
618            Some(DocumentError::TransientEdits(
619                crate::TransientRefusal::LayerOutstanding
620            ))
621        ));
622        assert_eq!(doc.to_plain_text().unwrap(), shown);
623        assert!(doc.has_transient_edits());
624        // Once they are reverted the append is begun, and counted open until it ends.
625        doc.revert_transient_edits();
626        let inner = doc.inner.lock();
627        let atomic = Atomic::begin(&inner).expect("nothing outstanding");
628        let store = inner.ctx.db_context.get_store();
629        assert!(store.begin_transient_write().is_err(), "the append is open");
630        atomic.commit();
631        assert!(store.begin_transient_write().is_ok());
632    }
633}