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