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