Skip to main content

text_document/
text_block.rs

1//! Read-only block (paragraph) handle.
2
3use std::cell::{Cell, OnceCell};
4use std::collections::{HashMap, HashSet};
5use std::sync::Arc;
6
7use parking_lot::Mutex;
8
9use frontend::commands::{block_commands, document_commands, frame_commands, list_commands};
10use frontend::common::format_runs::{FormatRun, ImageAnchor, synth_element_id};
11use frontend::common::types::EntityId;
12
13use crate::convert::to_usize;
14use crate::flow::{
15    AddressablePiece, BlockSnapshot, FragmentContent, ListInfo, TableCellContext, TableCellRef,
16};
17use crate::inner::TextDocumentInner;
18use crate::text_frame::TextFrame;
19use crate::text_list::TextList;
20use crate::text_table::TextTable;
21use crate::{BlockFormat, ListStyle, TextFormat};
22
23/// A lightweight, read-only handle to a single block (paragraph).
24///
25/// Holds a stable entity ID — the handle remains valid across edits
26/// that insert or remove other blocks. Each method acquires the
27/// document lock independently. For consistent reads across multiple
28/// fields, use [`snapshot()`](TextBlock::snapshot).
29#[derive(Clone)]
30pub struct TextBlock {
31    pub(crate) doc: Arc<Mutex<TextDocumentInner>>,
32    pub(crate) block_id: usize,
33}
34
35impl TextBlock {
36    // ── Content ──────────────────────────────────────────────
37
38    /// Block's plain text. O(1).
39    pub fn text(&self) -> String {
40        let inner = self.doc.lock();
41        let store = inner.ctx.db_context.get_store();
42        block_commands::get_block(&inner.ctx, &(self.block_id as u64))
43            .ok()
44            .flatten()
45            .map(|b| {
46                let entity: common::entities::Block = b.into();
47                common::database::rope_helpers::block_content_via_store(&entity, store)
48            })
49            .unwrap_or_default()
50    }
51
52    /// Character count. O(1).
53    pub fn length(&self) -> usize {
54        let inner = self.doc.lock();
55        let store = inner.ctx.db_context.get_store();
56        block_commands::get_block(&inner.ctx, &(self.block_id as u64))
57            .ok()
58            .flatten()
59            .map(|b| {
60                let entity: common::entities::Block = b.into();
61                to_usize(common::database::rope_helpers::block_char_length(
62                    &entity, store,
63                ))
64            })
65            .unwrap_or(0)
66    }
67
68    /// `length() == 0`. O(1).
69    pub fn is_empty(&self) -> bool {
70        let inner = self.doc.lock();
71        let store = inner.ctx.db_context.get_store();
72        block_commands::get_block(&inner.ctx, &(self.block_id as u64))
73            .ok()
74            .flatten()
75            .map(|b| {
76                let entity: common::entities::Block = b.into();
77                common::database::rope_helpers::block_char_length(&entity, store) == 0
78            })
79            .unwrap_or(true)
80    }
81
82    /// Block entity still exists in the database. O(1).
83    pub fn is_valid(&self) -> bool {
84        let inner = self.doc.lock();
85        block_commands::get_block(&inner.ctx, &(self.block_id as u64))
86            .ok()
87            .flatten()
88            .is_some()
89    }
90
91    // ── Identity and Position ────────────────────────────────
92
93    /// Stable entity ID (stored in the handle). O(1).
94    pub fn id(&self) -> usize {
95        self.block_id
96    }
97
98    /// Character offset of this block's start in the document. O(log n)
99    /// via the rope index for rope-clean documents; O(1) read of the
100    /// stored field for tabled documents.
101    pub fn position(&self) -> usize {
102        let inner = self.doc.lock();
103        let Some(mut dto) = block_commands::get_block(&inner.ctx, &(self.block_id as u64))
104            .ok()
105            .flatten()
106        else {
107            return 0;
108        };
109        let store = inner.ctx.db_context.get_store();
110        crate::inner::refresh_block_position(&mut dto, store);
111        to_usize(dto.document_position)
112    }
113
114    /// Global 0-indexed block number. **O(n)**: requires scanning all blocks
115    /// sorted by `document_position`. Prefer [`id()`](TextBlock::id) for
116    /// identity and [`position()`](TextBlock::position) for ordering.
117    pub fn block_number(&self) -> usize {
118        let inner = self.doc.lock();
119        compute_block_number(&inner, self.block_id as u64)
120    }
121
122    /// The next block in document order. **O(n)**.
123    /// Returns `None` if this is the last block.
124    pub fn next(&self) -> Option<TextBlock> {
125        let inner = self.doc.lock();
126        let all_blocks = block_commands::get_all_block(&inner.ctx).ok()?;
127        let mut sorted: Vec<_> = all_blocks.into_iter().collect();
128        let store = inner.ctx.db_context.get_store();
129        crate::inner::refresh_block_positions(&mut sorted, store);
130        sorted.sort_by_key(|b| b.document_position);
131        let idx = sorted.iter().position(|b| b.id == self.block_id as u64)?;
132        sorted.get(idx + 1).map(|b| TextBlock {
133            doc: Arc::clone(&self.doc),
134            block_id: b.id as usize,
135        })
136    }
137
138    /// The previous block in document order. **O(n)**.
139    /// Returns `None` if this is the first block.
140    pub fn previous(&self) -> Option<TextBlock> {
141        let inner = self.doc.lock();
142        let all_blocks = block_commands::get_all_block(&inner.ctx).ok()?;
143        let mut sorted: Vec<_> = all_blocks.into_iter().collect();
144        let store = inner.ctx.db_context.get_store();
145        crate::inner::refresh_block_positions(&mut sorted, store);
146        sorted.sort_by_key(|b| b.document_position);
147        let idx = sorted.iter().position(|b| b.id == self.block_id as u64)?;
148        if idx == 0 {
149            return None;
150        }
151        sorted.get(idx - 1).map(|b| TextBlock {
152            doc: Arc::clone(&self.doc),
153            block_id: b.id as usize,
154        })
155    }
156
157    // ── Structural Context ───────────────────────────────────
158
159    /// Parent frame. O(1).
160    pub fn frame(&self) -> TextFrame {
161        let inner = self.doc.lock();
162        let frame_id = find_parent_frame(&inner, self.block_id as u64);
163        TextFrame {
164            doc: Arc::clone(&self.doc),
165            frame_id: frame_id.map(|id| id as usize).unwrap_or(0),
166        }
167    }
168
169    /// If inside a table cell, returns table and cell coordinates.
170    ///
171    /// Finds the block's parent frame, then checks if any table cell
172    /// references that frame as its `cell_frame`. If so, identifies the
173    /// owning table.
174    pub fn table_cell(&self) -> Option<TableCellRef> {
175        let inner = self.doc.lock();
176        let frame_id = find_parent_frame(&inner, self.block_id as u64)?;
177
178        // Check if this frame is referenced as a cell_frame by any table cell.
179        // First try the fast path: if the frame has a `table` field, use it.
180        let frame_dto = frame_commands::get_frame(&inner.ctx, &frame_id)
181            .ok()
182            .flatten()?;
183
184        if let Some(table_entity_id) = frame_dto.table {
185            // This frame is a table anchor frame (not a cell frame).
186            // Anchor frames don't contain blocks directly — cell frames do.
187            // So this path shouldn't match, but check cells just in case.
188            let table_dto =
189                frontend::commands::table_commands::get_table(&inner.ctx, &{ table_entity_id })
190                    .ok()
191                    .flatten()?;
192            for &cell_id in &table_dto.cells {
193                if let Some(cell_dto) =
194                    frontend::commands::table_cell_commands::get_table_cell(&inner.ctx, &{
195                        cell_id
196                    })
197                    .ok()
198                    .flatten()
199                    && cell_dto.cell_frame == Some(frame_id)
200                {
201                    return Some(TableCellRef {
202                        table: TextTable {
203                            doc: Arc::clone(&self.doc),
204                            table_id: table_entity_id as usize,
205                        },
206                        row: to_usize(cell_dto.row),
207                        column: to_usize(cell_dto.column),
208                    });
209                }
210            }
211        }
212
213        // Slow path: this frame has no `table` field (cell frames don't).
214        // Scan all tables to find if any cell references this frame.
215        let all_tables =
216            frontend::commands::table_commands::get_all_table(&inner.ctx).unwrap_or_default();
217        for table_dto in &all_tables {
218            for &cell_id in &table_dto.cells {
219                if let Some(cell_dto) =
220                    frontend::commands::table_cell_commands::get_table_cell(&inner.ctx, &{
221                        cell_id
222                    })
223                    .ok()
224                    .flatten()
225                    && cell_dto.cell_frame == Some(frame_id)
226                {
227                    return Some(TableCellRef {
228                        table: TextTable {
229                            doc: Arc::clone(&self.doc),
230                            table_id: table_dto.id as usize,
231                        },
232                        row: to_usize(cell_dto.row),
233                        column: to_usize(cell_dto.column),
234                    });
235                }
236            }
237        }
238
239        None
240    }
241
242    // ── Formatting ──────────────────────────────────────────
243
244    /// Block format (alignment, margins, indent, heading level, marker, tabs). O(1).
245    pub fn block_format(&self) -> BlockFormat {
246        let inner = self.doc.lock();
247        block_commands::get_block(&inner.ctx, &(self.block_id as u64))
248            .ok()
249            .flatten()
250            .map(|b| BlockFormat::from(&b))
251            .unwrap_or_default()
252    }
253
254    /// Character format at a block-relative character offset. **O(k)**
255    /// where k = format runs + image anchors in this block.
256    ///
257    /// Returns the [`TextFormat`] of the fragment containing the given
258    /// offset. Returns `None` if the offset is out of range or the
259    /// block has no fragments.
260    pub fn char_format_at(&self, offset: usize) -> Option<TextFormat> {
261        let inner = self.doc.lock();
262        let fragments = build_fragments(&inner, self.block_id as u64);
263        for frag in &fragments {
264            match frag {
265                FragmentContent::Text {
266                    format,
267                    offset: frag_offset,
268                    length,
269                    ..
270                } => {
271                    if offset >= *frag_offset && offset < frag_offset + length {
272                        return Some(format.clone());
273                    }
274                }
275                FragmentContent::Image {
276                    format,
277                    offset: frag_offset,
278                    ..
279                }
280                | FragmentContent::FootnoteReference {
281                    format,
282                    offset: frag_offset,
283                    ..
284                } => {
285                    if offset == *frag_offset {
286                        return Some(format.clone());
287                    }
288                }
289            }
290        }
291        None
292    }
293
294    // ── Fragments ───────────────────────────────────────────
295
296    /// Shaping-input fragments: base formatting plus any *metric-affecting*
297    /// syntax highlights (bold / italic / size / family / spacing). This is
298    /// what the layout engine shapes. **Paint-only highlights (colors,
299    /// underline decorations) are NOT merged here** — they are kept separate
300    /// in [`BlockSnapshot::paint_highlights`](crate::BlockSnapshot::paint_highlights)
301    /// as a post-shape recolor overlay, so the shaping input stays stable
302    /// across paint-only highlight changes. For the fully-merged *visual*
303    /// fragments, use [`display_fragments`](Self::display_fragments).
304    ///
305    /// O(k) where k = format runs + image anchors in this block.
306    pub fn fragments(&self) -> Vec<FragmentContent> {
307        let inner = self.doc.lock();
308        build_fragments(&inner, self.block_id as u64)
309    }
310
311    /// Fragments as they should be *displayed*: base formatting with **all**
312    /// active syntax highlights merged in, including paint-only ones. This is
313    /// the "what it looks like" view — useful for a non-optimized renderer,
314    /// for accessibility, or for tests. The optimized layout path instead uses
315    /// [`fragments`](Self::fragments) (shaping input) plus the separate
316    /// [`BlockSnapshot::paint_highlights`](crate::BlockSnapshot::paint_highlights)
317    /// overlay. Equivalent to the pre-overlay behaviour of `fragments()`.
318    pub fn display_fragments(&self) -> Vec<FragmentContent> {
319        let inner = self.doc.lock();
320        let fragments = build_raw_fragments(
321            &inner,
322            self.block_id as u64,
323            None,
324            &SnapshotLookups::default(),
325        );
326        // The fully-merged visual view: every session, regardless of the paint-vs-metric
327        // split the optimized path draws on.
328        let spans = crate::highlight::merged_spans_for_block(
329            &inner,
330            self.block_id,
331            &crate::highlight::HighlightMask::ALL,
332        );
333        if !spans.is_empty() {
334            return crate::highlight::merge_highlight_spans(fragments, &spans);
335        }
336        fragments
337    }
338
339    // ── Addressable Inline Pieces ─────────────────────────────
340
341    /// The block's inline pieces (text runs, images, footnote references), addressed in
342    /// the document's own addressable character space rather than block-relative — see
343    /// [`AddressablePiece`]. **O(k)** where k = format runs + image anchors + footnote
344    /// references in this block.
345    ///
346    /// Reach for this instead of [`fragments`](Self::fragments) /
347    /// [`display_fragments`](Self::display_fragments) — whose `offset` is block-relative,
348    /// fine for the layout engine that consumes them one block at a time — whenever a piece
349    /// boundary needs comparing against something addressed in the *document's* own space:
350    /// a comment's stored character range, a
351    /// [`TextDocument::find_all`](crate::TextDocument::find_all) match position,
352    /// another block's [`position()`](Self::position).
353    ///
354    /// Thin wrapper over [`common::format_runs_query::addressable_inline_pieces_for_block`]
355    /// — the same accessor a DOCX/ODT export writer reaches for below the public API, so a
356    /// piece boundary computed here and one computed there can never disagree.
357    pub fn addressable_inline_pieces(&self) -> Vec<AddressablePiece> {
358        let inner = self.doc.lock();
359        let Some(block_dto) = block_commands::get_block(&inner.ctx, &(self.block_id as u64))
360            .ok()
361            .flatten()
362        else {
363            return Vec::new();
364        };
365        let entity: common::entities::Block = block_dto.into();
366        let store = inner.ctx.db_context.get_store();
367        let plain_text = common::database::rope_helpers::block_content_via_store(&entity, store);
368        common::format_runs_query::addressable_inline_pieces_for_block(store, &entity, &plain_text)
369            .into_iter()
370            .map(|p| AddressablePiece {
371                start: to_usize(p.start as i64),
372                end: to_usize(p.end as i64),
373                content: p.content,
374                format: TextFormat::from(&p.format),
375            })
376            .collect()
377    }
378
379    // ── List Membership ─────────────────────────────────────
380
381    /// List this block belongs to. O(1).
382    pub fn list(&self) -> Option<TextList> {
383        let inner = self.doc.lock();
384        let block_dto = block_commands::get_block(&inner.ctx, &(self.block_id as u64))
385            .ok()
386            .flatten()?;
387        let list_id = block_dto.list?;
388        Some(TextList {
389            doc: Arc::clone(&self.doc),
390            list_id: list_id as usize,
391        })
392    }
393
394    /// 0-based position within its list. **O(n)** where n = total blocks.
395    pub fn list_item_index(&self) -> Option<usize> {
396        let inner = self.doc.lock();
397        let block_dto = block_commands::get_block(&inner.ctx, &(self.block_id as u64))
398            .ok()
399            .flatten()?;
400        let list_id = block_dto.list?;
401        Some(compute_list_item_index(
402            &inner,
403            list_id,
404            self.block_id as u64,
405        ))
406    }
407
408    // ── Snapshot ─────────────────────────────────────────────
409
410    /// All layout-relevant data in one lock acquisition. O(k+n).
411    pub fn snapshot(&self) -> BlockSnapshot {
412        let inner = self.doc.lock();
413        build_block_snapshot(
414            &inner,
415            self.block_id as u64,
416            crate::highlight::SnapshotHighlights {
417                kind: inner.highlight_kind,
418                mask: &crate::highlight::HighlightMask::ALL,
419                suppress_paint: false,
420            },
421        )
422        .unwrap_or_else(|| BlockSnapshot {
423            block_id: self.block_id,
424            position: 0,
425            length: 0,
426            text: String::new(),
427            fragments: Vec::new(),
428            block_format: BlockFormat::default(),
429            list_info: None,
430            parent_frame_id: None,
431            table_cell: None,
432            paint_highlights: Vec::new(),
433        })
434    }
435}
436
437// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
438// Internal helpers (called while lock is held)
439// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
440
441/// Find the parent frame of a block by scanning all frames.
442pub(crate) fn find_parent_frame(inner: &TextDocumentInner, block_id: u64) -> Option<EntityId> {
443    whole_document_read();
444    let all_frames = frame_commands::get_all_frame(&inner.ctx).ok()?;
445    let block_entity_id = block_id as EntityId;
446    for frame in &all_frames {
447        if frame.blocks.contains(&block_entity_id) {
448            return Some(frame.id as EntityId);
449        }
450    }
451    None
452}
453
454/// O(1) fast check used by the snapshot hot path: returns true iff the
455/// store has zero table entities. Used to skip the expensive
456/// `find_table_cell_context` walks for documents that have no tables
457/// (e.g. typical markdown documents in an editor).
458fn document_has_no_tables(inner: &TextDocumentInner) -> bool {
459    inner.ctx.db_context.get_store().tables.read().is_empty()
460}
461
462/// Find table cell context for a block (snapshot-friendly, no live handles).
463/// Returns `None` if the block is not inside a table cell.
464fn find_table_cell_context(inner: &TextDocumentInner, block_id: u64) -> Option<TableCellContext> {
465    // Fast exit: a doc with no tables can't have any cell-bound blocks.
466    // Avoids per-block `get_all_frame` + `get_all_table` walks during
467    // snapshot_flow, which is called per editor pane on every keystroke.
468    if document_has_no_tables(inner) {
469        return None;
470    }
471    whole_document_read();
472    let frame_id = find_parent_frame(inner, block_id)?;
473
474    let frame_dto = frame_commands::get_frame(&inner.ctx, &frame_id)
475        .ok()
476        .flatten()?;
477
478    // Fast path: anchor frame with `table` field set
479    if let Some(table_entity_id) = frame_dto.table {
480        let table_dto =
481            frontend::commands::table_commands::get_table(&inner.ctx, &{ table_entity_id })
482                .ok()
483                .flatten()?;
484        for &cell_id in &table_dto.cells {
485            if let Some(cell_dto) =
486                frontend::commands::table_cell_commands::get_table_cell(&inner.ctx, &{ cell_id })
487                    .ok()
488                    .flatten()
489                && cell_dto.cell_frame == Some(frame_id)
490            {
491                return Some(TableCellContext {
492                    table_id: table_entity_id as usize,
493                    row: to_usize(cell_dto.row),
494                    column: to_usize(cell_dto.column),
495                });
496            }
497        }
498    }
499
500    // Slow path: scan all tables for a cell referencing this frame
501    let all_tables =
502        frontend::commands::table_commands::get_all_table(&inner.ctx).unwrap_or_default();
503    for table_dto in &all_tables {
504        for &cell_id in &table_dto.cells {
505            if let Some(cell_dto) =
506                frontend::commands::table_cell_commands::get_table_cell(&inner.ctx, &{ cell_id })
507                    .ok()
508                    .flatten()
509                && cell_dto.cell_frame == Some(frame_id)
510            {
511                return Some(TableCellContext {
512                    table_id: table_dto.id as usize,
513                    row: to_usize(cell_dto.row),
514                    column: to_usize(cell_dto.column),
515                });
516            }
517        }
518    }
519
520    None
521}
522
523/// Whole-document facts a block snapshot reads, each worked out at most once per snapshot
524/// and then shared by every block it covers.
525///
526/// A list item's number, the frame that lists a block, the table cell it sits in, what a
527/// footnote reference prints and the document's default language are facts about the
528/// whole document: finding one for a single block walks every block, frame, table or note
529/// in the store. A flow snapshot used to repeat that walk for every block, so its cost grew
530/// with the square of the text: opening a long document holding a list, a table or
531/// footnotes froze the editor for seconds, and every keystroke that took a new snapshot
532/// paid it again. The answers here are the ones the per-block walks give.
533///
534/// The three facts that differ from block to block (its parent frame, its table cell, its
535/// list number) are indexed only once a second block asks: see [`OnSecondAsk`]. The other
536/// three are one value for the whole document, kept from the first ask.
537///
538/// Lives for one hold of the document lock, like the snapshot it serves.
539#[derive(Default)]
540pub(crate) struct SnapshotLookups {
541    frames: OnSecondAsk<FrameLookup>,
542    cells: OnSecondAsk<CellLookup>,
543    list_item_indices: OnSecondAsk<HashMap<(EntityId, EntityId), usize>>,
544    default_language: OnceCell<Option<String>>,
545    footnote_markers: OnceCell<HashMap<String, String>>,
546    self_footnote_numbers: OnceCell<HashMap<String, usize>>,
547}
548
549/// An index over the whole document, built only once a second question needs it.
550///
551/// The first question is answered by the walk that serves one block, which costs less than
552/// building the index, so a snapshot of a single block (the incremental relayout path, a
553/// code editor's visible rows) costs what it did before. A second question means more are
554/// coming, and the index then answers every one of them for the price of one more walk.
555struct OnSecondAsk<T> {
556    asked: Cell<bool>,
557    index: OnceCell<T>,
558}
559
560impl<T> Default for OnSecondAsk<T> {
561    fn default() -> Self {
562        Self {
563            asked: Cell::new(false),
564            index: OnceCell::new(),
565        }
566    }
567}
568
569impl<T> OnSecondAsk<T> {
570    /// `None` on the first ask, which the caller answers with its one-block walk; the
571    /// index, built with `build` if need be, on every later one.
572    fn get(&self, build: impl FnOnce() -> T) -> Option<&T> {
573        if let Some(index) = self.index.get() {
574            return Some(index);
575        }
576        if !self.asked.replace(true) {
577            return None;
578        }
579        Some(self.index.get_or_init(build))
580    }
581
582    /// The index, built with `build` if need be, whatever was asked before: for a question
583    /// that already had its own first ask.
584    fn force(&self, build: impl FnOnce() -> T) -> &T {
585        self.asked.set(true);
586        self.index.get_or_init(build)
587    }
588}
589
590/// Mark one read of a whole-document fact on the snapshot path: a walk of every block,
591/// frame, table or note, or a copy of a document-wide list. Unit tests count them, which is
592/// how `tests::a_flow_snapshot_reads_each_whole_document_fact_a_fixed_number_of_times`
593/// guards the snapshot's cost in the debug builds CI tests with, where timing it cannot.
594fn whole_document_read() {
595    #[cfg(test)]
596    tests::WHOLE_DOCUMENT_READS.with(|reads| reads.set(reads.get() + 1));
597}
598
599/// Every frame's blocks and table, from one pass over the frames.
600struct FrameLookup {
601    /// The frame [`find_parent_frame`] names for each block: the first frame, in the
602    /// store's order, whose `blocks` list it.
603    parent_of_block: HashMap<EntityId, EntityId>,
604    /// Each frame's `table` field.
605    table_of_frame: HashMap<EntityId, Option<EntityId>>,
606}
607
608impl FrameLookup {
609    fn build(inner: &TextDocumentInner) -> Self {
610        whole_document_read();
611        let all_frames = frame_commands::get_all_frame(&inner.ctx).unwrap_or_default();
612        let mut parent_of_block = HashMap::new();
613        let mut table_of_frame = HashMap::with_capacity(all_frames.len());
614        for frame in &all_frames {
615            for &block_id in &frame.blocks {
616                parent_of_block.entry(block_id).or_insert(frame.id);
617            }
618            table_of_frame.insert(frame.id, frame.table);
619        }
620        Self {
621            parent_of_block,
622            table_of_frame,
623        }
624    }
625}
626
627/// Every table cell's coordinates, from one pass over the tables, keyed the two ways
628/// [`find_table_cell_context`] searches for a cell frame.
629struct CellLookup {
630    tables: HashSet<EntityId>,
631    /// The first cell in `table`'s own list whose frame is `frame`, by `(table, frame)`.
632    in_table: HashMap<(EntityId, EntityId), TableCellContext>,
633    /// The first cell whose frame is `frame`, tables in the store's order, by frame.
634    anywhere: HashMap<EntityId, TableCellContext>,
635}
636
637impl CellLookup {
638    fn build(inner: &TextDocumentInner) -> Self {
639        whole_document_read();
640        let all_tables =
641            frontend::commands::table_commands::get_all_table(&inner.ctx).unwrap_or_default();
642        let mut tables = HashSet::with_capacity(all_tables.len());
643        let mut in_table = HashMap::new();
644        let mut anywhere = HashMap::new();
645        for table_dto in &all_tables {
646            tables.insert(table_dto.id);
647            for &cell_id in &table_dto.cells {
648                let Some(cell_dto) =
649                    frontend::commands::table_cell_commands::get_table_cell(&inner.ctx, &{
650                        cell_id
651                    })
652                    .ok()
653                    .flatten()
654                else {
655                    continue;
656                };
657                let Some(frame_id) = cell_dto.cell_frame else {
658                    continue;
659                };
660                let context = TableCellContext {
661                    table_id: table_dto.id as usize,
662                    row: to_usize(cell_dto.row),
663                    column: to_usize(cell_dto.column),
664                };
665                in_table
666                    .entry((table_dto.id, frame_id))
667                    .or_insert_with(|| context.clone());
668                anywhere.entry(frame_id).or_insert(context);
669            }
670        }
671        Self {
672            tables,
673            in_table,
674            anywhere,
675        }
676    }
677}
678
679impl SnapshotLookups {
680    /// The frame whose `blocks` list `block_id`: [`find_parent_frame`]'s answer.
681    fn parent_frame(&self, inner: &TextDocumentInner, block_id: u64) -> Option<EntityId> {
682        match self.frames.get(|| FrameLookup::build(inner)) {
683            Some(frames) => frames.parent_of_block.get(&block_id).copied(),
684            None => find_parent_frame(inner, block_id),
685        }
686    }
687
688    /// The table cell `block_id` sits in: [`find_table_cell_context`]'s answer.
689    fn table_cell_context(
690        &self,
691        inner: &TextDocumentInner,
692        block_id: u64,
693    ) -> Option<TableCellContext> {
694        if document_has_no_tables(inner) {
695            return None;
696        }
697        let Some(cells) = self.cells.get(|| CellLookup::build(inner)) else {
698            return find_table_cell_context(inner, block_id);
699        };
700        let frames = self.frames.force(|| FrameLookup::build(inner));
701        let frame_id = *frames.parent_of_block.get(&block_id)?;
702        // A frame naming a table is looked for in that table first, and a table it names
703        // that no longer exists ends the search, as in the one-block walk.
704        if let Some(Some(table_id)) = frames.table_of_frame.get(&frame_id) {
705            if !cells.tables.contains(table_id) {
706                return None;
707            }
708            if let Some(context) = cells.in_table.get(&(*table_id, frame_id)) {
709                return Some(context.clone());
710            }
711        }
712        cells.anywhere.get(&frame_id).cloned()
713    }
714
715    /// `block_id`'s 0-based index among `list_id`'s blocks: [`compute_list_item_index`]'s
716    /// answer.
717    fn list_item_index(
718        &self,
719        inner: &TextDocumentInner,
720        list_id: EntityId,
721        block_id: u64,
722    ) -> usize {
723        let build = || {
724            whole_document_read();
725            let mut all_blocks = block_commands::get_all_block(&inner.ctx).unwrap_or_default();
726            let store = inner.ctx.db_context.get_store();
727            crate::inner::refresh_block_positions(&mut all_blocks, store);
728            // Each list's blocks in the order the store gives them, then sorted stably by
729            // position: the order the one-block walk sorts each list into.
730            let mut members: HashMap<EntityId, Vec<(i64, EntityId)>> = HashMap::new();
731            for block in &all_blocks {
732                if let Some(list) = block.list {
733                    members
734                        .entry(list)
735                        .or_default()
736                        .push((block.document_position, block.id));
737                }
738            }
739            let mut indices = HashMap::new();
740            for (list, mut blocks) in members {
741                blocks.sort_by_key(|&(position, _)| position);
742                for (index, (_, id)) in blocks.into_iter().enumerate() {
743                    indices.entry((list, id)).or_insert(index);
744                }
745            }
746            indices
747        };
748        match self.list_item_indices.get(build) {
749            Some(indices) => indices.get(&(list_id, block_id)).copied().unwrap_or(0),
750            None => compute_list_item_index(inner, list_id, block_id),
751        }
752    }
753
754    /// The language a block that sets none inherits: the document's default.
755    fn default_language(&self, inner: &TextDocumentInner) -> Option<String> {
756        self.default_language
757            .get_or_init(|| {
758                whole_document_read();
759                document_commands::get_document(&inner.ctx, &inner.document_id)
760                    .ok()
761                    .flatten()
762                    .and_then(|d| d.default_language)
763            })
764            .clone()
765    }
766
767    /// What the host says each footnote label prints.
768    fn footnote_markers(&self, inner: &TextDocumentInner) -> &HashMap<String, String> {
769        self.footnote_markers.get_or_init(|| {
770            whole_document_read();
771            inner
772                .ctx
773                .db_context
774                .get_store()
775                .footnote_markers
776                .read()
777                .clone()
778        })
779    }
780
781    /// Every footnote label's number in the document's own reading order.
782    fn self_footnote_numbers(&self, inner: &TextDocumentInner) -> &HashMap<String, usize> {
783        self.self_footnote_numbers
784            .get_or_init(|| document_self_footnote_numbers(inner.ctx.db_context.get_store()))
785    }
786}
787
788/// Compute 0-indexed block number by scanning all blocks sorted by document_position.
789fn compute_block_number(inner: &TextDocumentInner, block_id: u64) -> usize {
790    let mut all_blocks = block_commands::get_all_block(&inner.ctx).unwrap_or_default();
791    let store = inner.ctx.db_context.get_store();
792    crate::inner::refresh_block_positions(&mut all_blocks, store);
793    let mut sorted: Vec<_> = all_blocks.iter().collect();
794    sorted.sort_by_key(|b| b.document_position);
795    sorted.iter().position(|b| b.id == block_id).unwrap_or(0)
796}
797
798/// Build fragments for a block from its format runs and image anchors,
799/// with highlight spans merged in when a syntax highlighter is attached.
800pub(crate) fn build_fragments(inner: &TextDocumentInner, block_id: u64) -> Vec<FragmentContent> {
801    build_fragments_with_text(
802        inner,
803        block_id,
804        None,
805        crate::highlight::SnapshotHighlights {
806            kind: inner.highlight_kind,
807            mask: &crate::highlight::HighlightMask::ALL,
808            suppress_paint: false,
809        },
810        &SnapshotLookups::default(),
811    )
812}
813
814/// Like `build_fragments` but accepts a pre-materialized block text to
815/// avoid the double `block_content_via_store` allocation when the
816/// caller (e.g. `build_block_snapshot_with_position_and_parent`)
817/// already has the text. Per-block snapshot cost halves for typing in
818/// a multi-block document.
819pub(crate) fn build_fragments_with_text(
820    inner: &TextDocumentInner,
821    block_id: u64,
822    prefetched_text: Option<&str>,
823    hl: crate::highlight::SnapshotHighlights,
824    lookups: &SnapshotLookups,
825) -> Vec<FragmentContent> {
826    let fragments = build_raw_fragments(inner, block_id, prefetched_text, lookups);
827
828    // Only merge highlights into the shaping input when the effective kind is
829    // metric-affecting. Paint-only sessions keep fragments as BASE and carry their spans
830    // separately in `BlockSnapshot::paint_highlights`, so the engine can recolor without
831    // reshaping. A "without highlights" (empty-mask) snapshot resolves to `kind == None`,
832    // forcing base fragments regardless of the live sessions. See `HighlighterKind`.
833    if hl.kind == crate::highlight::HighlighterKind::Metric {
834        let spans = crate::highlight::merged_spans_for_block(inner, block_id as usize, hl.mask);
835        if !spans.is_empty() {
836            return crate::highlight::merge_highlight_spans(fragments, &spans);
837        }
838    }
839
840    fragments
841}
842
843/// Every footnote label's number, counted the document numbers its own
844/// references in reading order — blocks by `document_position`, then within a
845/// block by byte offset, first appearance of a label wins, 1-based. A
846/// definition frame's own blocks are excluded from the walk (a note that
847/// itself cites another note must not number the inner reference by where the
848/// *definition* sits).
849///
850/// This is `document_io::footnotes::Footnotes::build`'s `numbers` computation,
851/// duplicated rather than shared: `document_io` is a backend/export crate this
852/// one (`public_api`, i.e. the live editor) does not — and should not —
853/// depend on, since it pulls in every exporter for what is, here, a handful
854/// of lines over `common::database::Store`, which both crates already depend
855/// on directly. If the numbering rule ever changes, it has to change in both
856/// places — grep `Footnotes::build` in `document_io` before touching this.
857///
858/// The fallback tier `TextDocument::set_footnote_markers`'s doc promises
859/// ("Leave it unset and the document numbers its own references in reading
860/// order, which is right when the document *is* the whole text") and that
861/// `document_io::Footnotes::marker` actually implements as ITS fallback
862/// before finally falling back to the raw label — the exact tier
863/// `build_raw_fragments` was missing, which is why a host that never calls
864/// `set_footnote_markers` (the documented, supported "unset" case — every
865/// host does not manage its own note numbering the way Skribisto does) saw
866/// the live editor draw raw labels while every export numbered correctly.
867fn document_self_footnote_numbers(
868    store: &common::database::Store,
869) -> std::collections::HashMap<String, usize> {
870    whole_document_read();
871    let definition_blocks: std::collections::HashSet<common::types::EntityId> = store
872        .frames
873        .read()
874        .values()
875        .filter(|f| f.footnote_label.is_some())
876        .flat_map(|f| f.child_order.iter().copied())
877        .filter(|child| *child > 0)
878        .map(|child| child as common::types::EntityId)
879        .collect();
880
881    let mut ordered: Vec<(i64, common::types::EntityId)> = store
882        .blocks
883        .read()
884        .values()
885        .filter(|b| !definition_blocks.contains(&b.id))
886        .map(|b| (b.document_position, b.id))
887        .collect();
888    ordered.sort_unstable();
889
890    let refs = store.block_footnote_refs.read();
891    let mut numbers: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
892    let mut next = 1usize;
893    for (_, block_id) in ordered {
894        let Some(anchors) = refs.get(&block_id) else {
895            continue;
896        };
897        let mut in_block: Vec<_> = anchors.iter().collect();
898        in_block.sort_by_key(|a| a.byte_offset);
899        for anchor in in_block {
900            numbers.entry(anchor.label.clone()).or_insert_with(|| {
901                let n = next;
902                next += 1;
903                n
904            });
905        }
906    }
907    numbers
908}
909
910/// Build raw fragments from the block's format_runs and block_images
911/// tables (Phase 1 of the rope migration). Reads the per-block plain_text
912/// from the Block DTO and uses the format-run byte ranges + image
913/// anchors to produce a stream of `FragmentContent::{Text, Image}`
914/// values in document order.
915///
916/// `element_id` is synthesized from (block_id, byte_start) via
917/// `synth_element_id`. Synthesized ids are stable for the same
918/// (block, byte_start) pair and never collide with real entity ids
919/// (top bit set).
920///
921/// Uncovered byte ranges between runs (or before the first run / after
922/// the last) emit Text fragments with `TextFormat::default()` — the
923/// "no character formatting" case.
924fn build_raw_fragments(
925    inner: &TextDocumentInner,
926    block_id: u64,
927    prefetched_text: Option<&str>,
928    lookups: &SnapshotLookups,
929) -> Vec<FragmentContent> {
930    let _block_dto = match block_commands::get_block(&inner.ctx, &block_id)
931        .ok()
932        .flatten()
933    {
934        Some(b) => b,
935        None => return Vec::new(),
936    };
937
938    let plain_owned;
939    let plain: &str = match prefetched_text {
940        Some(t) => t,
941        None => {
942            let entity: common::entities::Block = _block_dto.clone().into();
943            plain_owned = common::database::rope_helpers::block_content_via_store(
944                &entity,
945                inner.ctx.db_context.get_store(),
946            );
947            &plain_owned
948        }
949    };
950
951    let (runs, images, notes) = {
952        let store = inner.ctx.db_context.get_store();
953        let runs: Vec<FormatRun> = store
954            .format_runs
955            .read()
956            .get(&block_id)
957            .cloned()
958            .unwrap_or_default();
959        let images: Vec<ImageAnchor> = store
960            .block_images
961            .read()
962            .get(&block_id)
963            .cloned()
964            .unwrap_or_default();
965        let notes = store
966            .block_footnote_refs
967            .read()
968            .get(&block_id)
969            .cloned()
970            .unwrap_or_default();
971        (runs, images, notes)
972    };
973
974    // One shared weave of runs + anchors (see
975    // `common::format_runs::merge_runs_and_anchors`). This used to be a second,
976    // hand-written copy of that algorithm, and the two disagreed on an image
977    // sitting exactly on a run boundary.
978    let anchors = frontend::common::format_runs::block_anchors(&images, &notes);
979    let pieces = frontend::common::format_runs::merge_runs_and_anchors(plain, &runs, &anchors);
980
981    let mut fragments = Vec::with_capacity(pieces.len());
982    let mut char_offset: usize = 0;
983
984    for piece in pieces {
985        match piece {
986            frontend::common::format_runs::InlinePiece::Text { start, end, format } => {
987                let text = &plain[start as usize..end as usize];
988                let length = text.chars().count();
989                let word_starts = compute_word_starts(text);
990                fragments.push(FragmentContent::Text {
991                    text: text.to_string(),
992                    format: format.map(TextFormat::from).unwrap_or_default(),
993                    offset: char_offset,
994                    length,
995                    element_id: synth_element_id(block_id, start),
996                    word_starts,
997                });
998                char_offset += length;
999            }
1000            frontend::common::format_runs::InlinePiece::FootnoteRef(note) => {
1001                fragments.push(FragmentContent::FootnoteReference {
1002                    label: note.label.clone(),
1003                    // What the host says this note prints — a number, usually.
1004                    //
1005                    // It has to come from outside: which note this is depends on
1006                    // how many references precede it in the *document*, and a
1007                    // host that owns note storage (Skribisto keeps bodies in its
1008                    // own store) knows more still — that this text is chapter
1009                    // five of a book, and where its numbering starts.
1010                    //
1011                    // Falls back, in order: the host's override map; then this
1012                    // document's OWN reading-order count (`document_self_
1013                    // footnote_numbers` — the tier `document_io::Footnotes::
1014                    // marker` implements and `set_footnote_markers` documents,
1015                    // "right when the document *is* the whole text"); then,
1016                    // only for a reference that resolves in neither, the raw
1017                    // label — visible and traceable rather than a blank
1018                    // marker, matching `Footnotes::marker`'s own last resort.
1019                    //
1020                    // Both maps are whole-document facts, read once per
1021                    // snapshot (see `SnapshotLookups`), and the reading-order
1022                    // count only when a reference has no marker: the common
1023                    // case (a host that manages its own numbering, like
1024                    // Skribisto, always pushes a full marker map before any
1025                    // document paints) never runs that scan.
1026                    marker: lookups
1027                        .footnote_markers(inner)
1028                        .get(&note.label)
1029                        .cloned()
1030                        .unwrap_or_else(|| {
1031                            lookups
1032                                .self_footnote_numbers(inner)
1033                                .get(&note.label)
1034                                .map(|n| n.to_string())
1035                                .unwrap_or_else(|| note.label.clone())
1036                        }),
1037                    format: TextFormat::from(&note.format),
1038                    offset: char_offset,
1039                    element_id: synth_element_id(block_id, note.byte_offset),
1040                });
1041                // One logical character, like an image — the U+FFFC in the rope
1042                // holds its position.
1043                char_offset += 1;
1044            }
1045            frontend::common::format_runs::InlinePiece::Image(img) => {
1046                fragments.push(FragmentContent::Image {
1047                    name: img.name.clone(),
1048                    alt: img.alt.clone(),
1049                    width: img.width as u32,
1050                    height: img.height as u32,
1051                    quality: img.quality as u32,
1052                    format: TextFormat::from(&img.format),
1053                    offset: char_offset,
1054                    element_id: synth_element_id(block_id, img.byte_offset),
1055                });
1056                // An image contributes exactly one logical character and zero
1057                // bytes; the U+FFFC sentinel in the rope holds its position.
1058                char_offset += 1;
1059            }
1060        }
1061    }
1062
1063    fragments
1064}
1065
1066/// Compute character-index-based word starts for a text slice,
1067/// following Unicode Standard Annex #29. Returned indices are
1068/// positions within `text.chars()`, NOT byte offsets — matches
1069/// AccessKit's `word_starts` contract where each entry is an index
1070/// into `character_lengths`.
1071fn compute_word_starts(text: &str) -> Vec<u8> {
1072    use unicode_segmentation::UnicodeSegmentation;
1073    let mut result = Vec::new();
1074    // `unicode_word_indices` yields (byte_offset, word_slice) for each
1075    // Unicode-word match. Convert each byte offset to a character
1076    // index by counting `char_indices` up to that offset.
1077    let mut byte_to_char: Vec<(usize, usize)> = Vec::new();
1078    for (ci, (bi, _)) in text.char_indices().enumerate() {
1079        byte_to_char.push((bi, ci));
1080    }
1081    for (byte_off, _word) in text.unicode_word_indices() {
1082        let char_idx = byte_to_char
1083            .iter()
1084            .find(|(bi, _)| *bi == byte_off)
1085            .map(|(_, ci)| *ci)
1086            .unwrap_or(0);
1087        // Saturating cast — text runs longer than 255 chars get their
1088        // later word starts dropped. That's the AccessKit contract:
1089        // `word_starts` is Box<[u8]>. Runs longer than ~255 chars are
1090        // unusual for a single format run, and the first 255 word
1091        // starts cover the viewport almost always. Documented in the
1092        // plan.
1093        if let Ok(idx) = u8::try_from(char_idx) {
1094            result.push(idx);
1095        } else {
1096            break;
1097        }
1098    }
1099    result
1100}
1101
1102/// Compute 0-based index of a block within its list.
1103fn compute_list_item_index(inner: &TextDocumentInner, list_id: EntityId, block_id: u64) -> usize {
1104    whole_document_read();
1105    let mut all_blocks = block_commands::get_all_block(&inner.ctx).unwrap_or_default();
1106    let store = inner.ctx.db_context.get_store();
1107    crate::inner::refresh_block_positions(&mut all_blocks, store);
1108    let mut list_blocks: Vec<_> = all_blocks
1109        .iter()
1110        .filter(|b| b.list == Some(list_id))
1111        .collect();
1112    list_blocks.sort_by_key(|b| b.document_position);
1113    list_blocks
1114        .iter()
1115        .position(|b| b.id == block_id)
1116        .unwrap_or(0)
1117}
1118
1119/// Format a list marker for the given item index.
1120pub(crate) fn format_list_marker(
1121    list_dto: &frontend::list::dtos::ListDto,
1122    item_index: usize,
1123) -> String {
1124    let number = item_index + 1; // 1-based for display
1125    let marker_body = match list_dto.style {
1126        ListStyle::Disc => "\u{2022}".to_string(),   // •
1127        ListStyle::Circle => "\u{25E6}".to_string(), // ◦
1128        ListStyle::Square => "\u{25AA}".to_string(), // ▪
1129        ListStyle::Decimal => format!("{number}"),
1130        ListStyle::LowerAlpha => {
1131            if number <= 26 {
1132                ((b'a' + (number as u8 - 1)) as char).to_string()
1133            } else {
1134                format!("{number}")
1135            }
1136        }
1137        ListStyle::UpperAlpha => {
1138            if number <= 26 {
1139                ((b'A' + (number as u8 - 1)) as char).to_string()
1140            } else {
1141                format!("{number}")
1142            }
1143        }
1144        ListStyle::LowerRoman => to_roman_lower(number),
1145        ListStyle::UpperRoman => to_roman_upper(number),
1146    };
1147    format!("{}{marker_body}{}", list_dto.prefix, list_dto.suffix)
1148}
1149
1150fn to_roman_upper(mut n: usize) -> String {
1151    const VALUES: &[(usize, &str)] = &[
1152        (1000, "M"),
1153        (900, "CM"),
1154        (500, "D"),
1155        (400, "CD"),
1156        (100, "C"),
1157        (90, "XC"),
1158        (50, "L"),
1159        (40, "XL"),
1160        (10, "X"),
1161        (9, "IX"),
1162        (5, "V"),
1163        (4, "IV"),
1164        (1, "I"),
1165    ];
1166    let mut result = String::new();
1167    for &(val, sym) in VALUES {
1168        while n >= val {
1169            result.push_str(sym);
1170            n -= val;
1171        }
1172    }
1173    result
1174}
1175
1176fn to_roman_lower(n: usize) -> String {
1177    to_roman_upper(n).to_lowercase()
1178}
1179
1180/// Build a ListInfo for a block. Called while lock is held.
1181fn build_list_info(
1182    inner: &TextDocumentInner,
1183    block_dto: &frontend::block::dtos::BlockDto,
1184    lookups: &SnapshotLookups,
1185) -> Option<ListInfo> {
1186    let list_id = block_dto.list?;
1187    let list_dto = list_commands::get_list(&inner.ctx, &{ list_id })
1188        .ok()
1189        .flatten()?;
1190
1191    let item_index = lookups.list_item_index(inner, list_id, block_dto.id);
1192    let marker = format_list_marker(&list_dto, item_index);
1193
1194    Some(ListInfo {
1195        list_id: list_id as usize,
1196        style: list_dto.style.clone(),
1197        indent: list_dto.indent as u8,
1198        marker,
1199        item_index,
1200    })
1201}
1202
1203/// Build a BlockSnapshot for a block. Called while lock is held.
1204pub(crate) fn build_block_snapshot(
1205    inner: &TextDocumentInner,
1206    block_id: u64,
1207    hl: crate::highlight::SnapshotHighlights,
1208) -> Option<BlockSnapshot> {
1209    build_block_snapshot_with_position_and_parent(
1210        inner,
1211        block_id,
1212        None,
1213        None,
1214        hl,
1215        &SnapshotLookups::default(),
1216    )
1217}
1218
1219/// Build a BlockSnapshot, optionally overriding the position with a computed value.
1220/// When `computed_position` is Some, it's used instead of `block_dto.document_position`
1221/// (which may be stale if position updates are deferred).
1222///
1223/// `lookups` carries the whole-document facts across the blocks of one snapshot:
1224/// [`SnapshotLookups::default`] for a snapshot of this block alone.
1225pub(crate) fn build_block_snapshot_with_position(
1226    inner: &TextDocumentInner,
1227    block_id: u64,
1228    computed_position: Option<usize>,
1229    hl: crate::highlight::SnapshotHighlights,
1230    lookups: &SnapshotLookups,
1231) -> Option<BlockSnapshot> {
1232    build_block_snapshot_with_position_and_parent(
1233        inner,
1234        block_id,
1235        computed_position,
1236        None,
1237        hl,
1238        lookups,
1239    )
1240}
1241
1242/// Build a BlockSnapshot with an optional `parent_frame_hint`. When the
1243/// caller already knows which frame owns the block (e.g. snapshot_flow's
1244/// per-frame walk), passing it here skips the per-block `find_parent_frame`
1245/// call — which would otherwise fetch every Frame in the store on every
1246/// invocation. That walk was a major contributor to per-keystroke
1247/// editor lag.
1248///
1249/// `lookups` carries the whole-document facts (list numbers, table cells,
1250/// footnote markers, the default language) across the blocks of one
1251/// snapshot, so each is worked out once rather than once per block.
1252pub(crate) fn build_block_snapshot_with_position_and_parent(
1253    inner: &TextDocumentInner,
1254    block_id: u64,
1255    computed_position: Option<usize>,
1256    parent_frame_hint: Option<EntityId>,
1257    hl: crate::highlight::SnapshotHighlights,
1258    lookups: &SnapshotLookups,
1259) -> Option<BlockSnapshot> {
1260    let mut block_dto = block_commands::get_block(&inner.ctx, &block_id)
1261        .ok()
1262        .flatten()?;
1263    let store_for_pos = inner.ctx.db_context.get_store();
1264    crate::inner::refresh_block_position(&mut block_dto, store_for_pos);
1265
1266    let mut block_format = BlockFormat::from(&block_dto);
1267    // Inherit the document-wide default language when the block sets none,
1268    // so hyphenation has a language for every block. The bridge still
1269    // falls back to English if this is also unset.
1270    if block_format.language.is_none() {
1271        block_format.language = lookups.default_language(inner);
1272    }
1273    let list_info = build_list_info(inner, &block_dto, lookups);
1274
1275    let parent_frame_id = parent_frame_hint
1276        .or_else(|| lookups.parent_frame(inner, block_id))
1277        .map(|id| id as usize);
1278    let table_cell = lookups.table_cell_context(inner, block_id);
1279
1280    // The flow-snapshot position MUST agree with the space the editing path
1281    // resolves cursor positions against. When the rope mirrors every block
1282    // (now true even with tables, since cell content is mirrored inline), the
1283    // rope is the single source of truth: its char order — including the
1284    // 1-char table-anchor sentinel — is what `find_block_at_char_position`
1285    // uses. So derive `position` from the rope-refreshed `document_position`
1286    // (set above) rather than the caller's running counter, which omits the
1287    // sentinel and would drift past every table. Only when the rope is NOT
1288    // authoritative (programmatically-inserted sub-frames whose blocks aren't
1289    // mirrored) do we fall back to the caller's computed running position.
1290    let position = if common::database::rope_helpers::rope_positions_match_flow(store_for_pos) {
1291        to_usize(block_dto.document_position)
1292    } else {
1293        computed_position.unwrap_or_else(|| to_usize(block_dto.document_position))
1294    };
1295
1296    // Materialize the block text once and pass it to build_fragments
1297    // and into the snapshot's `text` field — saves one redundant rope
1298    // slice + String allocation per block per snapshot_flow call.
1299    let entity: common::entities::Block = block_dto.clone().into();
1300    let store = inner.ctx.db_context.get_store();
1301    let text = common::database::rope_helpers::block_content_via_store(&entity, store);
1302    let length = to_usize(common::database::rope_helpers::block_char_length(
1303        &entity, store,
1304    ));
1305    let fragments = build_fragments_with_text(inner, block_id, Some(&text), hl, lookups);
1306
1307    // Paint-only sessions: emit the merged spans as a separate overlay (fragments stayed base
1308    // above). Metric / none: empty (highlights merged into fragments, or none). A "without
1309    // highlights" (empty-mask) snapshot resolves to `kind == None`, so this is empty
1310    // regardless of the live sessions.
1311    let paint_highlights =
1312        if hl.kind == crate::highlight::HighlighterKind::PaintOnly && !hl.suppress_paint {
1313            let spans = crate::highlight::merged_spans_for_block(inner, block_id as usize, hl.mask);
1314            crate::highlight::extract_paint_spans(&spans, length)
1315        } else {
1316            Vec::new()
1317        };
1318
1319    Some(BlockSnapshot {
1320        block_id: block_id as usize,
1321        position,
1322        length,
1323        text,
1324        fragments,
1325        block_format,
1326        list_info,
1327        parent_frame_id,
1328        table_cell,
1329        paint_highlights,
1330    })
1331}
1332
1333/// Build BlockSnapshots for all blocks in a frame, sorted by document_position.
1334/// `lookups` is shared with the rest of the snapshot this frame belongs to, if any.
1335pub(crate) fn build_blocks_snapshot_for_frame(
1336    inner: &TextDocumentInner,
1337    frame_id: u64,
1338    hl: crate::highlight::SnapshotHighlights,
1339    lookups: &SnapshotLookups,
1340) -> Vec<BlockSnapshot> {
1341    let frame_dto = match frame_commands::get_frame(&inner.ctx, &(frame_id as EntityId))
1342        .ok()
1343        .flatten()
1344    {
1345        Some(f) => f,
1346        None => return Vec::new(),
1347    };
1348
1349    let mut block_dtos: Vec<_> = frame_dto
1350        .blocks
1351        .iter()
1352        .filter_map(|&id| {
1353            block_commands::get_block(&inner.ctx, &{ id })
1354                .ok()
1355                .flatten()
1356        })
1357        .collect();
1358    let store = inner.ctx.db_context.get_store();
1359    crate::inner::refresh_block_positions(&mut block_dtos, store);
1360    block_dtos.sort_by_key(|b| b.document_position);
1361
1362    block_dtos
1363        .iter()
1364        .filter_map(|b| {
1365            build_block_snapshot_with_position_and_parent(inner, b.id, None, None, hl, lookups)
1366        })
1367        .collect()
1368}
1369
1370/// Build BlockSnapshots with computed positions starting from `start_pos`.
1371///
1372/// Returns `(snapshots, running_pos_after_last_block)`.
1373/// Positions are computed sequentially from `start_pos` using each block's
1374/// `text_length`, matching the logic in `find_block_at_position_sequential`.
1375/// `lookups` is shared with the rest of the snapshot this frame belongs to.
1376pub(crate) fn build_blocks_snapshot_for_frame_with_positions(
1377    inner: &TextDocumentInner,
1378    frame_id: u64,
1379    start_pos: usize,
1380    hl: crate::highlight::SnapshotHighlights,
1381    lookups: &SnapshotLookups,
1382) -> (Vec<BlockSnapshot>, usize) {
1383    let frame_dto = match frame_commands::get_frame(&inner.ctx, &(frame_id as EntityId))
1384        .ok()
1385        .flatten()
1386    {
1387        Some(f) => f,
1388        None => return (Vec::new(), start_pos),
1389    };
1390
1391    let mut block_dtos: Vec<_> = frame_dto
1392        .blocks
1393        .iter()
1394        .filter_map(|&id| {
1395            block_commands::get_block(&inner.ctx, &{ id })
1396                .ok()
1397                .flatten()
1398        })
1399        .collect();
1400    let store = inner.ctx.db_context.get_store();
1401    crate::inner::refresh_block_positions(&mut block_dtos, store);
1402    block_dtos.sort_by_key(|b| b.document_position);
1403
1404    let mut running_pos = start_pos;
1405    let mut snapshots = Vec::with_capacity(block_dtos.len());
1406    for b in &block_dtos {
1407        if let Some(snap) =
1408            build_block_snapshot_with_position(inner, b.id, Some(running_pos), hl, lookups)
1409        {
1410            running_pos += snap.length + 1; // +1 for block separator
1411            snapshots.push(snap);
1412        }
1413    }
1414    (snapshots, running_pos)
1415}
1416
1417#[cfg(test)]
1418mod tests {
1419    use crate::TextDocument;
1420    use crate::flow::FlowElementSnapshot;
1421    use std::cell::Cell;
1422
1423    thread_local! {
1424        /// Whole-document reads [`super::whole_document_read`] marked on this thread.
1425        pub(super) static WHOLE_DOCUMENT_READS: Cell<usize> = const { Cell::new(0) };
1426    }
1427
1428    /// A text of `paragraphs` paragraphs with every whole-document fact a block snapshot
1429    /// reads: footnotes, lists, tables and quotations spread through it.
1430    fn novel(paragraphs: usize) -> String {
1431        let mut text = String::new();
1432        for i in 0..paragraphs {
1433            if i % 7 == 3 {
1434                text.push_str(&format!("Paragraph {i}, with a note[^n{i}].\n\n"));
1435                text.push_str(&format!("[^n{i}]: Note {i}.\n\n"));
1436            } else if i % 17 == 5 {
1437                text.push_str(&format!("> Quoted paragraph {i}.\n\n"));
1438            } else {
1439                text.push_str(&format!("Paragraph {i} of the text.\n\n"));
1440            }
1441            if i % 11 == 4 {
1442                text.push_str(&format!("- item {i}\n- item {i}, second\n\n"));
1443            }
1444            if i % 13 == 6 {
1445                text.push_str(&format!("| a{i} | b |\n| c | d |\n\n"));
1446            }
1447        }
1448        text
1449    }
1450
1451    /// Every block snapshot among `elements`, table cells and sub-frames included.
1452    fn all_blocks(elements: &[FlowElementSnapshot], out: &mut Vec<crate::flow::BlockSnapshot>) {
1453        for element in elements {
1454            match element {
1455                FlowElementSnapshot::Block(block) => out.push(block.clone()),
1456                FlowElementSnapshot::Table(table) => {
1457                    for cell in &table.cells {
1458                        out.extend(cell.blocks.iter().cloned());
1459                    }
1460                }
1461                FlowElementSnapshot::Frame(frame) => all_blocks(&frame.elements, out),
1462            }
1463        }
1464    }
1465
1466    /// A flow snapshot works each block's whole-document facts out from indexes it shares
1467    /// across its blocks; a snapshot of one block works them out by walking the document.
1468    /// The two must give every block the same snapshot: list numbers across several lists,
1469    /// cells of tables in and out of quotations, cells holding several paragraphs and a
1470    /// list, notes numbered by the document, by the host, or partly by each.
1471    #[test]
1472    fn a_flow_snapshot_agrees_with_a_snapshot_of_each_block_alone() {
1473        let mixed = "# Title\n\nA note[^a] and another[^b].\n\n- one\n- two\n- three\n\n\
1474                     Between lists.\n\n1. first\n2. second\n\n> Quoted, with a note[^c].\n>\n\
1475                     > - quoted item\n> - quoted item two\n>\n> > nested quote\n\n\
1476                     | h1 | h2 |\n|----|----|\n| a | b[^a] |\n| c | d |\n\n\
1477                     - again one\n- again two\n\n> | q1 | q2 |\n> | q3 | q4 |\n\n\
1478                     Last paragraph[^d].\n\n[^a]: Note a, citing [^b].\n\n[^b]: Note b.\n\n\
1479                     [^c]: Note c.\n\n[^d]: Note d.\n";
1480        let html = "<p>Before.</p><table><tr><td><p>c1 p1</p><p>c1 p2</p></td><td><ul>\
1481                    <li>in cell</li><li>in cell 2</li></ul></td></tr><tr><td>plain</td><td>\
1482                    <p>x</p><p>y</p></td></tr></table><ol><li>o1</li><li>o2</li></ol>\
1483                    <blockquote><p>q</p><ul><li>qi</li></ul></blockquote><p>After.</p>";
1484
1485        let from_djot = |text: &str| {
1486            let doc = TextDocument::new();
1487            doc.set_djot_sync(text).unwrap();
1488            doc
1489        };
1490        let numbered_by_the_document = from_djot(mixed);
1491        let partly_by_the_host = from_djot(mixed);
1492        partly_by_the_host.set_footnote_markers(
1493            [("a", "i"), ("c", "iii")]
1494                .into_iter()
1495                .map(|(label, marker)| (label.to_string(), marker.to_string()))
1496                .collect(),
1497        );
1498        partly_by_the_host.set_default_language("fr").unwrap();
1499        let with_cells_of_paragraphs = TextDocument::new();
1500        with_cells_of_paragraphs
1501            .set_html(html)
1502            .unwrap()
1503            .wait()
1504            .unwrap();
1505        let long = from_djot(&novel(120));
1506
1507        for (label, doc) in [
1508            ("notes numbered by the document", &numbered_by_the_document),
1509            ("notes partly numbered by the host", &partly_by_the_host),
1510            ("cells holding paragraphs", &with_cells_of_paragraphs),
1511            ("a long text", &long),
1512        ] {
1513            let mut blocks = Vec::new();
1514            all_blocks(&doc.snapshot_flow().elements, &mut blocks);
1515            assert!(
1516                blocks.iter().any(|b| b.table_cell.is_some())
1517                    && blocks.iter().any(|b| b.list_info.is_some()),
1518                "{label}: the text holds table cells and list items"
1519            );
1520            for from_flow in blocks {
1521                let alone = doc
1522                    .block_by_id(from_flow.block_id)
1523                    .expect("a block of the flow exists")
1524                    .snapshot();
1525                assert_eq!(
1526                    alone, from_flow,
1527                    "{label}: block {} alone and in the flow",
1528                    from_flow.block_id
1529                );
1530            }
1531        }
1532    }
1533
1534    /// Whole-document reads one flow snapshot of `doc` makes, and the snapshot.
1535    fn reads_for_one_snapshot(doc: &TextDocument) -> (usize, crate::flow::FlowSnapshot) {
1536        WHOLE_DOCUMENT_READS.with(|reads| reads.set(0));
1537        let flow = doc.snapshot_flow();
1538        (WHOLE_DOCUMENT_READS.with(Cell::get), flow)
1539    }
1540
1541    /// A block's list number, its table cell, its footnote numbers and its default language
1542    /// are whole-document facts. A flow snapshot used to read each of them again for every
1543    /// block that needed it, so opening a long text holding lists, tables or footnotes cost
1544    /// time in proportion to the square of its length. It must read each one a fixed number
1545    /// of times, however long the text.
1546    #[test]
1547    fn a_flow_snapshot_reads_each_whole_document_fact_a_fixed_number_of_times() {
1548        let mut counts = Vec::new();
1549        for paragraphs in [60, 480] {
1550            let doc = TextDocument::new();
1551            doc.set_djot_sync(&novel(paragraphs)).unwrap();
1552            let (numbered_by_the_document, flow) = reads_for_one_snapshot(&doc);
1553
1554            let blocks: Vec<_> = flow
1555                .elements
1556                .iter()
1557                .filter_map(|element| match element {
1558                    FlowElementSnapshot::Block(block) => Some(block),
1559                    _ => None,
1560                })
1561                .collect();
1562            assert!(
1563                blocks.iter().filter(|b| b.list_info.is_some()).count() > 4,
1564                "the text holds list items"
1565            );
1566            assert!(
1567                flow.elements
1568                    .iter()
1569                    .filter(|e| matches!(e, FlowElementSnapshot::Table(_)))
1570                    .count()
1571                    > 2,
1572                "the text holds tables"
1573            );
1574            assert!(
1575                flow.elements
1576                    .iter()
1577                    .any(|e| matches!(e, FlowElementSnapshot::Frame(_))),
1578                "the text holds quotations"
1579            );
1580
1581            // The host numbering the notes itself, as Skribisto does.
1582            let markers = (0..paragraphs)
1583                .filter(|i| i % 7 == 3)
1584                .enumerate()
1585                .map(|(k, i)| (format!("n{i}"), (k + 1).to_string()))
1586                .collect();
1587            doc.set_footnote_markers(markers);
1588            let (numbered_by_the_host, _) = reads_for_one_snapshot(&doc);
1589
1590            counts.push((paragraphs, numbered_by_the_document, numbered_by_the_host));
1591        }
1592        let (small, small_self, small_host) = counts[0];
1593        let (large, large_self, large_host) = counts[1];
1594        println!(
1595            "whole-document reads per flow snapshot: {small_self} and {small_host} (notes \
1596             numbered by the document, by the host) at {small} paragraphs, {large_self} and \
1597             {large_host} at {large}"
1598        );
1599        assert_eq!(
1600            large_self, small_self,
1601            "a flow snapshot of {large} paragraphs read whole-document facts {large_self} \
1602             times against {small_self} for {small}: one of them is being read again for \
1603             each block that needs it"
1604        );
1605        assert_eq!(
1606            large_host, small_host,
1607            "with host footnote markers, a flow snapshot of {large} paragraphs read \
1608             whole-document facts {large_host} times against {small_host} for {small}"
1609        );
1610        // Each fact is read at most twice (the one-block walk that answers the first block,
1611        // then the index for the rest), plus the walks the direct table-cell search itself
1612        // makes the first time.
1613        assert!(
1614            small_self <= 12 && small_host <= 12,
1615            "{small_self} and {small_host} whole-document reads for one snapshot"
1616        );
1617    }
1618}