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