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