text-document 1.13.0

Rich text document editing library
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
//! Shared document interior state.
//!
//! # Lock ordering (enforced by convention, never violated)
//!
//! 1. `TextDocumentInner` (the document lock)
//! 2. `CursorData` (individual cursor locks)
//!
//! Always acquire the document lock before any cursor lock.
//! Pure cursor-local reads (position, anchor, has_selection) may lock
//! only CursorData — this is safe because they never touch the document
//! lock in the same call. Editing methods must lock the document first,
//! then read/update cursor data while the document lock is held, and
//! call `adjust_cursors()` before releasing the document lock.

use std::collections::HashMap;
use std::sync::atomic::AtomicBool;
use std::sync::{Arc, Weak};

use parking_lot::Mutex;

/// A batch of events paired with the callbacks to invoke for each.
pub(crate) type QueuedEvents = Vec<(
    crate::events::DocumentEvent,
    Vec<Arc<dyn Fn(crate::events::DocumentEvent) + Send + Sync>>,
)>;

use crate::Result;
use frontend::AppContext;
use frontend::EventHubClient;
use frontend::common::types::EntityId;
use frontend::event_hub_client::SubscriptionToken;

use crate::DocumentEvent;
use crate::highlight::HighlightRegistry;

/// Cursor position data stored inside the document for automatic adjustment.
pub(crate) struct CursorData {
    pub position: usize,
    pub anchor: usize,
    /// When set, overrides the computed `SelectionKind` to force cell selection.
    /// Cleared whenever position or anchor changes via normal editing/movement.
    pub cell_selection_override: Option<crate::flow::CellRange>,
    /// The language this cursor reads its text as, for the sentence operations
    /// ([`SelectionType::SentenceUnderCursor`](crate::SelectionType) and the sentence
    /// [`MoveOperation`](crate::MoveOperation)s). A BCP-47-ish tag; `None` means untailored
    /// UAX #29.
    ///
    /// Transient, per-cursor and non-persisted, like `cell_selection_override` beside it: it
    /// never reaches an entity, an undo command or an export. The enum-driven `select` /
    /// `move_position` have nowhere to take a locale argument, so it is set once on the cursor
    /// instead — [`TextDocument::sentence_at`](crate::TextDocument::sentence_at) takes the same
    /// value per call for callers that would rather not hold a cursor at all.
    pub content_locale: Option<String>,
    /// Whether the cursor's selection is the whole text, as
    /// [`select(SelectionType::Document)`](crate::SelectionType::Document) made it. Set there,
    /// and by a removal of a selection that left the text empty (a cut of all of it), and
    /// cleared by every other change of the cursor's position or anchor and by every edit,
    /// whichever cursor makes it (see `TextDocumentInner::end_whole_text_selections`). In
    /// an empty text that selection is empty, the same positions as a caret, and a paste over
    /// it still replaces the text, as a paste over any whole-text selection does (see
    /// `TextCursor::insert_fragment_with_origin`).
    pub whole_text_selected: bool,
    /// Where the selection was started, in a table's cell, while its moving end is outside
    /// that table. The table trap (see `TextCursor::set_position`) then sets `anchor` at
    /// the table's edge, so the selection shown, copied and removed holds the whole table;
    /// this is the end it came from, which the selection gets back when its moving end
    /// returns into the table. `None` whenever the anchor is where the selection started,
    /// and set back to `None` by every move of the anchor and every edit by this cursor.
    pub anchor_in_table: Option<usize>,
}

/// Callback entry for document event subscriptions.
pub(crate) struct CallbackEntry {
    pub alive: Weak<AtomicBool>,
    pub callback: Arc<dyn Fn(DocumentEvent) + Send + Sync>,
}

/// The shared document interior, behind `Arc<Mutex<>>`.
pub(crate) struct TextDocumentInner {
    pub ctx: AppContext,
    pub event_client: EventHubClient,
    pub stack_id: u64,
    /// Private undo stack for append-only streaming writes, created on first
    /// use (see `streaming.rs`). The entity commands always push an undo
    /// command — `None` resolves to stack 0 rather than opting out — so
    /// streaming routes its writes here and clears them as it goes, leaving
    /// `stack_id` (the user's real history) untouched.
    pub streaming_stack_id: Option<u64>,
    #[allow(dead_code)] // will be used for entity tree access
    pub root_id: EntityId,
    pub document_id: EntityId,
    pub modified: bool,
    /// Bumped once for every queued [`DocumentEvent::ContentsChanged`] — a
    /// cheap, monotonic "was this notification caused by exactly one edit,
    /// and nothing since" token. Unlike `modified` (a flag) or a
    /// millisecond-resolution `updated_at` timestamp, this can never
    /// collide between two edits and never merges the way the undo stack
    /// does when consecutive compatible commands coalesce. Read via
    /// [`TextDocument::content_revision`](crate::TextDocument::content_revision).
    pub content_revision: u64,

    // Cursor tracking
    pub cursors: Vec<Weak<Mutex<CursorData>>>,

    // Event dispatch — two independent delivery paths:
    //
    // 1. **Callback path** (`on_change`): `take_queued_events()` reads from
    //    `callback_cursor` to the end of `pending_events`, advances the cursor,
    //    and returns events + callbacks for dispatch outside the lock.
    //
    // 2. **Polling path** (`poll_events`): `poll_events()` reads from
    //    `poll_cursor` to the end of `pending_events` and advances the cursor.
    //
    // The two paths are independent — using both simultaneously is fine.
    // Events are trimmed from the front of `pending_events` when both cursors
    // have advanced past them.
    pub pending_events: Vec<DocumentEvent>,
    pub callbacks: Vec<CallbackEntry>,
    /// Next event index for callback dispatch.
    pub callback_cursor: usize,
    /// Next event index for `poll_events()`.
    pub poll_cursor: usize,

    // Resource name → entity ID cache for O(1) lookups by name.
    pub resource_cache: HashMap<String, u64>,

    // Cached plain text for the entire document. Populated lazily, invalidated
    // on any edit or document reset. Avoids O(blocks) reconstruction per search.
    pub plain_text_cache: Option<String>,

    // Last known block count, used to detect changes and emit BlockCountChanged.
    pub last_block_count: usize,

    // Last known child_order of the main frame, used to detect flow changes
    // and emit FlowElementsInserted/FlowElementsRemoved.
    pub last_child_order: Vec<i64>,

    // Highlight sessions (shadow formatting layer): a syntax highlighter, a spell-checker, a
    // find session per view — each a session with its own id, merged in registration order.
    pub highlights: HighlightRegistry,

    // The effective kind under the ALL-sessions mask, recomputed after every rehighlight pass.
    // Drives whether highlights are merged into the shaping input or kept as a paint overlay
    // for the unmasked `snapshot_flow()`; masked snapshots derive their own at the root.
    pub highlight_kind: crate::highlight::HighlighterKind,

    /// The shared backend this document was built in, if any.
    ///
    /// `None` for a document built by `TextDocument::new`, which owns its whole
    /// context and its own pump. `Some` means the hub, the pump and the
    /// long-operation manager belong to a [`DocumentBackend`](crate::DocumentBackend)
    /// shared with sibling documents, and this document must not shut any of
    /// them down on its own way out.
    pub backend: Option<crate::DocumentBackend>,
    /// The ids of the long operations this document started.
    ///
    /// A shared hub delivers every document's long-operation events to every
    /// document's subscription, so each one has to recognise its own. Empty for
    /// a standalone document, which is the only subscriber on its own hub and
    /// can accept everything it is handed.
    pub own_operations: std::collections::HashSet<String>,
    /// The loads in place this document started that are still to clear its undo history,
    /// each with the flag its result reader shares with the completion handler: whichever
    /// of the two sees the new content first clears the history and sets the flag, so the
    /// other leaves alone the history of any edit made since.
    pub history_resets: HashMap<String, Arc<AtomicBool>>,
    // Holds SubscriptionTokens for LongOperation event bridges. Dropping a
    // token unsubscribes the callback, so these must outlive the document.
    pub long_op_subscriptions: Vec<SubscriptionToken>,
    /// The empty paragraph the last removal of all of the main text left, as it looked then
    /// (see [`EmptiedText`]). A text of its own structure pasted into the main text while it
    /// is that paragraph, looking the same, replaces it, by whichever cursor and after
    /// whatever brought the text back to it.
    pub emptied_text: Option<EmptiedText>,
}

/// The one empty paragraph the main text is: the block, the list it is an item of and the
/// frames under the main frame, each without what names or dates it, as a removal of all of
/// the text left them.
///
/// That paragraph keeps the formatting of the first paragraph removed, which is not the
/// text a paste of what was cut brings back: a text of its own structure pasted into it
/// replaces it (see `TextCursor::insert_fragment_with_origin`). The cursor that removed the
/// text says so until the next edit, and nothing says so after an undo or a redo back to the
/// empty paragraph: cut everything, paste, undo and paste again, and a scene opening with an
/// epigraph came back quoted from end to end. The paragraph as it looked is kept here
/// instead, beside the document: an undo gives the same paragraph back, looking the same,
/// while a heading, a list item or a quotation the writer makes of it, or another text
/// loaded, looks otherwise, and a paste goes into it as into any formatted line.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct EmptiedText {
    block_id: EntityId,
    block: common::entities::Block,
    list: Option<common::entities::List>,
    frames: Vec<common::entities::Frame>,
}

impl EmptiedText {
    /// The main text as `store` holds it, when it is one paragraph holding nothing: no
    /// character, no image, no second paragraph and no table.
    pub(crate) fn of(store: &common::database::Store) -> Option<Self> {
        use common::entities::{Block, Frame, List};
        let main_frame = store
            .documents
            .read()
            .values()
            .next()
            .and_then(|document| document.frames.first().copied())?;
        let frames = store.frames.read();
        // The frames under the main frame in reading order, and the one block they hold.
        let mut sub_frames: Vec<Frame> = Vec::new();
        let mut only_block: Option<EntityId> = None;
        let mut pending: Vec<EntityId> = vec![main_frame];
        let mut seen: std::collections::HashSet<EntityId> = std::collections::HashSet::new();
        while let Some(frame_id) = pending.pop() {
            if !seen.insert(frame_id) {
                return None;
            }
            let frame = frames.get(&frame_id)?;
            if frame.table.is_some() || frame.footnote_label.is_some() {
                return None;
            }
            if frame_id != main_frame {
                sub_frames.push(Frame {
                    id: 0,
                    created_at: Default::default(),
                    updated_at: Default::default(),
                    parent_frame: None,
                    blocks: Vec::new(),
                    child_order: Vec::new(),
                    byte_range: (0, 0),
                    ..frame.clone()
                });
            }
            // In reverse, so that the first sub-frame is looked at first.
            for entry in frame.child_order.iter().rev() {
                if *entry > 0 {
                    if only_block.is_some() {
                        return None;
                    }
                    only_block = Some(*entry as EntityId);
                } else if *entry < 0 {
                    pending.push(entry.unsigned_abs() as EntityId);
                }
            }
        }
        drop(frames);
        let block_id = only_block?;
        let block = store.blocks.read().get(&block_id)?.clone();
        if common::database::rope_helpers::block_char_length(&block, store) != 0 {
            return None;
        }
        let list = block.list.and_then(|list_id| {
            store.lists.read().get(&list_id).map(|list| List {
                id: 0,
                created_at: Default::default(),
                updated_at: Default::default(),
                ..list.clone()
            })
        });
        Some(EmptiedText {
            block_id,
            block: Block {
                id: 0,
                created_at: Default::default(),
                updated_at: Default::default(),
                document_position: 0,
                list: None,
                ..block
            },
            list,
            frames: sub_frames,
        })
    }
}

impl TextDocumentInner {
    /// Remove dead `Weak` refs from the cursor list.
    pub fn prune_dead_cursors(&mut self) {
        self.cursors.retain(|w| w.strong_count() > 0);
    }

    /// After an edit, adjust all tracked cursor positions.
    ///
    /// Called while the document lock is held. Then locks individual
    /// CursorData mutexes (safe per lock ordering: doc before cursor).
    pub fn adjust_cursors(&mut self, edit_pos: usize, removed: usize, added: usize) {
        self.prune_dead_cursors();
        for weak in &self.cursors {
            if let Some(cursor) = weak.upgrade() {
                let mut data = cursor.lock();
                data.position = adjust_offset(data.position, edit_pos, removed, added);
                data.anchor = adjust_offset(data.anchor, edit_pos, removed, added);
                data.anchor_in_table = data
                    .anchor_in_table
                    .map(|origin| adjust_offset(origin, edit_pos, removed, added));
                // Cell selection override references table coordinates that may be
                // invalidated by the edit, so always clear it.
                data.cell_selection_override = None;
                // The text is not the one that was selected whole any more.
                data.whole_text_selected = false;
            }
        }
    }

    /// Register a new cursor and return its shared data.
    pub fn register_cursor(&mut self, position: usize) -> Arc<Mutex<CursorData>> {
        self.prune_dead_cursors();
        let data = Arc::new(Mutex::new(CursorData {
            position,
            anchor: position,
            content_locale: None,
            cell_selection_override: None,
            whole_text_selected: false,
            anchor_in_table: None,
        }));
        self.cursors.push(Arc::downgrade(&data));
        data
    }

    /// Queue a DocumentEvent for deferred dispatch.
    ///
    /// Events are collected while the lock is held, then dispatched
    /// after the lock is released via [`dispatch_queued_events`].
    pub fn queue_event(&mut self, event: DocumentEvent) {
        match event {
            DocumentEvent::ContentsChanged { .. } => {
                self.content_revision = self.content_revision.wrapping_add(1);
            }
            DocumentEvent::UndoRedoChanged { .. } => self.end_whole_text_selections(),
            // A text loaded in place is not the one a removal emptied, however alike its
            // empty paragraph looks.
            DocumentEvent::DocumentReset => self.emptied_text = None,
            _ => {}
        }
        self.pending_events.push(event);
    }

    /// Whether the main text is the empty paragraph the last removal of all of it left,
    /// looking as it did then (see [`EmptiedText`]).
    pub(crate) fn is_the_emptied_text(&self) -> bool {
        self.emptied_text.as_ref().is_some_and(|emptied| {
            EmptiedText::of(self.ctx.db_context.get_store()).as_ref() == Some(emptied)
        })
    }

    /// End every cursor's whole-text selection (see [`CursorData::whole_text_selected`]).
    ///
    /// Called as the state of the history is announced, which every edit does, a formatting
    /// edit or a load in place as much as typing: a paste after it goes into the text as the
    /// edit left it. Only the edits moving text moved the cursors, and only those ended the
    /// selection: after a cut of everything, a heading, a list item or a quotation made of the
    /// emptied line, or a text loaded over it, was taken off by the paste that followed.
    pub(crate) fn end_whole_text_selections(&mut self) {
        for weak in &self.cursors {
            if let Some(cursor) = weak.upgrade() {
                cursor.lock().whole_text_selected = false;
            }
        }
    }

    /// Return events added since the last `poll_events()` call.
    ///
    /// This path is independent of callback dispatch — using both
    /// `poll_events()` and `on_change()` simultaneously is safe and
    /// each path sees every event exactly once.
    pub fn drain_poll_events(&mut self) -> Vec<DocumentEvent> {
        if self.poll_cursor >= self.pending_events.len() {
            self.trim_delivered_events();
            return Vec::new();
        }
        let events = self.pending_events[self.poll_cursor..].to_vec();
        self.poll_cursor = self.pending_events.len();
        self.trim_delivered_events();
        events
    }

    /// Collect un-dispatched events paired with live callbacks.
    ///
    /// Only events added since the last call are returned. The caller
    /// should release the lock and then invoke callbacks via
    /// [`dispatch_queued_events`].
    pub fn take_queued_events(&mut self) -> QueuedEvents {
        if self.callback_cursor >= self.pending_events.len() {
            return Vec::new();
        }

        self.callbacks
            .retain(|entry| entry.alive.strong_count() > 0);

        let live_callbacks: Vec<Arc<dyn Fn(DocumentEvent) + Send + Sync>> = self
            .callbacks
            .iter()
            .filter_map(|entry| {
                let alive = entry.alive.upgrade()?;
                if alive.load(std::sync::atomic::Ordering::Relaxed) {
                    Some(Arc::clone(&entry.callback))
                } else {
                    None
                }
            })
            .collect();

        if live_callbacks.is_empty() {
            self.callback_cursor = self.pending_events.len();
            return Vec::new();
        }

        let new_events: Vec<DocumentEvent> = self.pending_events[self.callback_cursor..].to_vec();
        self.callback_cursor = self.pending_events.len();

        new_events
            .into_iter()
            .map(|e| (e, live_callbacks.clone()))
            .collect()
    }

    /// Discard events that both delivery paths have consumed.
    fn trim_delivered_events(&mut self) {
        let min_cursor = self.callback_cursor.min(self.poll_cursor);
        if min_cursor > 0 {
            self.pending_events.drain(..min_cursor);
            self.callback_cursor -= min_cursor;
            self.poll_cursor -= min_cursor;
        }
    }

    /// Invalidate the cached plain text. Call after any edit.
    pub fn invalidate_text_cache(&mut self) {
        self.plain_text_cache = None;
    }

    /// Check the current block count and queue a `BlockCountChanged` event if it changed.
    pub fn check_block_count_changed(&mut self) {
        let doc = frontend::commands::document_commands::get_document(&self.ctx, &self.document_id);
        if let Ok(Some(doc)) = doc {
            let new_count = doc.block_count as usize;
            if new_count != self.last_block_count {
                self.last_block_count = new_count;
                self.queue_event(crate::DocumentEvent::BlockCountChanged(new_count));
            }
        }
    }

    /// Check whether the main frame's `child_order` changed and queue
    /// `FlowElementsInserted` / `FlowElementsRemoved` events.
    ///
    /// Uses a simple diff: finds the first index where old and new diverge,
    /// then determines whether elements were inserted, removed, or replaced.
    pub fn check_flow_changed(&mut self) {
        let current = self.main_frame_child_order();
        if current == self.last_child_order {
            return;
        }

        let old = &self.last_child_order;
        let new = &current;

        // Find first index of divergence
        let prefix_len = old
            .iter()
            .zip(new.iter())
            .take_while(|(a, b)| a == b)
            .count();

        // Find common suffix length (after the divergent region)
        let old_remaining = old.len() - prefix_len;
        let new_remaining = new.len() - prefix_len;
        let suffix_len = old[prefix_len..]
            .iter()
            .rev()
            .zip(new[prefix_len..].iter().rev())
            .take_while(|(a, b)| a == b)
            .count();

        let removed_count = old_remaining - suffix_len;
        let inserted_count = new_remaining - suffix_len;

        if removed_count > 0 {
            self.queue_event(crate::DocumentEvent::FlowElementsRemoved {
                flow_index: prefix_len,
                count: removed_count,
            });
        }
        if inserted_count > 0 {
            self.queue_event(crate::DocumentEvent::FlowElementsInserted {
                flow_index: prefix_len,
                count: inserted_count,
            });
        }

        self.last_child_order = current;
    }

    /// Reset the cached child_order to the current state without emitting events.
    /// Call after a `DocumentReset` event, since the layout engine will do a full
    /// rebuild anyway.
    pub fn reset_cached_child_order(&mut self) {
        self.last_child_order = self.main_frame_child_order();
    }

    /// Read the main frame's current child_order from the database.
    fn main_frame_child_order(&self) -> Vec<i64> {
        let frames = frontend::commands::document_commands::get_document_relationship(
            &self.ctx,
            &self.document_id,
            &frontend::document::dtos::DocumentRelationshipField::Frames,
        )
        .unwrap_or_default();

        let main_frame_id = match frames.first() {
            Some(&id) => id,
            None => return Vec::new(),
        };

        frontend::commands::frame_commands::get_frame(&self.ctx, &(main_frame_id as u64))
            .ok()
            .flatten()
            .map(|f| f.child_order)
            .unwrap_or_default()
    }

    /// Get or lazily build the cached plain text.
    ///
    /// Read fresh, and not cached, while one of this document's own long
    /// operations runs. An import writes into the store in place, with no
    /// isolation from a read, so a read taken meanwhile sees the document partly
    /// replaced (or, since the importers hand new blocks to their owners at the
    /// end, briefly empty), and its completion invalidates nothing: a cached copy
    /// of that read would be returned after the import was done. `set_*` clear
    /// the cache before starting, so nothing stale can be left once the
    /// operation's end is handled.
    pub fn plain_text(&mut self) -> Result<std::borrow::Cow<'_, str>> {
        if !self.own_operations.is_empty() {
            let dto = frontend::commands::document_io_commands::export_plain_text(&self.ctx)?;
            return Ok(std::borrow::Cow::Owned(dto.plain_text));
        }
        let text = match self.plain_text_cache.take() {
            Some(text) => text,
            None => {
                frontend::commands::document_io_commands::export_plain_text(&self.ctx)?.plain_text
            }
        };
        Ok(std::borrow::Cow::Borrowed(
            self.plain_text_cache.insert(text).as_str(),
        ))
    }

    /// Initialize the document: create Root → Document → Frame → Block.
    /// Initialize a document inside a shared backend: its own store and undo
    /// stack, the backend's hub, pump and long-operation manager.
    pub fn initialize_in(backend: &crate::DocumentBackend) -> Result<Self> {
        let ctx = AppContext::new_sharing(backend.shared_ctx());
        let mut inner = Self::initialize_with_pump(ctx, false)?;
        inner.backend = Some(backend.clone());
        Ok(inner)
    }

    pub fn initialize(ctx: AppContext) -> Result<Self> {
        Self::initialize_with_pump(ctx, true)
    }

    /// `own_pump` is false for a document in a shared backend, whose pump is the
    /// backend's. Starting a second one on the same hub would have two threads
    /// competing for each event, and flume delivers an event to exactly one
    /// receiver, so half of them would reach the wrong drain.
    fn initialize_with_pump(ctx: AppContext, own_pump: bool) -> Result<Self> {
        use frontend::block::dtos::CreateBlockDto;
        use frontend::commands::{
            block_commands, document_commands, frame_commands, root_commands, undo_redo_commands,
        };
        use frontend::document::dtos::CreateDocumentDto;
        use frontend::frame::dtos::CreateFrameDto;
        use frontend::root::dtos::CreateRootDto;

        let event_client = EventHubClient::new(&ctx.event_hub);
        if own_pump {
            event_client.start(ctx.shutdown_rx.clone());
        }

        let stack_id = undo_redo_commands::create_new_stack(&ctx);

        // Create entity tree: Root → Document → Frame → Block
        let root = root_commands::create_orphan_root(&ctx, &CreateRootDto::default())?;
        let doc = document_commands::create_document(
            &ctx,
            Some(stack_id),
            &CreateDocumentDto::default(),
            root.id,
            -1,
        )?;
        let frame = frame_commands::create_frame(
            &ctx,
            Some(stack_id),
            &CreateFrameDto::default(),
            doc.id,
            -1,
        )?;
        let block = block_commands::create_block(
            &ctx,
            Some(stack_id),
            &CreateBlockDto::default(),
            frame.id,
            -1,
        )?;

        // Register the initial empty block in `block_offsets` so
        // subsequent rope mirrors (insert_text, insert_fragment, etc.)
        // can resolve its byte position. The generic create_block CRUD
        // path doesn't touch the rope.
        common::database::rope_helpers::rope_append_empty_block(
            ctx.db_context.get_store(),
            block.id,
        );

        // Fix child_order on the main frame — the generic create_block path
        // adds the block to the blocks junction table but does not update
        // child_order. We must set it so that flow() works correctly.
        let mut frame_update: frontend::frame::dtos::UpdateFrameDto = frame.into();
        frame_update.child_order = vec![block.id as i64];
        frame_commands::update_frame(&ctx, Some(stack_id), &frame_update)?;

        // Clear undo stack — initialization shouldn't be undoable
        undo_redo_commands::clear_stack(&ctx, stack_id);

        // Counted here rather than at the top of the function: every `?` above
        // returns without a body, and a count that included those would drift
        // upwards on its own and read as a leak.
        LIVE_DOCUMENTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);

        Ok(Self {
            ctx,
            event_client,
            stack_id,
            streaming_stack_id: None,
            root_id: root.id,
            document_id: doc.id,
            modified: false,
            content_revision: 0,
            cursors: Vec::new(),
            pending_events: Vec::new(),
            callbacks: Vec::new(),
            callback_cursor: 0,
            poll_cursor: 0,
            resource_cache: HashMap::new(),
            plain_text_cache: None,
            last_block_count: 1, // new document starts with one block
            last_child_order: vec![block.id as i64],
            highlights: HighlightRegistry::default(),
            highlight_kind: crate::highlight::HighlighterKind::None,
            long_op_subscriptions: Vec::new(),
            backend: None,
            own_operations: std::collections::HashSet::new(),
            history_resets: HashMap::new(),
            emptied_text: None,
        })
    }
}

impl TextDocumentInner {
    /// Whether `op_id` names an operation this document started.
    ///
    /// A standalone document is the only subscriber on its own hub, so
    /// everything it is handed is its own and the recorded set is never
    /// consulted. Only a document in a shared backend can be offered a sibling's
    /// event, and only then does the answer matter.
    pub fn owns_operation(&self, op_id: &str) -> bool {
        self.backend.is_none() || self.own_operations.contains(op_id)
    }
}

/// How many document bodies are alive in this process right now.
///
/// A `TextDocument` is a handle onto an `Arc<Mutex<TextDocumentInner>>`, so one
/// surviving clone anywhere keeps a document's rope, block table and store alive.
/// That makes "is anything still holding a document" a question a host cannot
/// answer from the outside, and it is exactly the question a leak hunt asks: the
/// bytes show up under the rope and the block table whatever holds them.
///
/// Read it through [`crate::live_document_count`].
pub(crate) static LIVE_DOCUMENTS: std::sync::atomic::AtomicUsize =
    std::sync::atomic::AtomicUsize::new(0);

impl Drop for TextDocumentInner {
    fn drop(&mut self) {
        LIVE_DOCUMENTS.fetch_sub(1, std::sync::atomic::Ordering::Relaxed);
        // Only a document that owns its context may stop its pump. One built in
        // a shared backend shares that pump with every sibling, and shutting it
        // down here would stop delivery for all of them the first time any one
        // document was dropped. The backend's own `Drop` ends it instead.
        if self.backend.is_none() {
            self.ctx.shutdown();
        }
    }
}

/// Dispatch queued events outside the lock.
///
/// Call this after releasing the document mutex to avoid deadlocks
/// when callbacks call back into the document.
pub(crate) fn dispatch_queued_events(queued: QueuedEvents) {
    for (event, callbacks) in queued {
        for cb in &callbacks {
            cb(event.clone());
        }
    }
}

/// Shift an offset after an edit: offsets before the edit are unchanged,
/// offsets inside the removed range clamp to the edit point, offsets after
/// shift by the delta.
/// The character and block counts the `Document` entity already carries.
///
/// **The cheap answer to a question that had only an expensive one.**
/// `get_document_stats` returns these two straight off the entity
/// (`get_document_stats_uc.rs` reads `document.character_count` /
/// `document.block_count`), and then, for the word count and image count in the
/// same DTO, opens a transaction, fetches every block, materialises each one's
/// text out of the rope into a fresh `String` and whitespace-splits it. Measured
/// at 3.18 ms for a ten-thousand-line document in `streaming.rs`'s own baseline.
///
/// Every caller that only wanted "how long is this document" was paying that
/// walk: the caret's end-of-document clamp on every move, insert and delete, and
/// a host's `character_count()` on every layout measurement. `streaming.rs`
/// already went around it for the block count alone and recorded why; this is
/// the same read, shared, so that no caller has to know.
///
/// `None` when the document entity cannot be read, so each caller keeps the
/// fallback it already had rather than being handed a zero that reads as an
/// empty document.
pub(crate) fn document_counts(inner: &TextDocumentInner) -> Option<(usize, usize)> {
    let doc = frontend::commands::document_commands::get_document(&inner.ctx, &inner.document_id)
        .ok()
        .flatten()?;
    Some((
        usize::try_from(doc.character_count).unwrap_or(0),
        usize::try_from(doc.block_count).unwrap_or(0),
    ))
}

pub(crate) fn adjust_offset(offset: usize, edit_pos: usize, removed: usize, added: usize) -> usize {
    if offset <= edit_pos {
        offset
    } else if offset <= edit_pos + removed {
        edit_pos + added
    } else {
        offset - removed + added
    }
}

/// Refresh `BlockDto::document_position` in-place from the rope: the DTO face of
/// `rope_helpers::refresh_block_positions`, and the same rule — a no-op only for a
/// document whose blocks are not all mirrored to the rope, where the stored field is
/// maintained by the editing use cases and is the authoritative source.
pub(crate) fn refresh_block_positions(
    dtos: &mut [frontend::block::dtos::BlockDto],
    store: &common::database::Store,
) {
    common::database::rope_helpers::refresh_positions_from_rope(
        store,
        dtos.iter_mut()
            .map(|dto| (dto.id, &mut dto.document_position)),
    );
}

/// The block a **caret** at `position` sits in.
///
/// `get_block_at_position` reads its argument as a character index, so the inter-block
/// separator belongs to the block that follows it. That is right for walking text and is
/// pinned by its own tests — but a caret on that same offset has not left the paragraph it
/// just finished typing, and every cursor-driven query wants the other answer.
///
/// The correction is exact rather than heuristic: past a table's anchor, the separator
/// rule is the only way the command can report a block starting *after* the position asked
/// for, and a separator is exactly one character wide, so the caret belongs to whatever owns
/// `position - 1`. A caret on a table's anchor stands at the table's first cell, as every
/// edit reads it: the command reports that cell's block, which starts after the anchor, and
/// it is the caret's.
///
/// Lives here so the document-level query, the cursor's own, and anything else needing
/// caret semantics share one rule instead of three copies that can drift.
pub(crate) fn block_at_caret_dto(
    ctx: &AppContext,
    position: usize,
) -> Result<frontend::document_inspection::BlockInfoDto> {
    let at = |p: usize| {
        frontend::commands::document_inspection_commands::get_block_at_position(
            ctx,
            &frontend::document_inspection::GetBlockAtPositionDto { position: p as i64 },
        )
    };
    let store = ctx.db_context.get_store();
    let past_anchor =
        common::database::rope_helpers::snap_off_table_anchor(store, position as i64, true);
    if past_anchor != position as i64 {
        return Ok(at(past_anchor.max(0) as usize)?);
    }
    let info = at(position)?;
    if position > 0 && (info.block_start as usize) > position {
        return Ok(at(position - 1)?);
    }
    Ok(info)
}

/// Like [`refresh_block_positions`] but for a single DTO.
pub(crate) fn refresh_block_position(
    dto: &mut frontend::block::dtos::BlockDto,
    store: &common::database::Store,
) {
    refresh_block_positions(std::slice::from_mut(dto), store);
}