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