Skip to main content

text_document/
document.rs

1//! TextDocument implementation.
2
3use std::sync::Arc;
4
5use parking_lot::Mutex;
6
7use crate::{DocumentError, Result};
8use base64::Engine;
9use base64::engine::general_purpose::STANDARD as BASE64;
10
11use crate::{
12    DjotExportOptions, DjotImportOptions, MarkdownExportOptions, PlainTextExportOptions,
13    ResourceType, TextDirection, WrapMode,
14};
15use frontend::commands::{
16    block_commands, document_commands, document_inspection_commands, document_io_commands,
17    document_search_commands, frame_commands, resource_commands, table_cell_commands,
18    table_commands, undo_redo_commands,
19};
20
21use crate::HtmlExportOptions;
22use crate::convert::{self, to_i64, to_usize};
23use crate::cursor::TextCursor;
24use crate::events::{self, DocumentEvent, Subscription};
25use crate::flow::FormatChangeKind;
26use crate::inner::TextDocumentInner;
27use crate::operation::{
28    DjotImportResult, DocxExportResult, EpubExportResult, HtmlImportResult, MarkdownImportResult,
29    OdtExportResult, Operation, PdfExportResult,
30};
31use crate::{BlockFormat, BlockInfo, DocumentStats, FindMatch, FindOptions, ReplaceRange};
32
33/// A rich text document.
34///
35/// Owns the backend (database, event hub, undo/redo manager) and provides
36/// document-level operations. All cursor-based editing goes through
37/// [`TextCursor`], obtained via [`cursor()`](TextDocument::cursor) or
38/// [`cursor_at()`](TextDocument::cursor_at).
39///
40/// Internally uses `Arc<Mutex<...>>` so that multiple [`TextCursor`]s can
41/// coexist and edit concurrently. Cloning a `TextDocument` creates a new
42/// handle to the **same** underlying document (like Qt's implicit sharing).
43#[derive(Clone)]
44pub struct TextDocument {
45    pub(crate) inner: Arc<Mutex<TextDocumentInner>>,
46}
47
48/// A load in place's result reader, made to clear the document's undo history the first time
49/// it hands over a successful result.
50///
51/// An import in place runs on a thread of its own, and the document learns of its end through
52/// the completion event, which reaches it on the event thread, possibly after the caller's
53/// [`Operation::wait`] has returned. Clearing only there left the history of the replaced
54/// content undoable for a while after `wait`, and would clear the entry of an edit made in
55/// that while. So the reader and the completion handler share one flag, registered here under
56/// the operation's id: whichever sees the new content first clears the history, and the
57/// other finds the flag set and leaves the history alone.
58///
59/// The reader that sees it first also ends every cursor's whole-text selection, as the
60/// completion does when it announces the history (see
61/// `TextDocumentInner::end_whole_text_selections`): a cursor that cut everything before the
62/// load, and pasted once `wait` returned, took off the formatting of the text just loaded.
63/// `doc` is the document's own handle, held weakly: the reader is run by the caller of
64/// [`Operation::wait`] or [`Operation::try_result`], never under the document's lock.
65fn clearing_history_on_success<T: 'static>(
66    doc: &Arc<Mutex<TextDocumentInner>>,
67    inner: &mut TextDocumentInner,
68    op_id: &str,
69    read: impl Fn(&frontend::AppContext, &str) -> Option<Result<T>> + Send + 'static,
70) -> crate::operation::ResultFn<T> {
71    let cleared = Arc::new(std::sync::atomic::AtomicBool::new(false));
72    inner
73        .history_resets
74        .insert(op_id.to_string(), Arc::clone(&cleared));
75    let stack_id = inner.stack_id;
76    let doc = Arc::downgrade(doc);
77    Box::new(move |ctx, id| {
78        let result = read(ctx, id)?;
79        if result.is_ok() && !cleared.swap(true, std::sync::atomic::Ordering::SeqCst) {
80            undo_redo_commands::clear_stack(ctx, stack_id);
81            if let Some(doc) = doc.upgrade() {
82                doc.lock().end_whole_text_selections();
83            }
84        }
85        Some(result)
86    })
87}
88
89/// Test-only accessor for the underlying rope-backed store. Not part
90/// of the stable public API.
91impl TextDocument {
92    #[doc(hidden)]
93    pub fn rope_store_for_test(&self) -> std::sync::Arc<common::database::Store> {
94        let inner = self.inner.lock();
95        std::sync::Arc::clone(inner.ctx.db_context.get_store())
96    }
97}
98
99impl TextDocument {
100    // ── Construction ──────────────────────────────────────────
101
102    /// Create a new, empty document.
103    ///
104    /// # Panics
105    ///
106    /// Panics if the database context cannot be created (e.g. filesystem error).
107    /// Use [`TextDocument::try_new`] for a fallible alternative.
108    pub fn new() -> Self {
109        Self::try_new().expect("failed to initialize document")
110    }
111
112    /// Create a new, empty document, returning an error on failure.
113    pub fn try_new() -> Result<Self> {
114        let ctx = frontend::AppContext::new();
115        let doc_inner = TextDocumentInner::initialize(ctx)?;
116        let inner = Arc::new(Mutex::new(doc_inner));
117
118        // Bridge backend long-operation events to public DocumentEvent.
119        Self::subscribe_long_operation_events(&inner);
120
121        Ok(Self { inner })
122    }
123
124    /// Create a document inside a shared [`DocumentBackend`].
125    ///
126    /// The document keeps its own store and its own undo stack, because undo
127    /// snapshots and restores a whole store and two documents sharing one would
128    /// roll each other back. What it shares is the event hub, the single thread
129    /// draining it, and the long-operation manager.
130    ///
131    /// Use this wherever a host opens many documents at once. Each
132    /// [`TextDocument::new`] starts an OS thread of its own, so a manuscript
133    /// stream over a book-length project starts one per scene.
134    ///
135    /// The backend must outlive every document built in it: dropping it stops
136    /// the pump. Holding a [`DocumentBackend`] clone beside the documents is
137    /// enough, and it is what the documents themselves do.
138    ///
139    /// [`DocumentBackend`]: crate::DocumentBackend
140    pub fn new_in(backend: &crate::DocumentBackend) -> Self {
141        Self::try_new_in(backend).expect("failed to initialize document")
142    }
143
144    /// [`new_in`](Self::new_in), returning an error instead of panicking.
145    pub fn try_new_in(backend: &crate::DocumentBackend) -> Result<Self> {
146        let doc_inner = TextDocumentInner::initialize_in(backend)?;
147        let inner = Arc::new(Mutex::new(doc_inner));
148        Self::subscribe_long_operation_events(&inner);
149        Ok(Self { inner })
150    }
151
152    /// Subscribe to backend long-operation events and bridge them to DocumentEvent.
153    fn subscribe_long_operation_events(inner: &Arc<Mutex<TextDocumentInner>>) {
154        use frontend::common::event::{LongOperationEvent as LOE, Origin};
155
156        let weak = Arc::downgrade(inner);
157        let mut locked = inner.lock();
158        // In a shared backend the subscriptions go on the backend's client,
159        // because that is the one with a thread behind it. The document's own
160        // client exists but was never started: a second drain on one hub would
161        // compete for each event, and flume hands an event to exactly one
162        // receiver, so half of them would reach the wrong document.
163        let client = match &locked.backend {
164            Some(backend) => backend.client().clone(),
165            None => locked.event_client.clone(),
166        };
167
168        // Progress
169        let w = weak.clone();
170        let progress_tok = client.subscribe(Origin::LongOperation(LOE::Progress), move |event| {
171            if let Some(inner) = w.upgrade() {
172                let (op_id, percent, message) = parse_progress_data(&event.data);
173                let mut inner = inner.lock();
174                if !inner.owns_operation(&op_id) {
175                    return;
176                }
177                inner.queue_event(DocumentEvent::LongOperationProgress {
178                    operation_id: op_id,
179                    percent,
180                    message,
181                });
182            }
183        });
184
185        // Completed
186        let w = weak.clone();
187        let completed_tok = client.subscribe(Origin::LongOperation(LOE::Completed), move |event| {
188            if let Some(inner) = w.upgrade() {
189                let op_id = parse_id_data(&event.data);
190                let mut inner = inner.lock();
191                if !inner.owns_operation(&op_id) {
192                    return;
193                }
194                inner.own_operations.remove(&op_id);
195                inner.queue_event(DocumentEvent::DocumentReset);
196                inner.check_block_count_changed();
197                inner.reset_cached_child_order();
198                // A load in place leaves no history behind it, unless a read of its
199                // result cleared it first (see `clearing_history_on_success`).
200                if let Some(cleared) = inner.history_resets.remove(&op_id) {
201                    if !cleared.swap(true, std::sync::atomic::Ordering::SeqCst) {
202                        undo_redo_commands::clear_stack(&inner.ctx, inner.stack_id);
203                    }
204                    let stack = Some(inner.stack_id);
205                    let can_undo = undo_redo_commands::can_undo(&inner.ctx, stack);
206                    let can_redo = undo_redo_commands::can_redo(&inner.ctx, stack);
207                    inner.queue_event(DocumentEvent::UndoRedoChanged { can_undo, can_redo });
208                }
209                inner.queue_event(DocumentEvent::LongOperationFinished {
210                    operation_id: op_id,
211                    success: true,
212                    error: None,
213                });
214            }
215        });
216
217        // Cancelled
218        let w = weak.clone();
219        let cancelled_tok = client.subscribe(Origin::LongOperation(LOE::Cancelled), move |event| {
220            if let Some(inner) = w.upgrade() {
221                let op_id = parse_id_data(&event.data);
222                let mut inner = inner.lock();
223                if !inner.owns_operation(&op_id) {
224                    return;
225                }
226                inner.own_operations.remove(&op_id);
227                inner.history_resets.remove(&op_id);
228                inner.queue_event(DocumentEvent::LongOperationFinished {
229                    operation_id: op_id,
230                    success: false,
231                    error: Some("cancelled".into()),
232                });
233            }
234        });
235
236        // Failed
237        let failed_tok = client.subscribe(Origin::LongOperation(LOE::Failed), move |event| {
238            if let Some(inner) = weak.upgrade() {
239                let (op_id, error) = parse_failed_data(&event.data);
240                let mut inner = inner.lock();
241                if !inner.owns_operation(&op_id) {
242                    return;
243                }
244                inner.own_operations.remove(&op_id);
245                inner.history_resets.remove(&op_id);
246                inner.queue_event(DocumentEvent::LongOperationFinished {
247                    operation_id: op_id,
248                    success: false,
249                    error: Some(error),
250                });
251            }
252        });
253
254        locked.long_op_subscriptions.extend([
255            progress_tok,
256            completed_tok,
257            cancelled_tok,
258            failed_tok,
259        ]);
260    }
261
262    // ── Whole-document content ────────────────────────────────
263
264    /// Replace the entire document with plain text. Clears undo history.
265    pub fn set_plain_text(&self, text: &str) -> Result<()> {
266        let _settled = self.settle_transient_edits();
267        let queued = {
268            let mut inner = self.inner.lock();
269            let dto = frontend::document_io::ImportPlainTextDto {
270                plain_text: text.into(),
271            };
272            document_io_commands::import_plain_text(&inner.ctx, &dto)?;
273            undo_redo_commands::clear_stack(&inner.ctx, inner.stack_id);
274            inner.invalidate_text_cache();
275            inner.rehighlight_all();
276            inner.queue_event(DocumentEvent::DocumentReset);
277            inner.check_block_count_changed();
278            inner.reset_cached_child_order();
279            inner.queue_event(DocumentEvent::UndoRedoChanged {
280                can_undo: false,
281                can_redo: false,
282            });
283            inner.take_queued_events()
284        };
285        crate::inner::dispatch_queued_events(queued);
286        Ok(())
287    }
288
289    /// Export the entire document as plain text, in reading order.
290    ///
291    /// This is the **human-readable** view: prose only. Embedded objects (a table) contribute
292    /// their content but not the `U+FFFC` anchor the document holds where they sit — which is
293    /// what you want for a `cat`-style export, and is why the crate's fast path bails the
294    /// moment a table exists.
295    ///
296    /// **Do not compute offsets from this string.** It is deliberately not
297    /// character-for-character the text a search runs against: that text carries the object
298    /// anchors, so a position taken here is short by two characters per preceding table. For
299    /// an addressable view — one whose offsets [`find_all`](Self::find_all),
300    /// [`replace_text`](Self::replace_text), a block's
301    /// [`position()`](crate::TextBlock::position) and a cursor all agree with — use
302    /// [`to_addressable_text`](Self::to_addressable_text) on a live document, or
303    /// [`djot_to_plain_text`](crate::djot_to_plain_text) when all you hold is Djot source.
304    ///
305    /// The two are allowed to differ in that one respect and no other; in particular they
306    /// agree on **order**. They did not always: this export used to hoist every blockquote's
307    /// prose to the end of the document (`"> a0\n\na"` came back as `"a\na0"`), because it
308    /// concatenated frames in creation order instead of sorting all blocks by
309    /// `document_position`. See `plain_text_order_tests`.
310    pub fn to_plain_text(&self) -> Result<String> {
311        let mut inner = self.inner.lock();
312        Ok(inner.plain_text()?.into_owned())
313    }
314
315    /// [`to_plain_text`](Self::to_plain_text) for writing an actual `.txt` file: quoted
316    /// blocks are indented four spaces per blockquote level, so an epigraph or a block
317    /// quotation still reads as set-off matter in a format with no markup to say so.
318    ///
319    /// **Not** interchangeable with [`to_plain_text`](Self::to_plain_text), and not cached.
320    /// That one is pinned to the document's addressable text — the text
321    /// [`find_all`](Self::find_all) and [`replace_text`](Self::replace_text) compute
322    /// offsets against — in everything but the object anchors, so indenting it would shift
323    /// every offset inside a quote and desynchronise search from the document. Use this
324    /// only for output nobody addresses back into the document.
325    pub fn to_plain_text_indented(&self) -> Result<String> {
326        let inner = self.inner.lock();
327        let dto = document_io_commands::export_plain_text_indented(&inner.ctx)?;
328        Ok(dto.plain_text)
329    }
330
331    /// [`to_plain_text`](Self::to_plain_text) with every presentation option chosen
332    /// explicitly — quoted-block indentation, and a `U+000C` form feed before each block
333    /// that asks to start a new page.
334    ///
335    /// Subject to the same warning as [`to_plain_text_indented`](Self::to_plain_text_indented):
336    /// anything other than [`PlainTextExportOptions::addressable`] shifts offsets, so this is
337    /// for files being written out, never for text anyone addresses back into the document.
338    pub fn to_plain_text_with(&self, options: PlainTextExportOptions) -> Result<String> {
339        let inner = self.inner.lock();
340        let dto = document_io_commands::export_plain_text_with(&inner.ctx, options)?;
341        Ok(dto.plain_text)
342    }
343
344    /// The document's **addressable text**: the exact string every offset this document
345    /// deals out is an index into.
346    ///
347    /// One char space runs through the whole API — [`find_all`](Self::find_all) match
348    /// positions, [`replace_ranges`](Self::replace_ranges) ranges, a block's
349    /// [`position()`](crate::TextBlock::position), a cursor, an editor widget's selection.
350    /// This is the string that space addresses, character for character: an embedded
351    /// table occupies its `U+FFFC` [`TABLE_ANCHOR`](crate::TABLE_ANCHOR) here (plus its
352    /// `\n` separator), exactly as the document holds it.
353    ///
354    /// Use it whenever a document offset and a document string travel together — capturing
355    /// the quoted text under a selection, pairing block starts with the text they index,
356    /// slicing context around a search hit. Pairing an offset with
357    /// [`to_plain_text`](Self::to_plain_text) instead is the classic form of this bug: that
358    /// is the human-readable **export**, it omits the anchors, and every offset after a
359    /// table lands two characters off in it.
360    ///
361    /// Built by the same code path [`find_all`](Self::find_all) uses to build the text it
362    /// searches, so the two cannot diverge. For the same view of bare Djot source — no live
363    /// document at hand — use [`djot_to_plain_text`](crate::djot_to_plain_text), which is
364    /// pinned to produce this very string for the same content. Not cached; it is a fresh
365    /// read of the document each call.
366    pub fn to_addressable_text(&self) -> Result<String> {
367        let inner = self.inner.lock();
368        let dto = document_search_commands::addressable_text(&inner.ctx)?;
369        Ok(dto.text)
370    }
371
372    /// Replace the entire document with Markdown. Clears undo history once the new content
373    /// is in (see [`set_djot`](Self::set_djot)).
374    ///
375    /// This is a **long operation**. Returns a typed [`Operation`] handle.
376    pub fn set_markdown(&self, markdown: &str) -> Result<Operation<MarkdownImportResult>> {
377        let _settled = self.settle_transient_edits();
378        let mut inner = self.inner.lock();
379        inner.invalidate_text_cache();
380        let dto = frontend::document_io::ImportMarkdownDto {
381            markdown_text: markdown.into(),
382        };
383        let op_id = document_io_commands::import_markdown(&inner.ctx, &dto)?;
384        inner.own_operations.insert(op_id.clone());
385        let read = clearing_history_on_success(&self.inner, &mut inner, &op_id, |ctx, id| {
386            document_io_commands::get_import_markdown_result(ctx, id)
387                .ok()
388                .flatten()
389                .map(|r| {
390                    Ok(MarkdownImportResult {
391                        block_count: to_usize(r.block_count),
392                    })
393                })
394        });
395        Ok(Operation::new(op_id, &inner.ctx, read))
396    }
397
398    /// Export the entire document as Markdown.
399    pub fn to_markdown(&self) -> Result<String> {
400        let inner = self.inner.lock();
401        let dto = document_io_commands::export_markdown(&inner.ctx)?;
402        Ok(dto.markdown_text)
403    }
404
405    /// [`to_markdown`](Self::to_markdown) with the presentation opt-ins — today, whether a
406    /// block that asks to start a new page gets a raw-HTML page break emitted above it.
407    /// Off by default, because raw HTML is not Markdown.
408    pub fn to_markdown_with(&self, options: MarkdownExportOptions) -> Result<String> {
409        let inner = self.inner.lock();
410        let dto = document_io_commands::export_markdown_with(&inner.ctx, options)?;
411        Ok(dto.markdown_text)
412    }
413
414    /// Replace the entire document with djot markup. Clears undo history.
415    ///
416    /// This is a **long operation**. Returns a typed [`Operation`] handle. The history is
417    /// cleared once the new content is in, by the first of these to happen: a read of the
418    /// operation's result ([`Operation::wait`], [`Operation::try_result`]), or the
419    /// completion reaching this document, which also announces
420    /// [`DocumentEvent::UndoRedoChanged`]. So [`can_undo`](Self::can_undo) is `false` as
421    /// soon as `wait` returns, and an edit made after that keeps its own entry. A load that
422    /// fails or is cancelled leaves the history as it was.
423    pub fn set_djot(&self, djot: &str) -> Result<Operation<DjotImportResult>> {
424        self.set_djot_with_options(djot, DjotImportOptions::default())
425    }
426
427    /// Replace the entire document with djot markup, selecting which optional
428    /// block attributes (alignment, line height, direction, non-breakable
429    /// lines, background color) are applied via `options`. Clears undo history
430    /// once the new content is in (see [`set_djot`](Self::set_djot)).
431    ///
432    /// This is a **long operation**. Returns a typed [`Operation`] handle.
433    pub fn set_djot_with_options(
434        &self,
435        djot: &str,
436        options: DjotImportOptions,
437    ) -> Result<Operation<DjotImportResult>> {
438        let _settled = self.settle_transient_edits();
439        let mut inner = self.inner.lock();
440        inner.invalidate_text_cache();
441        let dto = frontend::document_io::ImportDjotDto {
442            djot_text: djot.into(),
443            options,
444        };
445        let op_id = document_io_commands::import_djot(&inner.ctx, &dto)?;
446        inner.own_operations.insert(op_id.clone());
447        let read = clearing_history_on_success(&self.inner, &mut inner, &op_id, |ctx, id| {
448            document_io_commands::get_import_djot_result(ctx, id)
449                .ok()
450                .flatten()
451                .map(|r| {
452                    Ok(DjotImportResult {
453                        block_count: to_usize(r.block_count),
454                    })
455                })
456        });
457        Ok(Operation::new(op_id, &inner.ctx, read))
458    }
459
460    /// Replace the entire document with djot markup, **synchronously**, on the
461    /// calling thread. Clears undo history.
462    ///
463    /// This is the right call for *loading* a document's initial content — the
464    /// case where the caller is going to block for the result anyway.
465    /// [`set_djot`](Self::set_djot) starts a long operation: it spawns a thread,
466    /// and the caller then blocks in [`Operation::wait`] until that thread
467    /// publishes. That round trip is pure overhead when there is no frame loop to
468    /// keep responsive, and it does not shrink with the input — an *empty*
469    /// document costs the same thread spawn and hand-off as a full one. Loading N
470    /// documents in a loop paid it N times.
471    ///
472    /// Prefer [`set_djot`](Self::set_djot) when the import is genuinely long and
473    /// the caller must stay responsive (it reports progress and can be
474    /// cancelled); prefer this when the caller just wants the content in.
475    ///
476    /// Observationally equivalent to `set_djot(..).wait()`: same import, same
477    /// `DocumentReset`, same cache/block bookkeeping, same cleared history. Having no
478    /// operation, it emits no `LongOperation*` events and cannot be cancelled.
479    pub fn set_djot_sync(&self, djot: &str) -> Result<DjotImportResult> {
480        self.set_djot_sync_with_options(djot, DjotImportOptions::default())
481    }
482
483    /// As [`set_djot_sync`](Self::set_djot_sync), selecting which optional block
484    /// attributes are applied via `options`.
485    pub fn set_djot_sync_with_options(
486        &self,
487        djot: &str,
488        options: DjotImportOptions,
489    ) -> Result<DjotImportResult> {
490        let _settled = self.settle_transient_edits();
491        let (queued, block_count) = {
492            let mut inner = self.inner.lock();
493            inner.invalidate_text_cache();
494            let dto = frontend::document_io::ImportDjotDto {
495                djot_text: djot.into(),
496                options,
497            };
498            let result = document_io_commands::import_djot_sync(&inner.ctx, &dto)?;
499            // The history held edits of the content just replaced: undoing one of
500            // them put that content back over the load. Cleared as `set_plain_text`
501            // clears it.
502            undo_redo_commands::clear_stack(&inner.ctx, inner.stack_id);
503            // The same settling the async path performs when its operation
504            // completes (see `subscribe_long_operation_events`), done inline here
505            // because there is no completion event to hang it off.
506            inner.queue_event(DocumentEvent::DocumentReset);
507            inner.check_block_count_changed();
508            inner.reset_cached_child_order();
509            inner.queue_event(DocumentEvent::UndoRedoChanged {
510                can_undo: false,
511                can_redo: false,
512            });
513            (inner.take_queued_events(), result.block_count)
514        };
515        // Dispatch outside the lock — a subscriber is free to call back in.
516        crate::inner::dispatch_queued_events(queued);
517        Ok(DjotImportResult {
518            block_count: to_usize(block_count),
519        })
520    }
521
522    /// Export the entire document as djot markup.
523    pub fn to_djot(&self) -> Result<String> {
524        self.to_djot_with_options(DjotExportOptions::default())
525    }
526
527    /// Export the entire document as djot markup, selecting which optional block
528    /// attributes (alignment, line height, direction, non-breakable lines,
529    /// background color) are emitted via `options`.
530    pub fn to_djot_with_options(&self, options: DjotExportOptions) -> Result<String> {
531        let inner = self.inner.lock();
532        let dto = document_io_commands::export_djot(&inner.ctx, &options)?;
533        Ok(dto.djot_text)
534    }
535
536    /// Replace the entire document with HTML. Clears undo history once the new content is
537    /// in (see [`set_djot`](Self::set_djot)).
538    ///
539    /// This is a **long operation**. Returns a typed [`Operation`] handle.
540    pub fn set_html(&self, html: &str) -> Result<Operation<HtmlImportResult>> {
541        let _settled = self.settle_transient_edits();
542        let mut inner = self.inner.lock();
543        inner.invalidate_text_cache();
544        let dto = frontend::document_io::ImportHtmlDto {
545            html_text: html.into(),
546        };
547        let op_id = document_io_commands::import_html(&inner.ctx, &dto)?;
548        inner.own_operations.insert(op_id.clone());
549        let read = clearing_history_on_success(&self.inner, &mut inner, &op_id, |ctx, id| {
550            document_io_commands::get_import_html_result(ctx, id)
551                .ok()
552                .flatten()
553                .map(|r| {
554                    Ok(HtmlImportResult {
555                        block_count: to_usize(r.block_count),
556                    })
557                })
558        });
559        Ok(Operation::new(op_id, &inner.ctx, read))
560    }
561
562    /// Export the entire document as HTML.
563    ///
564    /// Inline images keep whatever `src` the document stores; placing the files
565    /// those point at is the caller's business. Use
566    /// [`to_html_with_options`](Self::to_html_with_options) to inline them
567    /// instead, or to drop them.
568    pub fn to_html(&self) -> Result<String> {
569        let inner = self.inner.lock();
570        let dto = document_io_commands::export_html(&inner.ctx)?;
571        Ok(dto.html_text)
572    }
573
574    /// Export as HTML, choosing how inline images are represented.
575    pub fn to_html_with_options(&self, options: HtmlExportOptions) -> Result<String> {
576        let inner = self.inner.lock();
577        let dto = document_io_commands::export_html_with_options(&inner.ctx, options)?;
578        Ok(dto.html_text)
579    }
580
581    /// Export the entire document as LaTeX.
582    ///
583    /// Images are emitted as `\includegraphics{src}`, which LaTeX resolves
584    /// against the filesystem at compile time — so the caller is responsible for
585    /// placing those files beside the `.tex`. Use
586    /// [`to_latex_with_options`](Self::to_latex_with_options) to drop them
587    /// instead.
588    pub fn to_latex(&self, document_class: &str, include_preamble: bool) -> Result<String> {
589        self.to_latex_with_options(crate::LatexExportOptions {
590            document_class: document_class.into(),
591            include_preamble,
592            omit_images: false,
593        })
594    }
595
596    /// As [`to_latex`](Self::to_latex), but taking the full
597    /// [`LatexExportOptions`](crate::LatexExportOptions) — the same document class and preamble
598    /// knobs `to_latex` takes positionally, plus the choice of dropping inline images instead of
599    /// emitting `\includegraphics{…}` for them.
600    pub fn to_latex_with_options(&self, options: crate::LatexExportOptions) -> Result<String> {
601        let inner = self.inner.lock();
602        let dto = frontend::document_io::ExportLatexDto { options };
603        let result = document_io_commands::export_latex(&inner.ctx, &dto)?;
604        Ok(result.latex_text)
605    }
606
607    /// Export the entire document as DOCX to a file path.
608    ///
609    /// This is a **long operation**. Returns a typed [`Operation`] handle.
610    ///
611    /// Requires the `docx` cargo feature on `text-document` (on by default). Without it this
612    /// returns `Err(DocumentError::Unsupported(..))`.
613    pub fn to_docx(&self, output_path: &str) -> Result<Operation<DocxExportResult>> {
614        self.to_docx_with_options(output_path, crate::DocxExportOptions::default())
615    }
616
617    /// As [`to_docx`](Self::to_docx), but with page geometry + base typography overrides — a
618    /// *manuscript* style (page size, margins, body font, line spacing, first-line indent,
619    /// alignment, and an optional page-number header). Per-block RTL is emitted automatically
620    /// from each block's own direction, independent of these options.
621    #[cfg(feature = "docx")]
622    pub fn to_docx_with_options(
623        &self,
624        output_path: &str,
625        options: crate::DocxExportOptions,
626    ) -> Result<Operation<DocxExportResult>> {
627        let mut inner = self.inner.lock();
628        let dto = frontend::document_io::ExportDocxDto {
629            output_path: output_path.into(),
630            options,
631        };
632        let op_id = document_io_commands::export_docx(&inner.ctx, &dto)?;
633        inner.own_operations.insert(op_id.clone());
634        Ok(Operation::new(
635            op_id,
636            &inner.ctx,
637            Box::new(|ctx, id| {
638                document_io_commands::get_export_docx_result(ctx, id)
639                    .ok()
640                    .flatten()
641                    .map(|r| {
642                        Ok(DocxExportResult {
643                            file_path: r.file_path,
644                            paragraph_count: to_usize(r.paragraph_count),
645                        })
646                    })
647            }),
648        ))
649    }
650
651    /// As [`to_docx`](Self::to_docx), when the `docx` cargo feature was not enabled at compile
652    /// time: returns [`DocumentError::Unsupported`] immediately, without starting an operation.
653    #[cfg(not(feature = "docx"))]
654    pub fn to_docx_with_options(
655        &self,
656        _output_path: &str,
657        _options: crate::DocxExportOptions,
658    ) -> Result<Operation<DocxExportResult>> {
659        Err(DocumentError::Unsupported(
660            "DOCX export requires the `docx` cargo feature on the `text-document` crate".into(),
661        ))
662    }
663
664    /// Export the entire document as an EPUB 3 file to a file path.
665    ///
666    /// This is a **long operation**. Returns a typed [`Operation`] handle.
667    ///
668    /// Requires the `epub` cargo feature on `text-document` (on by default). Without it this
669    /// returns `Err(DocumentError::Unsupported(..))`.
670    pub fn to_epub(&self, output_path: &str) -> Result<Operation<EpubExportResult>> {
671        self.to_epub_with_options(output_path, crate::EpubExportOptions::default())
672    }
673
674    /// As [`to_epub`](Self::to_epub), but with book-level metadata (title, author, language,
675    /// reading direction). The document is split into chapters at the shallowest heading level
676    /// present (e.g. every top-level `# Chapter` heading) — see
677    /// [`EpubExportOptions`](crate::EpubExportOptions) for details.
678    #[cfg(feature = "epub")]
679    pub fn to_epub_with_options(
680        &self,
681        output_path: &str,
682        options: crate::EpubExportOptions,
683    ) -> Result<Operation<EpubExportResult>> {
684        let mut inner = self.inner.lock();
685        let dto = frontend::document_io::ExportEpubDto {
686            output_path: output_path.into(),
687            options,
688        };
689        let op_id = document_io_commands::export_epub(&inner.ctx, &dto)?;
690        inner.own_operations.insert(op_id.clone());
691        Ok(Operation::new(
692            op_id,
693            &inner.ctx,
694            Box::new(|ctx, id| {
695                document_io_commands::get_export_epub_result(ctx, id)
696                    .ok()
697                    .flatten()
698                    .map(|r| {
699                        Ok(EpubExportResult {
700                            file_path: r.file_path,
701                            chapter_count: to_usize(r.chapter_count),
702                        })
703                    })
704            }),
705        ))
706    }
707
708    /// As [`to_epub`](Self::to_epub), when the `epub` cargo feature was not enabled at compile
709    /// time: returns [`DocumentError::Unsupported`] immediately, without starting an operation.
710    #[cfg(not(feature = "epub"))]
711    pub fn to_epub_with_options(
712        &self,
713        _output_path: &str,
714        _options: crate::EpubExportOptions,
715    ) -> Result<Operation<EpubExportResult>> {
716        Err(DocumentError::Unsupported(
717            "EPUB export requires the `epub` cargo feature on the `text-document` crate".into(),
718        ))
719    }
720
721    /// Export the entire document as ODT (OpenDocument Text) to a file path.
722    ///
723    /// This is a **long operation**. Returns a typed [`Operation`] handle.
724    ///
725    /// Requires the `odt` cargo feature on `text-document` (on by default). Without it this
726    /// returns `Err(DocumentError::Unsupported(..))`.
727    pub fn to_odt(&self, output_path: &str) -> Result<Operation<OdtExportResult>> {
728        self.to_odt_with_options(output_path, crate::OdtExportOptions::default())
729    }
730
731    /// As [`to_odt`](Self::to_odt), but with page geometry + base typography overrides — the ODT
732    /// analog of [`to_docx_with_options`](Self::to_docx_with_options), same units and same
733    /// per-block-RTL-is-automatic behaviour (see [`OdtExportOptions`](crate::OdtExportOptions)'s
734    /// own doc comment).
735    #[cfg(feature = "odt")]
736    pub fn to_odt_with_options(
737        &self,
738        output_path: &str,
739        options: crate::OdtExportOptions,
740    ) -> Result<Operation<OdtExportResult>> {
741        let mut inner = self.inner.lock();
742        let dto = frontend::document_io::ExportOdtDto {
743            output_path: output_path.into(),
744            options,
745        };
746        let op_id = document_io_commands::export_odt(&inner.ctx, &dto)?;
747        inner.own_operations.insert(op_id.clone());
748        Ok(Operation::new(
749            op_id,
750            &inner.ctx,
751            Box::new(|ctx, id| {
752                document_io_commands::get_export_odt_result(ctx, id)
753                    .ok()
754                    .flatten()
755                    .map(|r| {
756                        Ok(OdtExportResult {
757                            file_path: r.file_path,
758                            paragraph_count: to_usize(r.paragraph_count),
759                        })
760                    })
761            }),
762        ))
763    }
764
765    /// As [`to_odt`](Self::to_odt), when the `odt` cargo feature was not enabled at compile
766    /// time: returns [`DocumentError::Unsupported`] immediately, without starting an operation.
767    #[cfg(not(feature = "odt"))]
768    pub fn to_odt_with_options(
769        &self,
770        _output_path: &str,
771        _options: crate::OdtExportOptions,
772    ) -> Result<Operation<OdtExportResult>> {
773        Err(DocumentError::Unsupported(
774            "ODT export requires the `odt` cargo feature on the `text-document` crate".into(),
775        ))
776    }
777
778    /// Export the entire document as a PDF file, using the given options (page geometry,
779    /// typography, embedded font bytes, base language/direction).
780    ///
781    /// This is a **long operation**. Returns a typed [`Operation`] handle.
782    ///
783    /// Requires the `pdf` cargo feature on `text-document` (which forwards to `frontend`'s and
784    /// `document_io`'s own `pdf` features). If it was not enabled at compile time, this returns
785    /// `Err(DocumentError::Unsupported(..))` immediately rather than attempting the export — no
786    /// `#[cfg]` is needed at the call site either way.
787    pub fn to_pdf(
788        &self,
789        output_path: &str,
790        options: crate::PdfExportOptions,
791    ) -> Result<Operation<PdfExportResult>> {
792        self.to_pdf_with_options(output_path, options)
793    }
794
795    /// As [`to_pdf`](Self::to_pdf) — the two are identical; `to_pdf` is the plain entry point,
796    /// `to_pdf_with_options` exists (like [`to_docx_with_options`](Self::to_docx_with_options)
797    /// and [`to_epub_with_options`](Self::to_epub_with_options)) so the naming stays consistent
798    /// across the three file-based exporters, all of which take a mandatory options struct.
799    #[cfg(feature = "pdf")]
800    pub fn to_pdf_with_options(
801        &self,
802        output_path: &str,
803        options: crate::PdfExportOptions,
804    ) -> Result<Operation<PdfExportResult>> {
805        let mut inner = self.inner.lock();
806        let dto = frontend::document_io::ExportPdfDto {
807            output_path: output_path.into(),
808            options,
809        };
810        let op_id = document_io_commands::export_pdf(&inner.ctx, &dto)?;
811        inner.own_operations.insert(op_id.clone());
812        Ok(Operation::new(
813            op_id,
814            &inner.ctx,
815            Box::new(|ctx, id| {
816                document_io_commands::get_export_pdf_result(ctx, id)
817                    .ok()
818                    .flatten()
819                    .map(|r| {
820                        Ok(PdfExportResult {
821                            file_path: r.file_path,
822                            page_count: to_usize(r.page_count),
823                        })
824                    })
825            }),
826        ))
827    }
828
829    /// As [`to_pdf`](Self::to_pdf), when the `pdf` cargo feature was not enabled at compile
830    /// time — returns [`DocumentError::Unsupported`] immediately, without starting an operation
831    /// or touching the backend at all.
832    #[cfg(not(feature = "pdf"))]
833    pub fn to_pdf_with_options(
834        &self,
835        _output_path: &str,
836        _options: crate::PdfExportOptions,
837    ) -> Result<Operation<PdfExportResult>> {
838        Err(DocumentError::Unsupported(
839            "PDF export requires the `pdf` cargo feature on the `text-document` crate".into(),
840        ))
841    }
842
843    /// Clear all document content and reset to an empty state.
844    pub fn clear(&self) -> Result<()> {
845        let _settled = self.settle_transient_edits();
846        let queued = {
847            let mut inner = self.inner.lock();
848            let dto = frontend::document_io::ImportPlainTextDto {
849                plain_text: String::new(),
850            };
851            document_io_commands::import_plain_text(&inner.ctx, &dto)?;
852            undo_redo_commands::clear_stack(&inner.ctx, inner.stack_id);
853            inner.invalidate_text_cache();
854            inner.rehighlight_all();
855            inner.queue_event(DocumentEvent::DocumentReset);
856            inner.check_block_count_changed();
857            inner.reset_cached_child_order();
858            inner.queue_event(DocumentEvent::UndoRedoChanged {
859                can_undo: false,
860                can_redo: false,
861            });
862            inner.take_queued_events()
863        };
864        crate::inner::dispatch_queued_events(queued);
865        Ok(())
866    }
867
868    // ── Cursor factory ───────────────────────────────────────
869
870    /// Create a cursor at position 0.
871    pub fn cursor(&self) -> TextCursor {
872        self.cursor_at(0)
873    }
874
875    /// Create a cursor at the given position. If `position` falls
876    /// inside an extended grapheme cluster (decomposed accents, ZWJ
877    /// emoji, skin-tone sequences, flag pairs), the cursor snaps
878    /// forward to the end of the containing cluster so subsequent
879    /// `NextCharacter`/`PreviousCharacter` round-trips remain identity.
880    pub fn cursor_at(&self, position: usize) -> TextCursor {
881        let data = {
882            let mut inner = self.inner.lock();
883            inner.register_cursor(position)
884        };
885        let cursor = TextCursor {
886            doc: self.inner.clone(),
887            data,
888        };
889        cursor.snap_position_to_grapheme_boundary();
890        cursor
891    }
892
893    // ── Document queries ─────────────────────────────────────
894
895    /// Get document statistics. O(1) — reads cached values.
896    pub fn stats(&self) -> DocumentStats {
897        let inner = self.inner.lock();
898        let dto = document_inspection_commands::get_document_stats(&inner.ctx)
899            .expect("get_document_stats should not fail");
900        DocumentStats::from(&dto)
901    }
902
903    /// Tell the document what each footnote label should print.
904    ///
905    /// Presentation only: never stored, never exported, never part of the text. A
906    /// reference occupies one character whatever its marker says.
907    ///
908    /// Set it when the numbers are a fact about something larger than this
909    /// document — a host compiling one chapter of a book knows the chapter's notes
910    /// continue a sequence this document cannot see. Leave it unset and the
911    /// document numbers its own references in reading order, which is right when
912    /// the document *is* the whole text.
913    /// Storing the map is only half of it: a marker is **shaped text**, so a
914    /// document already laid out keeps drawing the old one until something tells
915    /// it to reshape. Nothing else will — the map is presentation state and
916    /// changing it edits no block, so it emits no edit event of its own. Without
917    /// the notification below, a host that numbers a note the instant it is
918    /// created watches the raw label sit in the writer's prose until an unrelated
919    /// keystroke happens to force a relayout.
920    ///
921    /// `FormatChanged` over the whole document rather than a paint-only event:
922    /// the marker's width changes with its text (`9` and `10` are not the same
923    /// size), so the line has to be reshaped, not recoloured. Guarded on the map
924    /// actually differing, because a host pushes this on every refresh and a
925    /// full relayout per keystroke is not a thing to do by accident.
926    pub fn set_footnote_markers(&self, markers: std::collections::HashMap<String, String>) {
927        let queued = {
928            let mut inner = self.inner.lock();
929            {
930                let store = inner.ctx.db_context.get_store();
931                let mut current = store.footnote_markers.write();
932                if *current == markers {
933                    return;
934                }
935                *current = markers;
936            }
937            inner.queue_event(DocumentEvent::FormatChanged {
938                position: 0,
939                length: 0,
940                kind: crate::flow::FormatChangeKind::Character,
941            });
942            inner.take_queued_events()
943        };
944        crate::inner::dispatch_queued_events(queued);
945    }
946
947    /// Every footnote reference in the document, as `(position, label)`, in
948    /// reading order.
949    ///
950    /// The seam a host uses to tie its own note storage to the prose: Skribisto
951    /// keeps note bodies in its store, so what it needs from the document is
952    /// only *where* the references are and *which* note each names.
953    ///
954    /// Positions are document-absolute character offsets — the same space a
955    /// cursor and a search hit use — so a caller can go straight from a caret to
956    /// the note under it without a second lookup.
957    pub fn footnote_references(&self) -> Vec<(usize, String)> {
958        let inner = self.inner.lock();
959        let store = inner.ctx.db_context.get_store();
960
961        let refs = store.block_footnote_refs.read();
962        if refs.is_empty() {
963            return Vec::new();
964        }
965
966        // Block order, then byte order within a block — the order they are read.
967        // Where a block starts is read from the rope: the stored field lags it by
968        // whatever was typed since something last wrote it, which reported every
969        // reference after an edit at a position the reference was not at.
970        let mut blocks: Vec<(i64, u64)> = store
971            .blocks
972            .read()
973            .values()
974            .map(|b| (b.document_position, b.id))
975            .collect();
976        frontend::common::database::rope_helpers::refresh_positions_from_rope(
977            store,
978            blocks.iter_mut().map(|(position, id)| (*id, position)),
979        );
980        blocks.sort_unstable();
981
982        let mut out = Vec::new();
983        for (position, block_id) in blocks {
984            let Some(anchors) = refs.get(&block_id) else {
985                continue;
986            };
987            let Some(block) = store.blocks.read().get(&block_id).cloned() else {
988                continue;
989            };
990            let text =
991                frontend::common::database::rope_helpers::block_content_via_store(&block, store);
992            let mut ordered: Vec<_> = anchors.iter().collect();
993            ordered.sort_by_key(|a| a.byte_offset);
994            for anchor in ordered {
995                // Byte offset within the block → character offset within the
996                // document. The two differ the moment the block holds anything
997                // outside ASCII, which for prose is immediately.
998                let chars_before = text
999                    .get(..anchor.byte_offset as usize)
1000                    .map(|s| s.chars().count())
1001                    .unwrap_or(0);
1002                out.push((position as usize + chars_before, anchor.label.clone()));
1003            }
1004        }
1005        out
1006    }
1007
1008    /// The label of the footnote reference at `position`, if one sits there.
1009    ///
1010    /// What "the caret is on a footnote" means, for a host wiring a two-way
1011    /// selection between its notes list and the prose.
1012    pub fn footnote_reference_at(&self, position: usize) -> Option<String> {
1013        self.footnote_references()
1014            .into_iter()
1015            .find(|(at, _)| *at == position)
1016            .map(|(_, label)| label)
1017    }
1018
1019    /// Whether this document was built inside a [`DocumentBackend`], rather than
1020    /// standing alone with an event hub and a drain thread of its own.
1021    ///
1022    /// The question a host asks of its own wiring. Documents it means to keep for
1023    /// the life of a project — a comment body, a footnote body, one per row of a
1024    /// stream — belong in a shared backend, and one built with
1025    /// [`TextDocument::new`] instead is indistinguishable in use while costing an
1026    /// OS thread that will never have anything to deliver. Nothing else reports
1027    /// that, so nothing else can test for it.
1028    ///
1029    /// [`DocumentBackend`]: crate::DocumentBackend
1030    pub fn shares_a_backend(&self) -> bool {
1031        self.inner.lock().backend.is_some()
1032    }
1033
1034    /// Get the total character count. One entity read, and no document walk.
1035    ///
1036    /// It reads the count the `Document` entity carries, through
1037    /// `crate::inner::document_counts`. It used to go through
1038    /// `get_document_stats`, which returns the same number and then walks every
1039    /// block materialising its text for the word count in the same DTO — so this
1040    /// call, which a host may make once per widget per layout pass, cost a
1041    /// complete scan of the document. `stats()` still pays that walk, and should:
1042    /// it is the caller that asked for the word count.
1043    pub fn character_count(&self) -> usize {
1044        let inner = self.inner.lock();
1045        crate::inner::document_counts(&inner).map_or(0, |(chars, _)| chars)
1046    }
1047
1048    /// Get the number of blocks (paragraphs). One entity read, and no document
1049    /// walk. See [`character_count`](Self::character_count) for what that
1050    /// replaced.
1051    pub fn block_count(&self) -> usize {
1052        let inner = self.inner.lock();
1053        crate::inner::document_counts(&inner).map_or(0, |(_, blocks)| blocks)
1054    }
1055
1056    /// Returns true if the document has no text content.
1057    pub fn is_empty(&self) -> bool {
1058        self.character_count() == 0
1059    }
1060
1061    /// Get text at a position for a given length.
1062    pub fn text_at(&self, position: usize, length: usize) -> Result<String> {
1063        let inner = self.inner.lock();
1064        let dto = frontend::document_inspection::GetTextAtPositionDto {
1065            position: to_i64(position),
1066            length: to_i64(length),
1067        };
1068        let result = document_inspection_commands::get_text_at_position(&inner.ctx, &dto)?;
1069        Ok(result.text)
1070    }
1071
1072    /// Find the inline segment containing `position` and return its
1073    /// stable element id (synthesized from `(block_id, byte_start)`
1074    /// via [`common::format_runs::synth_element_id`]) together with the
1075    /// segment's absolute start position and the character offset of
1076    /// `position` within the segment. Used by accessibility layers to
1077    /// convert a document-absolute character position into the
1078    /// `(element_id, character_index_in_run)` coordinate space
1079    /// AccessKit's `TextPosition` expects.
1080    ///
1081    /// Returns `None` when the position is outside the document.
1082    /// Returns the element at position `position - 1` when `position`
1083    /// falls exactly on an element boundary, matching the "cursor
1084    /// belongs to the preceding element at a boundary" convention
1085    /// used throughout text-document.
1086    pub fn find_element_at_position(&self, position: usize) -> Option<(u64, usize, usize)> {
1087        // Caret semantics, per the boundary convention documented just above: with the
1088        // character-index `block_at`, a position at the end of a paragraph resolved to the
1089        // *next* block and the `checked_sub` below then failed, so the last element of every
1090        // paragraph was unreachable.
1091        let block_info = self.block_at_caret(position).ok()?;
1092        let block_start = block_info.start;
1093        let offset_in_block = position.checked_sub(block_start)?;
1094        let block = crate::text_block::TextBlock {
1095            doc: std::sync::Arc::clone(&self.inner),
1096            block_id: block_info.block_id,
1097        };
1098        let frags = block.fragments();
1099        // Walk fragments; match the fragment that contains
1100        // `offset_in_block`. For a boundary position shared with the
1101        // next fragment, prefer the preceding fragment (boundary
1102        // belongs to the end of the previous element).
1103        let mut last_text: Option<(u64, usize, usize, usize)> = None; // (id, abs_start, frag_offset, frag_length)
1104        for frag in &frags {
1105            match frag {
1106                crate::flow::FragmentContent::Text {
1107                    offset,
1108                    length,
1109                    element_id,
1110                    ..
1111                } => {
1112                    let frag_start = *offset;
1113                    let frag_end = frag_start + *length;
1114                    if offset_in_block >= frag_start && offset_in_block < frag_end {
1115                        let abs_start = block_start + frag_start;
1116                        let offset_within = offset_in_block - frag_start;
1117                        return Some((*element_id, abs_start, offset_within));
1118                    }
1119                    // Record as a candidate for the "end-of-element"
1120                    // boundary fallback (offset_in_block == frag_end).
1121                    if offset_in_block == frag_end {
1122                        last_text =
1123                            Some((*element_id, block_start + frag_start, frag_start, *length));
1124                    }
1125                }
1126                // Both objects occupy exactly one position and answer for it
1127                // whole — there is no offset *inside* either to report.
1128                crate::flow::FragmentContent::Image {
1129                    offset, element_id, ..
1130                }
1131                | crate::flow::FragmentContent::FootnoteReference {
1132                    offset, element_id, ..
1133                } => {
1134                    if offset_in_block == *offset {
1135                        return Some((*element_id, block_start + offset, 0));
1136                    }
1137                }
1138            }
1139        }
1140        // Boundary fallback: position was at the end of the last text
1141        // fragment we saw.
1142        last_text.map(|(id, abs_start, _, length)| (id, abs_start, length))
1143    }
1144
1145    /// Get info about the block at a position. O(log n).
1146    ///
1147    /// `position` is read as a **character index**, so the inter-block separator belongs to
1148    /// the block that *follows* it: in `"abc\ndef"`, position 3 is the newline and reports the
1149    /// second block. For a **caret** offset — where 3 means "after the c", the last place the
1150    /// caret can sit in the first paragraph — use [`block_at_caret`](Self::block_at_caret).
1151    pub fn block_at(&self, position: usize) -> Result<BlockInfo> {
1152        let inner = self.inner.lock();
1153        let dto = frontend::document_inspection::GetBlockAtPositionDto {
1154            position: to_i64(position),
1155        };
1156        let result = document_inspection_commands::get_block_at_position(&inner.ctx, &dto)?;
1157        Ok(BlockInfo::from(&result))
1158    }
1159
1160    /// The block a **caret** at `position` sits in. O(log n).
1161    ///
1162    /// Differs from [`block_at`](Self::block_at) at exactly one place: the end of a paragraph.
1163    /// A character index and a caret offset disagree there — the character at that index is the
1164    /// separator, which belongs to the next block, but a caret there is still in the paragraph
1165    /// it just finished typing. `block_at` answers the first question (and callers that walk
1166    /// text depend on it — moving the caret across a separator, reading the character under an
1167    /// offset); this answers the second.
1168    ///
1169    /// Ask this one whenever the position came from a cursor. Asking `block_at` instead is why
1170    /// the caret-band highlight lit the *next* paragraph the moment the caret reached the end of
1171    /// one.
1172    pub fn block_at_caret(&self, position: usize) -> Result<BlockInfo> {
1173        let inner = self.inner.lock();
1174        let info = crate::inner::block_at_caret_dto(&inner.ctx, position)?;
1175        Ok(BlockInfo::from(&info))
1176    }
1177
1178    /// The sentence containing `position`, as absolute char offsets `(start, end)` — the
1179    /// granularity between [`word`](TextCursor::select) and [`block_at`](Self::block_at).
1180    ///
1181    /// `content_locale` is a BCP-47-ish tag (`"en"`, `"en-US"`, `"pt_BR"`) naming the language
1182    /// the text is written in. It selects the sentence tailoring for that language —
1183    /// abbreviations that do not end a sentence, French spaced guillemets, the Greek question
1184    /// mark. Pass it **fresh on every call**, like [`FindOptions::language`](crate::FindOptions):
1185    /// only the caller knows what language the text is in, and it is not document state.
1186    /// `None`, or a language with no tailoring, falls back to plain UAX #29.
1187    ///
1188    /// A sentence never crosses a block: a paragraph break always ends one. Returns `None` when
1189    /// the block holds no sentence to point at (empty, or whitespace only). Trailing whitespace
1190    /// is trimmed off the end, so the range covers the sentence and not the gap after it.
1191    ///
1192    /// The trailing edge is inclusive of the caret: a `position` at the very end of the block
1193    /// resolves to the last sentence of *that* block rather than to the first sentence of the
1194    /// next one. `position` is a caret offset, so the block is resolved with
1195    /// [`block_at_caret`](Self::block_at_caret) and not with the character-index
1196    /// [`block_at`](Self::block_at).
1197    pub fn sentence_at(
1198        &self,
1199        position: usize,
1200        content_locale: Option<&str>,
1201    ) -> Option<(usize, usize)> {
1202        // Resolved before the lock: `block_at_caret` takes it itself.
1203        let block = self.block_at_caret(position).ok()?;
1204        let inner = self.inner.lock();
1205        let block_start = block.start;
1206        let block_length = block.length;
1207        if block_length == 0 {
1208            return None;
1209        }
1210        let text_dto = frontend::document_inspection::GetTextAtPositionDto {
1211            position: to_i64(block_start),
1212            length: to_i64(block_length),
1213        };
1214        let text = document_inspection_commands::get_text_at_position(&inner.ctx, &text_dto)
1215            .ok()?
1216            .text;
1217        drop(inner);
1218
1219        let offset = position.saturating_sub(block_start);
1220        let (start, end) =
1221            frontend::common::parser_tools::sentence_bounds(&text, offset, content_locale)?;
1222        Some((block_start + start, block_start + end))
1223    }
1224
1225    /// Get the block format at a position.
1226    ///
1227    /// `position` is read with **caret** semantics ([`block_at_caret`](Self::block_at_caret)):
1228    /// at the end of a paragraph this reports that paragraph's format, not the next one's.
1229    /// Formatting queries are asked about a cursor, never about a character index.
1230    pub fn block_format_at(&self, position: usize) -> Result<BlockFormat> {
1231        let inner = self.inner.lock();
1232        let block_info = crate::inner::block_at_caret_dto(&inner.ctx, position)?;
1233        let block_id = block_info.block_id;
1234        let block_id = block_id as u64;
1235        let block_dto = frontend::commands::block_commands::get_block(&inner.ctx, &block_id)?
1236            .ok_or_else(|| DocumentError::NotFound("block not found".into()))?;
1237        Ok(BlockFormat::from(&block_dto))
1238    }
1239
1240    // ── Flow traversal (layout engine API) ─────────────────
1241
1242    /// Walk the main frame's visual flow in document order.
1243    ///
1244    /// Returns the top-level flow elements — blocks, tables, and
1245    /// sub-frames — in the order defined by the main frame's
1246    /// `child_order`. Table cell contents are NOT included here;
1247    /// access them through [`TextTableCell::blocks()`](crate::TextTableCell::blocks).
1248    ///
1249    /// This is the primary entry point for layout initialization.
1250    pub fn flow(&self) -> Vec<crate::flow::FlowElement> {
1251        let inner = self.inner.lock();
1252        let main_frame_id = get_main_frame_id(&inner);
1253        crate::text_frame::build_flow_elements(&inner, &self.inner, main_frame_id)
1254    }
1255
1256    /// Get a read-only handle to a block by its entity ID.
1257    ///
1258    /// Entity IDs are stable across insertions and deletions.
1259    /// Returns `None` if no block with this ID exists.
1260    pub fn block_by_id(&self, block_id: usize) -> Option<crate::text_block::TextBlock> {
1261        let inner = self.inner.lock();
1262        let exists = frontend::commands::block_commands::get_block(&inner.ctx, &(block_id as u64))
1263            .ok()
1264            .flatten()
1265            .is_some();
1266
1267        if exists {
1268            Some(crate::text_block::TextBlock {
1269                doc: self.inner.clone(),
1270                block_id,
1271            })
1272        } else {
1273            None
1274        }
1275    }
1276
1277    /// Build a single `BlockSnapshot` for the block at the given position.
1278    ///
1279    /// This is O(k) where k = format runs + image anchors in that block,
1280    /// compared to `snapshot_flow()` which is O(n) over the entire document.
1281    /// Use for incremental layout updates after single-block edits.
1282    pub fn snapshot_block_at_position(
1283        &self,
1284        position: usize,
1285    ) -> Option<crate::flow::BlockSnapshot> {
1286        self.snapshot_block_at_position_masked(position, &crate::highlight::HighlightMask::all())
1287    }
1288
1289    /// Like [`snapshot_block_at_position`](Self::snapshot_block_at_position)
1290    /// but with **no highlights applied** — base fragments and empty
1291    /// `paint_highlights`, regardless of the active sessions. Used by the
1292    /// incremental relayout path of a view that has opted out of highlights.
1293    pub fn snapshot_block_at_position_without_highlights(
1294        &self,
1295        position: usize,
1296    ) -> Option<crate::flow::BlockSnapshot> {
1297        self.snapshot_block_at_position_masked(position, &crate::highlight::HighlightMask::none())
1298    }
1299
1300    /// Like [`snapshot_block_at_position`](Self::snapshot_block_at_position) but rendering
1301    /// only the sessions `mask` admits — the per-view incremental path (two panes over one
1302    /// document can carry different find sessions). `all()` = the plain method; `none()` = the
1303    /// without-highlights method.
1304    pub fn snapshot_block_at_position_masked(
1305        &self,
1306        position: usize,
1307        mask: &crate::highlight::HighlightMask,
1308    ) -> Option<crate::flow::BlockSnapshot> {
1309        block_snapshot_at(&self.inner.lock(), position, mask)
1310    }
1311
1312    /// Get a read-only handle to the block containing the given
1313    /// character position. Returns `None` if position is out of range.
1314    pub fn block_at_position(&self, position: usize) -> Option<crate::text_block::TextBlock> {
1315        let inner = self.inner.lock();
1316        let dto = frontend::document_inspection::GetBlockAtPositionDto {
1317            position: to_i64(position),
1318        };
1319        let result = document_inspection_commands::get_block_at_position(&inner.ctx, &dto).ok()?;
1320        Some(crate::text_block::TextBlock {
1321            doc: self.inner.clone(),
1322            block_id: result.block_id as usize,
1323        })
1324    }
1325
1326    /// Get a read-only handle to a block by its 0-indexed global
1327    /// block number.
1328    ///
1329    /// **O(n)**: requires scanning all blocks sorted by
1330    /// `document_position` to find the nth one. Prefer
1331    /// [`block_at_position()`](TextDocument::block_at_position) or
1332    /// [`block_by_id()`](TextDocument::block_by_id) in
1333    /// performance-sensitive paths.
1334    pub fn block_by_number(&self, block_number: usize) -> Option<crate::text_block::TextBlock> {
1335        let inner = self.inner.lock();
1336        let all_blocks = frontend::commands::block_commands::get_all_block(&inner.ctx).ok()?;
1337        let mut sorted: Vec<_> = all_blocks.into_iter().collect();
1338        let store = inner.ctx.db_context.get_store();
1339        crate::inner::refresh_block_positions(&mut sorted, store);
1340        sorted.sort_by_key(|b| b.document_position);
1341
1342        sorted
1343            .get(block_number)
1344            .map(|b| crate::text_block::TextBlock {
1345                doc: self.inner.clone(),
1346                block_id: b.id as usize,
1347            })
1348    }
1349
1350    /// All blocks in the document, sorted by `document_position`. **O(n)**.
1351    ///
1352    /// Returns blocks from all frames, including those inside table cells.
1353    /// This is the efficient way to iterate all blocks — avoids the O(n^2)
1354    /// cost of calling `block_by_number(i)` in a loop.
1355    pub fn blocks(&self) -> Vec<crate::text_block::TextBlock> {
1356        let inner = self.inner.lock();
1357        let all_blocks =
1358            frontend::commands::block_commands::get_all_block(&inner.ctx).unwrap_or_default();
1359        let mut sorted: Vec<_> = all_blocks.into_iter().collect();
1360        let store = inner.ctx.db_context.get_store();
1361        crate::inner::refresh_block_positions(&mut sorted, store);
1362        sorted.sort_by_key(|b| b.document_position);
1363        sorted
1364            .iter()
1365            .map(|b| crate::text_block::TextBlock {
1366                doc: self.inner.clone(),
1367                block_id: b.id as usize,
1368            })
1369            .collect()
1370    }
1371
1372    /// All blocks whose character range intersects `[position, position + length)`.
1373    ///
1374    /// **O(n)**: scans all blocks once. Returns them sorted by `document_position`.
1375    /// A block intersects if its range `[block.position, block.position + block.length)`
1376    /// overlaps the query range. An empty query range (`length == 0`) returns the
1377    /// block containing that position, if any.
1378    pub fn blocks_in_range(
1379        &self,
1380        position: usize,
1381        length: usize,
1382    ) -> Vec<crate::text_block::TextBlock> {
1383        let inner = self.inner.lock();
1384        let all_blocks =
1385            frontend::commands::block_commands::get_all_block(&inner.ctx).unwrap_or_default();
1386        let mut sorted: Vec<_> = all_blocks.into_iter().collect();
1387        let store = inner.ctx.db_context.get_store();
1388        crate::inner::refresh_block_positions(&mut sorted, store);
1389        sorted.sort_by_key(|b| b.document_position);
1390
1391        let range_start = position;
1392        let range_end = position + length;
1393        sorted
1394            .iter()
1395            .filter(|b| {
1396                let block_start = b.document_position.max(0) as usize;
1397                let entity: common::entities::Block = (*b).clone().into();
1398                let block_end = block_start
1399                    + common::database::rope_helpers::block_char_length(&entity, store).max(0)
1400                        as usize;
1401                // Overlap check: block intersects [range_start, range_end)
1402                if length == 0 {
1403                    // Point query: block contains the position
1404                    range_start >= block_start && range_start < block_end
1405                } else {
1406                    block_start < range_end && block_end > range_start
1407                }
1408            })
1409            .map(|b| crate::text_block::TextBlock {
1410                doc: self.inner.clone(),
1411                block_id: b.id as usize,
1412            })
1413            .collect()
1414    }
1415
1416    /// Snapshot the entire main flow in a single lock acquisition.
1417    ///
1418    /// Returns a [`FlowSnapshot`](crate::FlowSnapshot) containing snapshots
1419    /// for every element in the flow.
1420    pub fn snapshot_flow(&self) -> crate::flow::FlowSnapshot {
1421        self.snapshot_flow_masked(&crate::highlight::HighlightMask::all())
1422    }
1423
1424    /// Snapshot the entire main flow with **no highlights applied** — base
1425    /// fragments and empty `paint_highlights` on every block, regardless of
1426    /// the active sessions.
1427    ///
1428    /// This is the per-view opt-out: a read-only viewer that should stay
1429    /// free of search / spell / syntax highlighting pulls *this* snapshot
1430    /// instead of [`snapshot_flow`](Self::snapshot_flow). Because suppression
1431    /// happens at build time, it works for metric-affecting sessions too
1432    /// (whose highlights are otherwise merged into `fragments` irreversibly).
1433    pub fn snapshot_flow_without_highlights(&self) -> crate::flow::FlowSnapshot {
1434        self.snapshot_flow_masked(&crate::highlight::HighlightMask::none())
1435    }
1436
1437    /// Snapshot the entire main flow rendering only the sessions `mask` admits.
1438    ///
1439    /// The generalization of the plain / without-highlights pair: `all()` shows every session,
1440    /// `none()` shows none, and `only([...])` shows a chosen set — which is how two panes over
1441    /// one shared document carry different find sessions. The effective
1442    /// `HighlighterKind` is resolved **once here**, at the snapshot root,
1443    /// and threaded down, so a view showing only paint-only sessions never pays the reshape
1444    /// path for a metric session it does not show.
1445    pub fn snapshot_flow_masked(
1446        &self,
1447        mask: &crate::highlight::HighlightMask,
1448    ) -> crate::flow::FlowSnapshot {
1449        flow_snapshot_of(&self.inner.lock(), mask, false)
1450    }
1451
1452    /// Snapshot the main flow like [`snapshot_flow_masked`](Self::snapshot_flow_masked),
1453    /// but **without computing the paint-only overlay** (`paint_highlights` is
1454    /// empty on every block). Fragments are identical — metric sessions still
1455    /// split them — so a consumer that reads only the fragments and their
1456    /// geometry gets the exact same tree, minus the `extract_paint_spans` work.
1457    ///
1458    /// This is the accessibility path's snapshot: the AT tree reads fragments,
1459    /// never the paint overlay, so paying to compute a per-block paint span for
1460    /// each of a spell-checker's tens of thousands of ranges is pure waste (it
1461    /// dominated the a11y rebuild on a large mis-dictionaried document). Render
1462    /// and layout keep using [`snapshot_flow_masked`](Self::snapshot_flow_masked),
1463    /// which they must — they draw the overlay.
1464    pub fn snapshot_flow_masked_no_paint(
1465        &self,
1466        mask: &crate::highlight::HighlightMask,
1467    ) -> crate::flow::FlowSnapshot {
1468        flow_snapshot_of(&self.inner.lock(), mask, true)
1469    }
1470
1471    // ── Search ───────────────────────────────────────────────
1472
1473    /// Find the next (or previous) occurrence. Returns `None` if not found.
1474    pub fn find(
1475        &self,
1476        query: &str,
1477        from: usize,
1478        options: &FindOptions,
1479    ) -> Result<Option<FindMatch>> {
1480        let inner = self.inner.lock();
1481        let dto = options.to_find_text_dto(query, from);
1482        let result = document_search_commands::find_text(&inner.ctx, &dto)?;
1483        Ok(convert::find_result_to_match(&result))
1484    }
1485
1486    /// Find all occurrences.
1487    pub fn find_all(&self, query: &str, options: &FindOptions) -> Result<Vec<FindMatch>> {
1488        let inner = self.inner.lock();
1489        let dto = options.to_find_all_dto(query);
1490        let result = document_search_commands::find_all(&inner.ctx, &dto)?;
1491        Ok(convert::find_all_to_matches(&result))
1492    }
1493
1494    /// Replace occurrences. Returns the number of replacements. Undoable.
1495    ///
1496    /// `options` carries both how to find the text and — via
1497    /// [`crate::ReplaceOptions::format_policy`] — what the replacement wears where it
1498    /// overwrites formatted prose. The default drops the formatting under the replaced
1499    /// range, which is fine for plain text and destructive for a rename that lands on a
1500    /// partly-bold name; pass a different policy when that matters.
1501    pub fn replace_text(
1502        &self,
1503        query: &str,
1504        replacement: &str,
1505        replace_all: bool,
1506        options: &crate::ReplaceOptions,
1507    ) -> Result<usize> {
1508        let _settled = self.settle_transient_edits();
1509        let (count, queued) = {
1510            let mut inner = self.inner.lock();
1511            let dto = options.to_replace_dto(query, replacement, replace_all);
1512            let result =
1513                document_search_commands::replace_text(&inner.ctx, Some(inner.stack_id), &dto)?;
1514            let count = to_usize(result.replacements_count);
1515            inner.invalidate_text_cache();
1516            if count > 0 {
1517                inner.modified = true;
1518                inner.rehighlight_all();
1519                // Replacements are scattered across the document — we can't
1520                // provide a single position/chars delta. Signal "content changed
1521                // from position 0, affecting `count` sites" so the consumer
1522                // knows to re-read.
1523                inner.queue_event(DocumentEvent::ContentsChanged {
1524                    position: 0,
1525                    chars_removed: 0,
1526                    chars_added: 0,
1527                    blocks_affected: count,
1528                });
1529                inner.check_block_count_changed();
1530                inner.check_flow_changed();
1531                let can_undo = undo_redo_commands::can_undo(&inner.ctx, Some(inner.stack_id));
1532                let can_redo = undo_redo_commands::can_redo(&inner.ctx, Some(inner.stack_id));
1533                inner.queue_event(DocumentEvent::UndoRedoChanged { can_undo, can_redo });
1534            }
1535            (count, inner.take_queued_events())
1536        };
1537        crate::inner::dispatch_queued_events(queued);
1538        Ok(count)
1539    }
1540
1541    /// Replace an explicit set of ranges, each with **its own** replacement text. Undoable
1542    /// as one action, however many ranges it touches.
1543    ///
1544    /// [`replace_text`](Self::replace_text) can only put the same string at every match.
1545    /// This is for the case where the caller decides *per occurrence* — a reviewed bulk
1546    /// rename where some occurrences are unticked, or one that preserves the case it found
1547    /// (`AURÉLIEN` → `AURÉLIAN`, not `aurélian`).
1548    ///
1549    /// ⚠ **Do not build the ranges with a separate `find_all` call.** The document can move
1550    /// between the two, and the ranges then address text that is no longer there — which
1551    /// does not fail, it rewrites *the wrong words*. Use
1552    /// [`find_and_replace`](Self::find_and_replace), which does both under one lock.
1553    ///
1554    /// Ranges that straddle a block boundary, or that overlap one another, are **skipped**;
1555    /// the returned count reflects only what was actually applied.
1556    ///
1557    /// With [transient edits](crate::transient) outstanding, they are reverted first, and the
1558    /// ranges, read in the document as it was with them, are moved back so that each holds
1559    /// the recorded text it held (see the [module documentation](crate::transient#positions));
1560    /// a non-empty range that comes back empty held only transient text, names nothing left,
1561    /// and is skipped too.
1562    pub fn replace_ranges(
1563        &self,
1564        ranges: &[ReplaceRange],
1565        options: &crate::ReplaceOptions,
1566    ) -> Result<usize> {
1567        let (result, rest) = {
1568            let mut inner = self.inner.lock();
1569            // Reverted under the lock the replacement takes, so that no other write lands
1570            // between the revert and the replacement and the mapped ranges stay true.
1571            let reverted = inner.revert_transient_edits();
1572            let mapped: Vec<ReplaceRange>;
1573            let ranges = match &reverted {
1574                None => ranges,
1575                Some(reverted) => {
1576                    mapped = ranges
1577                        .iter()
1578                        .filter_map(|range| {
1579                            let (start, end) =
1580                                reverted.map_range(range.position, range.position + range.length);
1581                            (range.length == 0 || end > start).then(|| ReplaceRange {
1582                                position: start,
1583                                length: end - start,
1584                                replacement: range.replacement.clone(),
1585                            })
1586                        })
1587                        .collect();
1588                    &mapped
1589                }
1590            };
1591            let result = Self::replace_ranges_locked(&mut inner, ranges, options);
1592            (result, inner.take_queued_events())
1593        };
1594        crate::inner::dispatch_queued_events(rest);
1595        result
1596    }
1597
1598    /// Find every match of `query` and let `decide` choose what each becomes — **atomically**.
1599    ///
1600    /// `decide` is handed the matched text and the index of the match, and returns the
1601    /// replacement, or `None` to leave that occurrence alone. So a rename that preserves case
1602    /// and skips the occurrences a writer unticked is one call:
1603    ///
1604    /// ```no_run
1605    /// # use text_document::{TextDocument, FindOptions, ReplaceOptions};
1606    /// # let doc = TextDocument::new();
1607    /// # let excluded: Vec<usize> = vec![];
1608    /// doc.find_and_replace("Aurélien", &ReplaceOptions::new(FindOptions::default()), |matched, i| {
1609    ///     if excluded.contains(&i) {
1610    ///         return None; // the writer unticked this one
1611    ///     }
1612    ///     Some(if matched.chars().all(char::is_uppercase) { "AURÉLIAN".into() } else { "Aurélian".into() })
1613    /// })?;
1614    /// # Ok::<(), text_document::DocumentError>(())
1615    /// ```
1616    ///
1617    /// **The scan and the splice happen under one lock**, which is the whole point. Calling
1618    /// `find_all` and then `replace_ranges` would drop the lock in between, and the document
1619    /// can be edited there — after which every range addresses text that has moved. That does
1620    /// not raise an error; it silently rewrites the wrong words. The document mutex is not
1621    /// reentrant, so composing the two public methods cannot close the gap; only doing both
1622    /// inside one can.
1623    pub fn find_and_replace(
1624        &self,
1625        query: &str,
1626        options: &crate::ReplaceOptions,
1627        mut decide: impl FnMut(&str, usize) -> Option<String>,
1628    ) -> Result<usize> {
1629        let _settled = self.settle_transient_edits();
1630        let (count, queued) = {
1631            let mut inner = self.inner.lock();
1632
1633            // Scan. The matched TEXT comes back with the offsets, sliced by the use case from
1634            // the very text it searched — deliberately, so this never has to slice a
1635            // whole-document string of its own. The only one reachable here is
1636            // `to_plain_text`, which is the human-readable view and carries no `U+FFFC` anchor
1637            // for an embedded table; slicing it with these offsets would be wrong by two
1638            // characters per preceding table, and the rename would rewrite the wrong words.
1639            let found = {
1640                let dto = options.find.to_find_all_dto(query);
1641                document_search_commands::find_all(&inner.ctx, &dto)?
1642            };
1643
1644            // …decide, against the document as it is RIGHT NOW…
1645            let mut ranges: Vec<ReplaceRange> = Vec::new();
1646            for (i, ((&position, &length), matched)) in found
1647                .positions
1648                .iter()
1649                .zip(found.lengths.iter())
1650                .zip(found.matched_texts.iter())
1651                .enumerate()
1652            {
1653                if let Some(replacement) = decide(matched, i) {
1654                    ranges.push(ReplaceRange {
1655                        position: to_usize(position),
1656                        length: to_usize(length),
1657                        replacement,
1658                    });
1659                }
1660            }
1661
1662            // …and splice — all without ever letting go of the lock.
1663            let count = if ranges.is_empty() {
1664                0
1665            } else {
1666                Self::replace_ranges_locked(&mut inner, &ranges, options)?
1667            };
1668            (count, inner.take_queued_events())
1669        };
1670        crate::inner::dispatch_queued_events(queued);
1671        Ok(count)
1672    }
1673
1674    /// The splice, with the lock already held. Shared by [`Self::replace_ranges`] and
1675    /// [`Self::find_and_replace`] so the second cannot drift from the first.
1676    fn replace_ranges_locked(
1677        inner: &mut crate::inner::TextDocumentInner,
1678        ranges: &[ReplaceRange],
1679        options: &crate::ReplaceOptions,
1680    ) -> Result<usize> {
1681        let dto = options.to_replace_ranges_dto(ranges);
1682        let result =
1683            document_search_commands::replace_ranges(&inner.ctx, Some(inner.stack_id), &dto)?;
1684        let count = to_usize(result.replacements_count);
1685
1686        inner.invalidate_text_cache();
1687        if count > 0 {
1688            inner.modified = true;
1689            inner.rehighlight_all();
1690            inner.queue_event(DocumentEvent::ContentsChanged {
1691                position: 0,
1692                chars_removed: 0,
1693                chars_added: 0,
1694                blocks_affected: count,
1695            });
1696            inner.check_block_count_changed();
1697            inner.check_flow_changed();
1698            let can_undo = undo_redo_commands::can_undo(&inner.ctx, Some(inner.stack_id));
1699            let can_redo = undo_redo_commands::can_redo(&inner.ctx, Some(inner.stack_id));
1700            inner.queue_event(DocumentEvent::UndoRedoChanged { can_undo, can_redo });
1701        }
1702        Ok(count)
1703    }
1704
1705    // ── Resources ────────────────────────────────────────────
1706
1707    /// Add a resource (image, stylesheet) to the document.
1708    pub fn add_resource(
1709        &self,
1710        resource_type: ResourceType,
1711        name: &str,
1712        mime_type: &str,
1713        data: &[u8],
1714    ) -> Result<()> {
1715        let _settled = self.settle_transient_edits();
1716        let mut inner = self.inner.lock();
1717        let dto = frontend::resource::dtos::CreateResourceDto {
1718            created_at: Default::default(),
1719            updated_at: Default::default(),
1720            resource_type,
1721            name: name.into(),
1722            url: String::new(),
1723            mime_type: mime_type.into(),
1724            data_base64: BASE64.encode(data),
1725        };
1726        let created = resource_commands::create_resource(
1727            &inner.ctx,
1728            Some(inner.stack_id),
1729            &dto,
1730            inner.document_id,
1731            -1,
1732        )?;
1733        inner.resource_cache.insert(name.to_string(), created.id);
1734        Ok(())
1735    }
1736
1737    /// Get a resource by name. Returns `None` if not found.
1738    ///
1739    /// Uses an internal cache to avoid scanning all resources on repeated lookups.
1740    pub fn resource(&self, name: &str) -> Result<Option<Vec<u8>>> {
1741        let mut inner = self.inner.lock();
1742
1743        // Fast path: check the name → ID cache.
1744        if let Some(&id) = inner.resource_cache.get(name) {
1745            if let Some(r) = resource_commands::get_resource(&inner.ctx, &id)? {
1746                let bytes = BASE64
1747                    .decode(&r.data_base64)
1748                    .map_err(|e| DocumentError::Internal(e.into()))?;
1749                return Ok(Some(bytes));
1750            }
1751            // ID was stale — fall through to full scan.
1752            inner.resource_cache.remove(name);
1753        }
1754
1755        // Slow path: linear scan, then populate cache for the match.
1756        let all = resource_commands::get_all_resource(&inner.ctx)?;
1757        for r in &all {
1758            if r.name == name {
1759                inner.resource_cache.insert(name.to_string(), r.id);
1760                let bytes = BASE64
1761                    .decode(&r.data_base64)
1762                    .map_err(|e| DocumentError::Internal(e.into()))?;
1763                return Ok(Some(bytes));
1764            }
1765        }
1766        Ok(None)
1767    }
1768
1769    // ── Undo / Redo ──────────────────────────────────────────
1770
1771    /// Undo the last operation.
1772    ///
1773    /// The cursor the edit was made with goes where QTextDocument puts it: where the text
1774    /// an undone insertion put in was, and after the text an undone deletion took away, as
1775    /// TextEdit and Word leave it too. An undone format change leaves it as it stands.
1776    /// Every other cursor moves only by what the undo changed.
1777    pub fn undo(&self) -> Result<()> {
1778        let _settled = self.settle_transient_edits();
1779        let queued = {
1780            let mut inner = self.inner.lock();
1781            let before = capture_block_state(&inner);
1782            let entry = undo_redo_commands::head_seq(&inner.ctx, Some(inner.stack_id));
1783            let (edited_with, left_at) = inner.edit_caret_cursor(entry).unzip();
1784            let stepped = undo_redo_commands::can_undo(&inner.ctx, Some(inner.stack_id));
1785            let result = undo_redo_commands::undo(&inner.ctx, Some(inner.stack_id));
1786            inner.invalidate_text_cache();
1787            // An undo that actually popped a command changed the buffer, so the
1788            // document is dirty again. Nothing else sets `modified` here: every
1789            // other setter is an *edit* in `cursor.rs`/`streaming.rs`. Without
1790            // this, an embedder that gates its write-back on `is_modified()`
1791            // silently discards the undo — the text reverts on screen while the
1792            // persisted copy keeps the pre-undo version, and the next reload
1793            // brings the stale text back. (Skribisto's `ProseField::flush` did
1794            // exactly that.)
1795            //
1796            // `can_undo` is sampled *before* the call because `undo()` on an
1797            // empty stack is a successful no-op, and marking a clean document
1798            // dirty for a keystroke that did nothing would be its own bug.
1799            //
1800            // Set *before* `result?`, and deliberately. A composite entry undoes
1801            // its parts in reverse and gives up on the first failure, so a
1802            // failed undo can still have reverted some of them — the buffer has
1803            // moved, which is why `invalidate_text_cache` above is also
1804            // unconditional. Marking a document dirty that turns out not to need
1805            // saving costs one redundant write; the other way round loses the
1806            // writer's text.
1807            if stepped {
1808                inner.modified = true;
1809            }
1810            result?;
1811            inner.rehighlight_all();
1812            let changed_text_end = emit_content_change_events_near(&mut inner, &before, left_at);
1813            if let (Some(cursor), Some(end)) = (edited_with, changed_text_end) {
1814                let end =
1815                    crate::cursor::max_cursor_position_of(&inner).map_or(end, |max| end.min(max));
1816                let mut data = cursor.lock();
1817                data.position = end;
1818                data.anchor = end;
1819                data.anchor_in_table = None;
1820                data.cell_selection_override = None;
1821            }
1822            inner.check_block_count_changed();
1823            inner.check_flow_changed();
1824            let can_undo = undo_redo_commands::can_undo(&inner.ctx, Some(inner.stack_id));
1825            let can_redo = undo_redo_commands::can_redo(&inner.ctx, Some(inner.stack_id));
1826            inner.queue_event(DocumentEvent::UndoRedoChanged { can_undo, can_redo });
1827            inner.take_queued_events()
1828        };
1829        crate::inner::dispatch_queued_events(queued);
1830        Ok(())
1831    }
1832
1833    /// Redo the last undone operation.
1834    ///
1835    /// The cursor the edit was made with goes back where the edit left it: after a redone
1836    /// insertion its end, after a redone deletion the deletion point, after a redone format
1837    /// change the selection it was made on. It goes there wherever it went since, as in
1838    /// QTextDocument, TextEdit and Word. Every other cursor moves only by what the redo
1839    /// changed.
1840    pub fn redo(&self) -> Result<()> {
1841        let _settled = self.settle_transient_edits();
1842        let queued = {
1843            let mut inner = self.inner.lock();
1844            let before = capture_block_state(&inner);
1845            let stepped = undo_redo_commands::can_redo(&inner.ctx, Some(inner.stack_id));
1846            let result = undo_redo_commands::redo(&inner.ctx, Some(inner.stack_id));
1847            inner.invalidate_text_cache();
1848            // A redo re-applies an edit the writer took back, which is a change
1849            // to the buffer like any other: same reasoning as `undo` above, and
1850            // the same placement before `result?` for the same reason. Here the
1851            // predicate is `can_redo`, sampled before the call because `redo()`
1852            // on an empty redo branch is a successful no-op.
1853            if stepped {
1854                inner.modified = true;
1855            }
1856            result?;
1857            inner.rehighlight_all();
1858            emit_content_change_events(&mut inner, &before);
1859            if stepped {
1860                let entry = undo_redo_commands::head_seq(&inner.ctx, Some(inner.stack_id));
1861                inner.restore_edit_caret(entry, crate::cursor::max_cursor_position_of(&inner));
1862            }
1863            inner.check_block_count_changed();
1864            inner.check_flow_changed();
1865            let can_undo = undo_redo_commands::can_undo(&inner.ctx, Some(inner.stack_id));
1866            let can_redo = undo_redo_commands::can_redo(&inner.ctx, Some(inner.stack_id));
1867            inner.queue_event(DocumentEvent::UndoRedoChanged { can_undo, can_redo });
1868            inner.take_queued_events()
1869        };
1870        crate::inner::dispatch_queued_events(queued);
1871        Ok(())
1872    }
1873
1874    /// Close the current undo entry, so the next edit starts a new one.
1875    ///
1876    /// Typing is coalesced — contiguous inserts within a couple of seconds
1877    /// become one undo step, which is what makes Ctrl+Z take back a word rather
1878    /// than a letter. The rule looks only at the *shape* of two edits and cannot
1879    /// see that something happened between them: an embedder whose user typed,
1880    /// renamed a chapter somewhere else, then typed again gets one entry
1881    /// spanning both bursts, and undoing it takes back text entered before an
1882    /// event the user remembers as a dividing line.
1883    ///
1884    /// The embedder is the only one who knows such a line was crossed. This is
1885    /// how it says so. Idempotent, and harmless on an empty history.
1886    pub fn break_undo_merge(&self) {
1887        let inner = self.inner.lock();
1888        undo_redo_commands::seal_head(&inner.ctx, Some(inner.stack_id));
1889    }
1890
1891    /// Bound how many undo entries this document keeps, dropping the oldest
1892    /// past the limit. `None` — the default — keeps everything.
1893    ///
1894    /// Typing history is unbounded by construction: every keystroke that does
1895    /// not coalesce into the entry below it is another entry, and each holds a
1896    /// snapshot of what it changed. Over a day-long drafting session on one
1897    /// document that is a ceiling nobody set. An embedder that cares about the
1898    /// ceiling needs a way to say so, and this is it — the far end of a long
1899    /// history is the part nobody reaches for.
1900    ///
1901    /// The limit belongs to the document, not to one edit: lowering it trims
1902    /// on the next push rather than immediately, so an entry the writer can
1903    /// still see in a menu does not vanish under them.
1904    pub fn set_undo_limit(&self, limit: Option<usize>) {
1905        let inner = self.inner.lock();
1906        undo_redo_commands::set_undo_limit(&inner.ctx, limit);
1907    }
1908
1909    /// The current entry limit, if one is set.
1910    pub fn undo_limit(&self) -> Option<usize> {
1911        let inner = self.inner.lock();
1912        undo_redo_commands::undo_limit(&inner.ctx)
1913    }
1914
1915    /// Returns true if there are operations that can be undone.
1916    pub fn can_undo(&self) -> bool {
1917        let inner = self.inner.lock();
1918        undo_redo_commands::can_undo(&inner.ctx, Some(inner.stack_id))
1919    }
1920
1921    /// Returns true if there are operations that can be redone.
1922    pub fn can_redo(&self) -> bool {
1923        let inner = self.inner.lock();
1924        undo_redo_commands::can_redo(&inner.ctx, Some(inner.stack_id))
1925    }
1926
1927    /// Clear all undo/redo history.
1928    pub fn clear_undo_redo(&self) {
1929        let inner = self.inner.lock();
1930        undo_redo_commands::clear_stack(&inner.ctx, inner.stack_id);
1931    }
1932
1933    // ── Modified state ───────────────────────────────────────
1934
1935    /// Returns true if the document has been modified since creation or last reset.
1936    pub fn is_modified(&self) -> bool {
1937        self.inner.lock().modified
1938    }
1939
1940    /// Set or clear the modified flag.
1941    pub fn set_modified(&self, modified: bool) {
1942        let queued = {
1943            let mut inner = self.inner.lock();
1944            if inner.modified != modified {
1945                inner.modified = modified;
1946                inner.queue_event(DocumentEvent::ModificationChanged(modified));
1947            }
1948            inner.take_queued_events()
1949        };
1950        crate::inner::dispatch_queued_events(queued);
1951    }
1952
1953    /// A monotonic counter, bumped once per [`DocumentEvent::ContentsChanged`]
1954    /// queued so far. Starts at `0`.
1955    ///
1956    /// Lets a caller answer "was this notification caused by exactly the
1957    /// most recent edit, with nothing else having happened since" precisely
1958    /// — snapshot the value when acting on a notification, and compare it
1959    /// against the current value later. This is deliberately *not* the same
1960    /// as [`is_modified`](Self::is_modified) (a flag, not a count) or the
1961    /// undo stack's depth (which does not grow when consecutive compatible
1962    /// edits merge into one entry — e.g. fast consecutive typing).
1963    pub fn content_revision(&self) -> u64 {
1964        self.inner.lock().content_revision
1965    }
1966
1967    // ── Document properties ──────────────────────────────────
1968
1969    /// Get the document title.
1970    pub fn title(&self) -> String {
1971        let inner = self.inner.lock();
1972        document_commands::get_document(&inner.ctx, &inner.document_id)
1973            .ok()
1974            .flatten()
1975            .map(|d| d.title)
1976            .unwrap_or_default()
1977    }
1978
1979    /// Set the document title.
1980    pub fn set_title(&self, title: &str) -> Result<()> {
1981        let _settled = self.settle_transient_edits();
1982        let inner = self.inner.lock();
1983        let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
1984            .ok_or_else(|| DocumentError::NotFound("document not found".into()))?;
1985        let mut update: frontend::document::dtos::UpdateDocumentDto = doc.into();
1986        update.title = title.into();
1987        document_commands::update_document(&inner.ctx, Some(inner.stack_id), &update)?;
1988        Ok(())
1989    }
1990
1991    /// Get the text direction.
1992    pub fn text_direction(&self) -> TextDirection {
1993        let inner = self.inner.lock();
1994        document_commands::get_document(&inner.ctx, &inner.document_id)
1995            .ok()
1996            .flatten()
1997            .map(|d| d.text_direction)
1998            .unwrap_or(TextDirection::LeftToRight)
1999    }
2000
2001    /// Set the text direction.
2002    pub fn set_text_direction(&self, direction: TextDirection) -> Result<()> {
2003        let _settled = self.settle_transient_edits();
2004        let inner = self.inner.lock();
2005        let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
2006            .ok_or_else(|| DocumentError::NotFound("document not found".into()))?;
2007        let mut update: frontend::document::dtos::UpdateDocumentDto = doc.into();
2008        update.text_direction = direction;
2009        document_commands::update_document(&inner.ctx, Some(inner.stack_id), &update)?;
2010        Ok(())
2011    }
2012
2013    /// Get the default wrap mode.
2014    pub fn default_wrap_mode(&self) -> WrapMode {
2015        let inner = self.inner.lock();
2016        document_commands::get_document(&inner.ctx, &inner.document_id)
2017            .ok()
2018            .flatten()
2019            .map(|d| d.default_wrap_mode)
2020            .unwrap_or(WrapMode::WordWrap)
2021    }
2022
2023    /// Set the default wrap mode.
2024    pub fn set_default_wrap_mode(&self, mode: WrapMode) -> Result<()> {
2025        let _settled = self.settle_transient_edits();
2026        let inner = self.inner.lock();
2027        let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
2028            .ok_or_else(|| DocumentError::NotFound("document not found".into()))?;
2029        let mut update: frontend::document::dtos::UpdateDocumentDto = doc.into();
2030        update.default_wrap_mode = mode;
2031        document_commands::update_document(&inner.ctx, Some(inner.stack_id), &update)?;
2032        Ok(())
2033    }
2034
2035    /// Get the document-wide default language (ISO 639-1 code, e.g. "en").
2036    /// This is the fallback hyphenation language for blocks that don't set
2037    /// their own `language`. Defaults to `"en"` when never set.
2038    pub fn default_language(&self) -> String {
2039        let inner = self.inner.lock();
2040        document_commands::get_document(&inner.ctx, &inner.document_id)
2041            .ok()
2042            .flatten()
2043            .and_then(|d| d.default_language)
2044            .unwrap_or_else(|| "en".to_string())
2045    }
2046
2047    /// Set the document-wide default language (ISO 639-1 code). Blocks
2048    /// without an explicit `language` inherit this for hyphenation.
2049    pub fn set_default_language(&self, language: &str) -> Result<()> {
2050        let _settled = self.settle_transient_edits();
2051        let inner = self.inner.lock();
2052        let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
2053            .ok_or_else(|| DocumentError::NotFound("document not found".into()))?;
2054        let mut update: frontend::document::dtos::UpdateDocumentDto = doc.into();
2055        update.default_language = Some(language.to_string());
2056        document_commands::update_document(&inner.ctx, Some(inner.stack_id), &update)?;
2057        Ok(())
2058    }
2059
2060    // ── Event subscription ───────────────────────────────────
2061
2062    /// Subscribe to document events via callback.
2063    ///
2064    /// Callbacks are invoked **outside** the document lock (after the editing
2065    /// operation completes and the lock is released). It is safe to call
2066    /// `TextDocument` or `TextCursor` methods from within the callback without
2067    /// risk of deadlock. However, keep callbacks lightweight — they run
2068    /// synchronously on the calling thread and block the caller until they
2069    /// return.
2070    ///
2071    /// Drop the returned [`Subscription`] to unsubscribe.
2072    ///
2073    /// # Breaking change (v0.0.6)
2074    ///
2075    /// The callback bound changed from `Send` to `Send + Sync` in v0.0.6
2076    /// to support `Arc`-based dispatch. Callbacks that capture non-`Sync`
2077    /// types (e.g., `Rc<T>`, `Cell<T>`) must be wrapped in a `Mutex`.
2078    pub fn on_change<F>(&self, callback: F) -> Subscription
2079    where
2080        F: Fn(DocumentEvent) + Send + Sync + 'static,
2081    {
2082        let mut inner = self.inner.lock();
2083        events::subscribe_inner(&mut inner, callback)
2084    }
2085
2086    /// Return events accumulated since the last `poll_events()` call.
2087    ///
2088    /// This delivery path is independent of callback dispatch via
2089    /// [`on_change`](Self::on_change) — using both simultaneously is safe
2090    /// and each path sees every event exactly once.
2091    ///
2092    /// While events are held ([`hold_events`](Self::hold_events)) it returns nothing, and
2093    /// the events held are returned by the first call after the release.
2094    pub fn poll_events(&self) -> Vec<DocumentEvent> {
2095        let mut inner = self.inner.lock();
2096        inner.drain_poll_events()
2097    }
2098
2099    /// Hold back the document's events until the returned [`EventHold`](crate::EventHold) is dropped.
2100    ///
2101    /// For a host that edits the document where application code must not run: an input
2102    /// method's lock, during which the host writes the text the input method asks for and
2103    /// reads it back, and no application code may write the document (which would end the
2104    /// transient edits the input method's composition is, see the
2105    /// [transient module](crate::transient#under-a-hosts-lock)).
2106    ///
2107    /// It holds back events only. A [`SyntaxHighlighter`](crate::SyntaxHighlighter) is
2108    /// application code that runs during the hold all the same: it runs as part of each
2109    /// edit, under the document's lock, held or not, so it must not wait on anything the
2110    /// host holds during the hold.
2111    ///
2112    /// While a hold is alive, no event goes out: the [`on_change`](Self::on_change)
2113    /// callbacks are not called and [`poll_events`](Self::poll_events) returns nothing.
2114    /// Every edit, by any cursor or clone of the document and on any thread, queues its
2115    /// events as usual, and so do the transient edits, their revert and their commit, undo
2116    /// and redo, and the long operations' progress. Everything else happens at once: the
2117    /// edit itself, the cursors it moves, [`content_revision`](Self::content_revision),
2118    /// [`can_undo`](Self::can_undo) and every other read, which see the document as it is
2119    /// now. Only notification is deferred.
2120    ///
2121    /// Holds nest: the events go out when the last hold alive is dropped, in the order they
2122    /// were queued, each as it was queued (none is merged with another or left out), on the
2123    /// thread that drops it, outside the document's lock. An edit a callback makes while
2124    /// they go out is delivered after them, in order, never in the middle of them. A hold
2125    /// taken while they go out (by a callback that keeps it, or on another thread) stops
2126    /// the delivery, and its own release delivers the rest. A subscription made during the
2127    /// hold receives only what is queued after it was made, and one dropped receives
2128    /// nothing more. A callback that panics ends the delivery as it ends any other, and the
2129    /// panic goes on from the drop.
2130    ///
2131    /// A delivery already under way when the hold is taken, on this thread (the hold taken
2132    /// by a callback) or on another, finishes the events it had taken: the hold keeps back
2133    /// what is queued from then on. The order holds within one delivery: events another
2134    /// thread was still delivering when the hold was released can reach their callbacks
2135    /// after the ones the release delivers.
2136    pub fn hold_events(&self) -> crate::EventHold {
2137        self.inner.lock().event_holds += 1;
2138        crate::EventHold {
2139            doc: Arc::clone(&self.inner),
2140        }
2141    }
2142
2143    // ── Syntax highlighting ──────────────────────────────────
2144
2145    /// Attach a single syntax highlighter to this document — the classic, one-highlighter
2146    /// entry point.
2147    ///
2148    /// Immediately re-highlights the entire document. **Replaces** the one highlighter this
2149    /// method manages, and *only* that one: a spell-checker or find layer registered
2150    /// independently via [`add_syntax_session`](Self::add_syntax_session) /
2151    /// [`add_range_session`](Self::add_range_session) is left untouched. Pass `None` to remove
2152    /// it.
2153    ///
2154    /// This is a convenience over the session registry — it owns exactly one "shim" session. A
2155    /// host that wants to manage several layers uses the session methods directly.
2156    pub fn set_syntax_highlighter(&self, highlighter: Option<Arc<dyn crate::SyntaxHighlighter>>) {
2157        let queued = {
2158            let mut inner = self.inner.lock();
2159            let prev_kind = inner.highlight_kind;
2160            let installed = highlighter.is_some();
2161            inner.highlights.set_shim(highlighter);
2162            if installed {
2163                inner.rehighlight_all(); // recomputes highlight_kind
2164            } else {
2165                inner.recompute_highlight_kind();
2166            }
2167            Self::queue_highlight_changed(&mut inner, 0, 0, prev_kind);
2168            inner.take_queued_events()
2169        };
2170        crate::inner::dispatch_queued_events(queued);
2171    }
2172
2173    /// Register a **syntax session** — a [`SyntaxHighlighter`](crate::SyntaxHighlighter)
2174    /// callback with its own per-block state cascade — and return its [`crate::SessionId`].
2175    ///
2176    /// Unlike [`set_syntax_highlighter`](Self::set_syntax_highlighter), this **adds** rather
2177    /// than replaces: a document can carry a syntax highlighter and a spell-checker at once,
2178    /// each a session, merged in `(priority, registration)` order (a later session's field
2179    /// wins). Sessions remain visible only in views whose
2180    /// [`HighlightMask`](crate::highlight::HighlightMask) admits them.
2181    pub fn add_syntax_session(
2182        &self,
2183        highlighter: Arc<dyn crate::SyntaxHighlighter>,
2184    ) -> crate::highlight::SessionId {
2185        self.add_syntax_session_with_priority(highlighter, 0)
2186    }
2187
2188    /// [`add_syntax_session`](Self::add_syntax_session) at an explicit merge priority — see
2189    /// [`add_range_session_with_priority`](Self::add_range_session_with_priority).
2190    pub fn add_syntax_session_with_priority(
2191        &self,
2192        highlighter: Arc<dyn crate::SyntaxHighlighter>,
2193        priority: i32,
2194    ) -> crate::highlight::SessionId {
2195        let (id, queued) = {
2196            let mut inner = self.inner.lock();
2197            let prev_kind = inner.highlight_kind;
2198            let id = inner.highlights.add_syntax(highlighter, priority);
2199            inner.rehighlight_all();
2200            Self::queue_highlight_changed(&mut inner, 0, 0, prev_kind);
2201            (id, inner.take_queued_events())
2202        };
2203        crate::inner::dispatch_queued_events(queued);
2204        id
2205    }
2206
2207    /// Register an empty **range session** — absolute-offset ranges set with
2208    /// [`set_session_ranges`](Self::set_session_ranges), the shape used for search and (later)
2209    /// an externally-driven spell-checker. Returns its [`crate::SessionId`].
2210    ///
2211    /// A view's own find session is a range session it alone admits; that is how two panes
2212    /// over one document highlight different queries.
2213    ///
2214    /// **Shared**: every view renders it unless its mask says otherwise. For a layer that
2215    /// belongs to one view rather than to the text, see
2216    /// [`add_opt_in_range_session`](Self::add_opt_in_range_session).
2217    pub fn add_range_session(&self) -> crate::highlight::SessionId {
2218        self.add_range_session_with_priority(0)
2219    }
2220
2221    /// Register an empty range session that **no view renders until it asks for it** by name
2222    /// (`HighlightMask::all().with(id)`).
2223    ///
2224    /// The session lives on the document like any other (a range session has nowhere else to
2225    /// live), but it is a fact about one *view*, not about the text, so a second view of the
2226    /// same document must be left alone. Reach for this whenever the answer to "should the
2227    /// pane next door draw this too?" is no: a reading that marks every mention of one
2228    /// character marks it in the reading, not in every editor that happens to hold the same
2229    /// scene.
2230    ///
2231    /// The alternative, [`HighlightMask::only`](crate::highlight::HighlightMask::only) on
2232    /// every *other* view, cannot be written: a view would have to name every session it
2233    /// does want, including ones it holds no handle on, and would silently drop the next
2234    /// layer anyone adds.
2235    pub fn add_opt_in_range_session(&self) -> crate::highlight::SessionId {
2236        self.add_opt_in_range_session_with_priority(0)
2237    }
2238
2239    /// Every [`OptIn`](crate::highlight::SessionVisibility::OptIn) session on this document,
2240    /// in merge order.
2241    ///
2242    /// Sessions can be added and retired but there was no way to ask what a document carries,
2243    /// which is the one question worth asking about a private layer: it is invisible to the
2244    /// plain snapshot by design, so "is it there, and is it marking the right characters" has
2245    /// no other answer. Shared sessions are deliberately not listed, since every view already
2246    /// draws those, so enumerating them answers nothing.
2247    ///
2248    /// Not a route to a view's mask: a view names the session it *owns*, and one built from
2249    /// this list would draw whatever the pane next door happens to have registered, which is
2250    /// exactly what [`add_opt_in_range_session`](Self::add_opt_in_range_session) exists to
2251    /// prevent.
2252    pub fn opt_in_session_ids(&self) -> Vec<crate::highlight::SessionId> {
2253        let inner = self.inner.lock();
2254        inner
2255            .highlights
2256            .sessions
2257            .iter()
2258            .filter(|s| s.visibility == crate::highlight::SessionVisibility::OptIn)
2259            .map(|s| s.id)
2260            .collect()
2261    }
2262
2263    /// [`add_opt_in_range_session`](Self::add_opt_in_range_session) at an explicit **merge
2264    /// priority**. See
2265    /// [`add_range_session_with_priority`](Self::add_range_session_with_priority).
2266    pub fn add_opt_in_range_session_with_priority(
2267        &self,
2268        priority: i32,
2269    ) -> crate::highlight::SessionId {
2270        let mut inner = self.inner.lock();
2271        inner
2272            .highlights
2273            .add_range(priority, crate::highlight::SessionVisibility::OptIn)
2274        // No repaint: an empty range session shows nothing until its ranges are set.
2275    }
2276
2277    /// [`add_range_session`](Self::add_range_session) at an explicit **merge priority**.
2278    ///
2279    /// Where two sessions format the same character, the higher priority wins field by field;
2280    /// equal priorities fall back to registration order, which is what every session gets by
2281    /// default (`0`).
2282    ///
2283    /// Reach for this when a layer must reliably lose — an ambient background band that every
2284    /// find match and spell squiggle should paint over. Registration order cannot express that:
2285    /// a per-view layer is registered when its view appears, so whether it lands before or
2286    /// after the find session depends on the order the user happened to open things in.
2287    pub fn add_range_session_with_priority(&self, priority: i32) -> crate::highlight::SessionId {
2288        let mut inner = self.inner.lock();
2289        inner
2290            .highlights
2291            .add_range(priority, crate::highlight::SessionVisibility::Shared)
2292        // No repaint: an empty range session shows nothing until its ranges are set.
2293    }
2294
2295    /// Replace the ranges of a range session (absolute char offsets, the space
2296    /// [`FindMatch`] reports in). Returns `false` if `id` is not a range
2297    /// session.
2298    ///
2299    /// Fires a highlight-changed event so live views showing this session re-snapshot — the
2300    /// only signal there is, since the ranges do not mutate the document.
2301    pub fn set_session_ranges(
2302        &self,
2303        id: crate::highlight::SessionId,
2304        ranges: Vec<crate::highlight::RangeHighlight>,
2305    ) -> bool {
2306        let (ok, queued) = {
2307            let mut inner = self.inner.lock();
2308            let prev_kind = inner.highlight_kind;
2309            // The block layout the ranges are bucketed against — cheap (ids + positions, no
2310            // block text) and computed before the mutable borrow of `highlights`. This is what
2311            // lets `merged_spans_for_block` look up only a block's own ranges instead of
2312            // scanning the whole vector per block.
2313            let block_positions = crate::highlight::ordered_block_positions(&inner);
2314            let changed = inner.highlights.set_ranges(id, ranges, &block_positions);
2315            if let Some((position, length)) = changed {
2316                inner.recompute_highlight_kind();
2317                // The real extent, not `0, 0`: a view can then recolor just the block it covers
2318                // rather than re-snapshotting the whole document on every caret move.
2319                Self::queue_highlight_changed(&mut inner, position, length, prev_kind);
2320            }
2321            (changed.is_some(), inner.take_queued_events())
2322        };
2323        crate::inner::dispatch_queued_events(queued);
2324        ok
2325    }
2326
2327    /// Retire a session (of either kind). Returns whether it existed.
2328    pub fn remove_session(&self, id: crate::highlight::SessionId) -> bool {
2329        let (existed, queued) = {
2330            let mut inner = self.inner.lock();
2331            let prev_kind = inner.highlight_kind;
2332            let existed = inner.highlights.remove(id);
2333            if existed {
2334                inner.recompute_highlight_kind();
2335                Self::queue_highlight_changed(&mut inner, 0, 0, prev_kind);
2336            }
2337            (existed, inner.take_queued_events())
2338        };
2339        crate::inner::dispatch_queued_events(queued);
2340        existed
2341    }
2342
2343    /// Re-highlight the entire document.
2344    ///
2345    /// Call this when the highlighter's rules change (e.g., new keywords
2346    /// were added, spellcheck dictionary updated).
2347    pub fn rehighlight(&self) {
2348        let queued = {
2349            let mut inner = self.inner.lock();
2350            let prev_kind = inner.highlight_kind;
2351            inner.rehighlight_all();
2352            Self::queue_highlight_changed(&mut inner, 0, 0, prev_kind);
2353            inner.take_queued_events()
2354        };
2355        crate::inner::dispatch_queued_events(queued);
2356    }
2357
2358    /// Re-highlight a single block and cascade to subsequent blocks if
2359    /// the block state changes.
2360    pub fn rehighlight_block(&self, block_id: usize) {
2361        let queued = {
2362            let mut inner = self.inner.lock();
2363            let prev_kind = inner.highlight_kind;
2364            inner.rehighlight_from_block(block_id);
2365            Self::queue_highlight_changed(&mut inner, 0, 0, prev_kind);
2366            inner.take_queued_events()
2367        };
2368        crate::inner::dispatch_queued_events(queued);
2369    }
2370
2371    /// Queue the relayout/repaint notification for a highlight-only change.
2372    ///
2373    /// Highlighting overlays the layout without touching stored formatting,
2374    /// so it emits no edit event on its own — subscribers (live editors)
2375    /// must be told to re-snapshot. The event kind depends on whether the
2376    /// shaping input (`fragments`) changed:
2377    ///
2378    /// - A change that leaves `fragments` BASE on both sides (paint-only ↔
2379    ///   paint-only / none) emits [`DocumentEvent::HighlightPaintChanged`],
2380    ///   which the editor handles by recoloring the cached layout without
2381    ///   reshaping.
2382    /// - Any transition involving a metric-affecting highlighter changes
2383    ///   `fragments` (highlights are merged in / removed), so it emits
2384    ///   [`DocumentEvent::FormatChanged`] (full relayout, caret/scroll
2385    ///   preserved).
2386    ///
2387    /// `position` / `length` name the extent that changed, so a live view can
2388    /// recolor just the blocks it covers instead of re-deriving the whole
2389    /// snapshot. **A `length` of `0` means "unknown — assume the whole
2390    /// document"**, which is what the genuinely document-wide operations pass
2391    /// (installing or retiring a highlighter, a full rehighlight). Only
2392    /// [`set_session_ranges`](Self::set_session_ranges) reports a real extent,
2393    /// its before/after range sets giving an exact answer.
2394    fn queue_highlight_changed(
2395        inner: &mut TextDocumentInner,
2396        position: usize,
2397        length: usize,
2398        prev_kind: crate::highlight::HighlighterKind,
2399    ) {
2400        use crate::highlight::HighlighterKind::{Metric, None as KNone, PaintOnly};
2401        let new_kind = inner.highlight_kind;
2402        let event = match (prev_kind, new_kind) {
2403            // No highlighter before or after — nothing changed.
2404            (KNone, KNone) => return,
2405            // Fragments are BASE on both sides: recolor-only.
2406            (PaintOnly, PaintOnly) | (KNone, PaintOnly) | (PaintOnly, KNone) => {
2407                DocumentEvent::HighlightPaintChanged { position, length }
2408            }
2409            // A metric highlighter is involved on one side: fragments change.
2410            (KNone, Metric)
2411            | (Metric, Metric)
2412            | (Metric, PaintOnly)
2413            | (Metric, KNone)
2414            | (PaintOnly, Metric) => DocumentEvent::FormatChanged {
2415                position,
2416                length,
2417                kind: crate::flow::FormatChangeKind::Character,
2418            },
2419        };
2420        inner.queue_event(event);
2421    }
2422}
2423
2424impl Default for TextDocument {
2425    fn default() -> Self {
2426        Self::new()
2427    }
2428}
2429
2430// ── Undo/redo change detection helpers ─────────────────────────
2431
2432/// Lightweight block state for before/after comparison.
2433///
2434/// Named for undo/redo because that is where it started; it is now also how a
2435/// structural table edit works out what it did to the text. See
2436/// [`emit_content_change_events`].
2437pub(crate) struct UndoBlockState {
2438    id: u64,
2439    position: i64,
2440    text_length: i64,
2441    plain_text: String,
2442    format: BlockFormat,
2443}
2444
2445/// The blocks of the document, sorted by position, and its addressable text, as they were
2446/// at one moment: what [`emit_content_change_events`] compares with the document as it is.
2447pub(crate) struct BlockStates {
2448    blocks: Vec<UndoBlockState>,
2449    text: String,
2450}
2451
2452/// Capture the state of all blocks, sorted by document_position, and the document's
2453/// addressable text.
2454///
2455/// Reads through the store rather than the plain-text cache, so a caller does
2456/// not have to have invalidated anything first.
2457pub(crate) fn capture_block_state(inner: &TextDocumentInner) -> BlockStates {
2458    let mut all_blocks =
2459        frontend::commands::block_commands::get_all_block(&inner.ctx).unwrap_or_default();
2460    let store = inner.ctx.db_context.get_store();
2461    crate::inner::refresh_block_positions(&mut all_blocks, store);
2462    let mut states: Vec<UndoBlockState> = all_blocks
2463        .into_iter()
2464        .map(|b| {
2465            let format = BlockFormat::from(&b);
2466            let entity: common::entities::Block = b.clone().into();
2467            let plain_text =
2468                common::database::rope_helpers::block_content_via_store(&entity, store);
2469            let text_length = common::database::rope_helpers::block_char_length(&entity, store);
2470            UndoBlockState {
2471                id: b.id,
2472                position: b.document_position,
2473                text_length,
2474                plain_text,
2475                format,
2476            }
2477        })
2478        .collect();
2479    states.sort_by_key(|s| s.position);
2480    let text = addressable_text_of(store, &states);
2481    BlockStates {
2482        blocks: states,
2483        text,
2484    }
2485}
2486
2487/// The document's addressable text ([`TextDocument::to_addressable_text`]), which `blocks`
2488/// are the sorted blocks of.
2489///
2490/// Every position the document deals out (a cursor, a block's position, `text_at`) indexes
2491/// this string, so a diff over it moves cursors and reports changes in their own space.
2492/// Joined without the `U+FFFC` anchor and separator of each table, as it once was, every
2493/// change after a table was read two characters early per table before it: an undo of
2494/// typing in a cell moved a cursor standing after the typing back by two, and inserting or
2495/// removing a table reported less than it changed.
2496///
2497/// It is the rope, as `to_addressable_text` reads it, whenever the rope's positions are the
2498/// document's. Otherwise it is rebuilt from the blocks' positions, each gap between two
2499/// blocks being their newline and, for each table between them, its anchor and the newline
2500/// after it.
2501fn addressable_text_of(store: &common::database::Store, blocks: &[UndoBlockState]) -> String {
2502    let text = common::database::rope_helpers::rope_full_text_if_flow_matches(store)
2503        .unwrap_or_else(|| build_doc_text(blocks));
2504    let end = blocks.last().map_or(0, |last| {
2505        last.position.max(0) as usize + last.text_length.max(0) as usize
2506    });
2507    debug_assert_eq!(
2508        end,
2509        text.chars().count(),
2510        "the blocks' positions are not positions in the addressable text"
2511    );
2512    text
2513}
2514
2515/// The addressable text rebuilt from sorted block states (see [`addressable_text_of`]).
2516fn build_doc_text(states: &[UndoBlockState]) -> String {
2517    let mut text = String::new();
2518    let mut length = 0usize;
2519    for (i, state) in states.iter().enumerate() {
2520        if i > 0 {
2521            text.push('\n');
2522            length += 1;
2523        }
2524        let position = state.position.max(0) as usize;
2525        debug_assert!(
2526            position >= length && (position - length).is_multiple_of(2),
2527            "a gap of {} characters before the block at {position} is not tables' anchors",
2528            position.saturating_sub(length)
2529        );
2530        while length + 2 <= position {
2531            text.push_str(crate::TABLE_ANCHOR);
2532            text.push('\n');
2533            length += 2;
2534        }
2535        text.push_str(&state.plain_text);
2536        length += state.plain_text.chars().count();
2537    }
2538    text
2539}
2540
2541/// Compute the precise edit between two strings by comparing common prefix and suffix.
2542/// Returns `(edit_offset, chars_removed, chars_added)`.
2543fn compute_text_edit(before: &str, after: &str) -> (usize, usize, usize) {
2544    let before_chars: Vec<char> = before.chars().collect();
2545    let after_chars: Vec<char> = after.chars().collect();
2546
2547    // Common prefix
2548    let prefix_len = before_chars
2549        .iter()
2550        .zip(after_chars.iter())
2551        .take_while(|(a, b)| a == b)
2552        .count();
2553
2554    // Common suffix (not overlapping with prefix)
2555    let before_remaining = before_chars.len() - prefix_len;
2556    let after_remaining = after_chars.len() - prefix_len;
2557    let suffix_len = before_chars
2558        .iter()
2559        .rev()
2560        .zip(after_chars.iter().rev())
2561        .take(before_remaining.min(after_remaining))
2562        .take_while(|(a, b)| a == b)
2563        .count();
2564
2565    let removed = before_remaining - suffix_len;
2566    let added = after_remaining - suffix_len;
2567
2568    (prefix_len, removed, added)
2569}
2570
2571/// The edit `minimal` ([`compute_text_edit`] of `before` and `after`) as an undo of an edit
2572/// that left its cursor at `left_at` reads it: inside a run of repeated text the same
2573/// change can start at several places, and [`compute_text_edit`] takes the last. Undoing
2574/// the insertion of `a` before `ab`, `aab` becomes `ab` by removing either `a`; the one the
2575/// edit put in ends where it left its cursor, at 1, and is the first. So the edit is moved
2576/// back while it reads the same, to where what it removes ends at `left_at` (the cursor
2577/// stood after what the edit put in, which the undo removes, and on the gap of what it took
2578/// away, which the undo puts back). `minimal` when there is no such place.
2579fn compute_text_edit_left_at(
2580    before: &str,
2581    after: &str,
2582    minimal: (usize, usize, usize),
2583    left_at: usize,
2584) -> (usize, usize, usize) {
2585    let (mut offset, removed, added) = minimal;
2586    if offset + removed < left_at {
2587        return minimal;
2588    }
2589    let before_chars: Vec<char> = before.chars().collect();
2590    let after_chars: Vec<char> = after.chars().collect();
2591    loop {
2592        if offset + removed == left_at {
2593            return (offset, removed, added);
2594        }
2595        // Moved back by one, the edit reads the same when the character it then leaves
2596        // to the text after it is the same before and after the change.
2597        if offset == 0 || before_chars[offset - 1 + removed] != after_chars[offset - 1 + added] {
2598            return minimal;
2599        }
2600        offset -= 1;
2601    }
2602}
2603
2604/// Compare block state before and after an edit and emit
2605/// `ContentsChanged` / `FormatChanged` events for the affected regions.
2606///
2607/// ## Why anything else would be a guess
2608///
2609/// The delta this computes is a **real text diff**, and consumers rely on that
2610/// being true rather than approximate: a comment anchor shifts by
2611/// `(position, chars_removed, chars_added)`, so a figure that is merely
2612/// plausible moves an anchor to somewhere that was never right — which is
2613/// harder to notice than not moving it at all.
2614///
2615/// That is why the table primitives call this rather than describing their own
2616/// edit. A row insert knows how many rows it added; it does not know where in
2617/// the document's text that lands, and working it out by hand would be seven
2618/// separate opportunities to be subtly wrong.
2619///
2620/// Used by undo, redo, every structural table edit, and inserting a table or a frame.
2621pub(crate) fn emit_content_change_events(inner: &mut TextDocumentInner, before: &BlockStates) {
2622    emit_content_change_events_near(inner, before, None);
2623}
2624
2625/// [`emit_content_change_events`], also saying where the text that changed ends now: where
2626/// an undo leaves the cursor that made the edit (see [`TextDocument::undo`]). `None` when
2627/// no text changed. Where the change sits inside a run of repeated text is ambiguous (a
2628/// deletion of the first `a` of `aab` reads the same as one of the second), and is read
2629/// as the undo of an edit that left its cursor at `left_at` (see
2630/// [`compute_text_edit_left_at`]): the event, the cursors and the end all take that place.
2631fn emit_content_change_events_near(
2632    inner: &mut TextDocumentInner,
2633    before: &BlockStates,
2634    left_at: Option<usize>,
2635) -> Option<usize> {
2636    let after = capture_block_state(inner);
2637    let (before_text, after_text) = (&before.text, &after.text);
2638    let (before, after) = (&before.blocks, &after.blocks);
2639    let mut changed_text_end = None;
2640
2641    // Build a map of block id → state for the "before" set.
2642    let before_map: std::collections::HashMap<u64, &UndoBlockState> =
2643        before.iter().map(|s| (s.id, s)).collect();
2644    let after_map: std::collections::HashMap<u64, &UndoBlockState> =
2645        after.iter().map(|s| (s.id, s)).collect();
2646
2647    // Track the affected content region (earliest position, total old/new length).
2648    let mut content_changed = false;
2649    let mut earliest_pos: Option<usize> = None;
2650    let mut old_end: usize = 0;
2651    let mut blocks_affected: usize = 0;
2652
2653    let mut format_only_changes: Vec<(usize, usize)> = Vec::new(); // (position, length)
2654
2655    // Check blocks present in both before and after.
2656    for after_state in after {
2657        if let Some(before_state) = before_map.get(&after_state.id) {
2658            let text_changed = before_state.plain_text != after_state.plain_text
2659                || before_state.text_length != after_state.text_length;
2660            let format_changed = before_state.format != after_state.format;
2661
2662            if text_changed {
2663                content_changed = true;
2664                blocks_affected += 1;
2665                let pos = after_state.position.max(0) as usize;
2666                earliest_pos = Some(earliest_pos.map_or(pos, |p: usize| p.min(pos)));
2667                old_end = old_end.max(
2668                    before_state.position.max(0) as usize
2669                        + before_state.text_length.max(0) as usize,
2670                );
2671            } else if format_changed {
2672                let pos = after_state.position.max(0) as usize;
2673                let len = after_state.text_length.max(0) as usize;
2674                format_only_changes.push((pos, len));
2675            }
2676        } else {
2677            // Block exists in after but not in before — new block from undo/redo.
2678            content_changed = true;
2679            blocks_affected += 1;
2680            let pos = after_state.position.max(0) as usize;
2681            earliest_pos = Some(earliest_pos.map_or(pos, |p: usize| p.min(pos)));
2682        }
2683    }
2684
2685    // Check blocks that were removed (present in before but not after).
2686    for before_state in before {
2687        if !after_map.contains_key(&before_state.id) {
2688            content_changed = true;
2689            blocks_affected += 1;
2690            let pos = before_state.position.max(0) as usize;
2691            earliest_pos = Some(earliest_pos.map_or(pos, |p: usize| p.min(pos)));
2692            old_end = old_end.max(pos + before_state.text_length.max(0) as usize);
2693        }
2694    }
2695
2696    if content_changed {
2697        // Use a precise text-level diff for cursor adjustment so cursors land
2698        // at the actual edit point rather than the end of the affected block.
2699        let minimal = compute_text_edit(before_text, after_text);
2700        let (edit_offset, precise_removed, precise_added) = match left_at {
2701            Some(left_at) => compute_text_edit_left_at(before_text, after_text, minimal, left_at),
2702            None => minimal,
2703        };
2704
2705        // The event reports the blocks that changed when they hold the precise change, and
2706        // the precise change when they do not: the blocks leave out a table's anchor,
2707        // which belongs to no block, so a table inserted or removed reported less than it
2708        // changed. A range that holds the precise change maps the text before onto the
2709        // text after, so the figures are a splice a consumer can shift its offsets by.
2710        let before_len = before_text.chars().count();
2711        let after_len = after_text.chars().count();
2712        let region_start = earliest_pos.unwrap_or(0).min(before_len);
2713        let region_end = old_end.clamp(region_start, before_len);
2714        let precise = precise_removed > 0 || precise_added > 0;
2715        let (position, chars_removed, chars_added) = if !precise
2716            || (region_start <= edit_offset && edit_offset + precise_removed <= region_end)
2717        {
2718            let removed = region_end - region_start;
2719            (
2720                region_start,
2721                removed,
2722                (removed + after_len).saturating_sub(before_len),
2723            )
2724        } else {
2725            (edit_offset, precise_removed, precise_added)
2726        };
2727        if precise_removed > 0 || precise_added > 0 {
2728            inner.adjust_cursors(edit_offset, precise_removed, precise_added);
2729            changed_text_end = Some(edit_offset + precise_added);
2730        }
2731
2732        inner.queue_event(DocumentEvent::ContentsChanged {
2733            position,
2734            chars_removed,
2735            chars_added,
2736            blocks_affected,
2737        });
2738        // **`Replayed`, hard-coded, and it cannot double-count.** Undo and redo
2739        // never re-enter the insertion API — they snapshot and diff, which is
2740        // why this function exists — so text restored by them is reported once,
2741        // under an origin that says it came back rather than arrived.
2742        //
2743        // ⚠ Measured as the document's **total** gain, not from `chars_added`.
2744        // That figure is the size of the restored region, which is non-zero for
2745        // an undo that removes text: reporting it would put `Replayed` on a
2746        // count of characters nothing brought back. A test caught exactly that.
2747        //
2748        // Reported where that text starts: where the change does, unless it starts on a
2749        // table's anchor, which belongs to no block, and the text then starts in the
2750        // table's first cell (an undo of the table's removal brings back the anchor, its
2751        // separator and then the cells' text).
2752        let before_len: i64 = before.iter().map(|b| b.text_length.max(0)).sum();
2753        let after_len: i64 = after.iter().map(|a| a.text_length.max(0)).sum();
2754        if after_len > before_len {
2755            let text_start = after
2756                .iter()
2757                .map(|state| state.position.max(0) as usize)
2758                .zip(after.iter().map(|state| state.text_length.max(0) as usize))
2759                .find(|&(start, length)| start + length >= edit_offset)
2760                .map_or(edit_offset, |(start, _)| start.max(edit_offset));
2761            inner.queue_event(DocumentEvent::TextInserted {
2762                position: text_start,
2763                chars_inserted: (after_len - before_len) as usize,
2764                origin: crate::InsertionOrigin::Replayed,
2765            });
2766        }
2767    }
2768
2769    // Emit FormatChanged for blocks where only formatting changed (not content).
2770    for (position, length) in format_only_changes {
2771        inner.queue_event(DocumentEvent::FormatChanged {
2772            position,
2773            length,
2774            kind: FormatChangeKind::Block,
2775        });
2776    }
2777    changed_text_end
2778}
2779
2780// ── Flow helpers ──────────────────────────────────────────────
2781
2782/// Get the main frame ID for the document.
2783/// Collect all block IDs in document order from a frame, recursing into nested
2784/// sub-frames (negative entries in child_order).
2785fn collect_frame_block_ids(
2786    inner: &TextDocumentInner,
2787    frame_id: frontend::common::types::EntityId,
2788) -> Option<Vec<u64>> {
2789    let frame_dto = frame_commands::get_frame(&inner.ctx, &frame_id)
2790        .ok()
2791        .flatten()?;
2792
2793    if !frame_dto.child_order.is_empty() {
2794        let mut block_ids = Vec::new();
2795        for &entry in &frame_dto.child_order {
2796            if entry > 0 {
2797                block_ids.push(entry as u64);
2798            } else if entry < 0 {
2799                let sub_frame_id = (-entry) as u64;
2800                let sub_frame = frame_commands::get_frame(&inner.ctx, &sub_frame_id)
2801                    .ok()
2802                    .flatten();
2803                if let Some(ref sf) = sub_frame {
2804                    if let Some(table_id) = sf.table {
2805                        // Table anchor frame: collect blocks from cell frames
2806                        // in row-major order, matching collect_block_ids_recursive.
2807                        if let Some(table_dto) = table_commands::get_table(&inner.ctx, &table_id)
2808                            .ok()
2809                            .flatten()
2810                        {
2811                            let mut cell_dtos: Vec<_> = table_dto
2812                                .cells
2813                                .iter()
2814                                .filter_map(|&cid| {
2815                                    table_cell_commands::get_table_cell(&inner.ctx, &cid)
2816                                        .ok()
2817                                        .flatten()
2818                                })
2819                                .collect();
2820                            cell_dtos
2821                                .sort_by(|a, b| a.row.cmp(&b.row).then(a.column.cmp(&b.column)));
2822                            for cell_dto in &cell_dtos {
2823                                if let Some(cf_id) = cell_dto.cell_frame
2824                                    && let Some(cf_ids) = collect_frame_block_ids(inner, cf_id)
2825                                {
2826                                    block_ids.extend(cf_ids);
2827                                }
2828                            }
2829                        }
2830                    } else if let Some(sub_ids) = collect_frame_block_ids(inner, sub_frame_id) {
2831                        block_ids.extend(sub_ids);
2832                    }
2833                }
2834            }
2835        }
2836        Some(block_ids)
2837    } else {
2838        Some(frame_dto.blocks.to_vec())
2839    }
2840}
2841
2842/// [`TextDocument::snapshot_flow_masked`] of `inner` (with `suppress_paint`,
2843/// [`TextDocument::snapshot_flow_masked_no_paint`]), which is the document as it is or,
2844/// inside [`TextDocumentInner::read_recorded`], as recorded.
2845pub(crate) fn flow_snapshot_of(
2846    inner: &TextDocumentInner,
2847    mask: &crate::highlight::HighlightMask,
2848    suppress_paint: bool,
2849) -> crate::flow::FlowSnapshot {
2850    let main_frame_id = get_main_frame_id(inner);
2851    let hl = crate::highlight::SnapshotHighlights {
2852        kind: inner.highlights.effective_kind(mask),
2853        mask,
2854        suppress_paint,
2855    };
2856    let elements = crate::text_frame::build_flow_snapshot(inner, main_frame_id, hl);
2857    crate::flow::FlowSnapshot { elements }
2858}
2859
2860/// [`TextDocument::snapshot_block_at_position_masked`] of `inner`, which is the document as
2861/// it is or, inside [`TextDocumentInner::read_recorded`], as recorded.
2862pub(crate) fn block_snapshot_at(
2863    inner: &TextDocumentInner,
2864    position: usize,
2865    mask: &crate::highlight::HighlightMask,
2866) -> Option<crate::flow::BlockSnapshot> {
2867    // Effective kind resolved once here (the join over the mask's sessions), then threaded
2868    // down with the mask itself.
2869    let hl = crate::highlight::SnapshotHighlights {
2870        kind: inner.highlights.effective_kind(mask),
2871        mask,
2872        suppress_paint: false,
2873    };
2874    let main_frame_id = get_main_frame_id(inner);
2875    let store = inner.ctx.db_context.get_store();
2876
2877    // Rope-authoritative fast path. When every block is mirrored to the
2878    // rope (now true with tables: see `rope_positions_match_flow`), the
2879    // rope IS the position space the snapshot reports in, so we must also
2880    // *locate* the block via the rope. Walking a hand-rolled `running_pos`
2881    // here instead would search in the old cells-inline-no-sentinel space
2882    // and then report the rope position: an off-by-the-sentinel mismatch
2883    // for any block after a table.
2884    if common::database::rope_helpers::rope_positions_match_flow(store)
2885        && let Some((block_id, _, _)) =
2886            common::database::rope_helpers::find_block_at_char_position(store, position as i64)
2887    {
2888        return crate::text_block::build_block_snapshot(inner, block_id, hl);
2889    }
2890
2891    // Collect all block IDs in document order, traversing into nested frames
2892    let ordered_block_ids = collect_frame_block_ids(inner, main_frame_id)?;
2893
2894    // Walk blocks computing positions on the fly
2895    let pos = position as i64;
2896    let mut running_pos: i64 = 0;
2897    for &block_id in &ordered_block_ids {
2898        let block_dto = block_commands::get_block(&inner.ctx, &block_id)
2899            .ok()
2900            .flatten()?;
2901        let entity: common::entities::Block = block_dto.clone().into();
2902        let block_end =
2903            running_pos + common::database::rope_helpers::block_char_length(&entity, store);
2904        if pos >= running_pos && pos <= block_end {
2905            return crate::text_block::build_block_snapshot_with_position(
2906                inner,
2907                block_id,
2908                Some(running_pos as usize),
2909                hl,
2910                &crate::text_block::SnapshotLookups::default(),
2911            );
2912        }
2913        running_pos = block_end + 1;
2914    }
2915
2916    // Fallback to last block
2917    if let Some(&last_id) = ordered_block_ids.last() {
2918        return crate::text_block::build_block_snapshot(inner, last_id, hl);
2919    }
2920    None
2921}
2922
2923pub(crate) fn get_main_frame_id(inner: &TextDocumentInner) -> frontend::common::types::EntityId {
2924    // The document's first frame is the main frame.
2925    let frames = frontend::commands::document_commands::get_document_relationship(
2926        &inner.ctx,
2927        &inner.document_id,
2928        &frontend::document::dtos::DocumentRelationshipField::Frames,
2929    )
2930    .unwrap_or_default();
2931
2932    frames.first().copied().unwrap_or(0)
2933}
2934
2935// ── Long-operation event data helpers ─────────────────────────
2936
2937/// Parse progress JSON: `{"id":"...", "percentage": 50.0, "message": "..."}`
2938fn parse_progress_data(data: &Option<String>) -> (String, f64, String) {
2939    let Some(json) = data else {
2940        return (String::new(), 0.0, String::new());
2941    };
2942    let v: serde_json::Value = serde_json::from_str(json).unwrap_or_default();
2943    let id = v["id"].as_str().unwrap_or_default().to_string();
2944    let pct = v["percentage"].as_f64().unwrap_or(0.0);
2945    let msg = v["message"].as_str().unwrap_or_default().to_string();
2946    (id, pct, msg)
2947}
2948
2949/// Parse completed/cancelled JSON: `{"id":"..."}`
2950fn parse_id_data(data: &Option<String>) -> String {
2951    let Some(json) = data else {
2952        return String::new();
2953    };
2954    let v: serde_json::Value = serde_json::from_str(json).unwrap_or_default();
2955    v["id"].as_str().unwrap_or_default().to_string()
2956}
2957
2958/// Parse failed JSON: `{"id":"...", "error":"..."}`
2959fn parse_failed_data(data: &Option<String>) -> (String, String) {
2960    let Some(json) = data else {
2961        return (String::new(), "unknown error".into());
2962    };
2963    let v: serde_json::Value = serde_json::from_str(json).unwrap_or_default();
2964    let id = v["id"].as_str().unwrap_or_default().to_string();
2965    let error = v["error"].as_str().unwrap_or("unknown error").to_string();
2966    (id, error)
2967}