Skip to main content

sui_widgets/
rich_document.rs

1use std::{
2    cell::RefCell,
3    collections::{HashMap, HashSet},
4    fmt,
5    ops::Range,
6    rc::Rc,
7    sync::Arc,
8};
9
10use pulldown_cmark::{
11    CodeBlockKind, Event as MarkdownEvent, HeadingLevel, Options, Parser, Tag, TagEnd,
12};
13use sui_reactive::{Observable, Observer, Signal, SourceId, Subscription};
14
15mod view;
16
17pub use view::{
18    RichDocumentRenderContext, RichDocumentRendererRegistry, RichDocumentView,
19    RichDocumentViewState,
20};
21
22/// Stable identity for a block in a [`RichDocumentModel`].
23#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
24pub struct RichBlockId(u64);
25
26impl RichBlockId {
27    pub const fn new(value: u64) -> Self {
28        Self(value)
29    }
30
31    pub const fn get(self) -> u64 {
32        self.0
33    }
34}
35
36impl fmt::Display for RichBlockId {
37    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
38        self.0.fmt(formatter)
39    }
40}
41
42#[derive(Clone, Debug, Default, PartialEq, Eq)]
43pub struct RichInlineStyle {
44    pub strong: bool,
45    pub emphasis: bool,
46    pub strikethrough: bool,
47}
48
49#[derive(Clone, Debug, PartialEq, Eq)]
50pub struct RichLink {
51    pub destination: String,
52    pub title: Option<String>,
53}
54
55impl RichLink {
56    pub fn new(destination: impl Into<String>) -> Self {
57        Self {
58            destination: destination.into(),
59            title: None,
60        }
61    }
62
63    pub fn title(mut self, title: impl Into<String>) -> Self {
64        self.title = Some(title.into());
65        self
66    }
67}
68
69#[derive(Clone, Debug, PartialEq, Eq)]
70pub struct RichInlineImage {
71    pub source: String,
72    pub alt: String,
73    pub title: Option<String>,
74}
75
76impl RichInlineImage {
77    pub fn new(source: impl Into<String>, alt: impl Into<String>) -> Self {
78        Self {
79            source: source.into(),
80            alt: alt.into(),
81            title: None,
82        }
83    }
84
85    pub fn title(mut self, title: impl Into<String>) -> Self {
86        self.title = Some(title.into());
87        self
88    }
89}
90
91#[derive(Clone, Debug, PartialEq, Eq)]
92pub enum RichInlineKind {
93    Text,
94    Code,
95    Link(RichLink),
96    Image(RichInlineImage),
97}
98
99#[derive(Clone, Debug, PartialEq, Eq)]
100pub struct RichDocumentSpan {
101    pub text: String,
102    pub source_range: Range<usize>,
103    pub style: RichInlineStyle,
104    pub kind: RichInlineKind,
105}
106
107impl RichDocumentSpan {
108    pub fn text(text: impl Into<String>, source_range: Range<usize>) -> Self {
109        Self {
110            text: text.into(),
111            source_range,
112            style: RichInlineStyle::default(),
113            kind: RichInlineKind::Text,
114        }
115    }
116}
117
118#[derive(Clone, Debug, PartialEq, Eq)]
119pub struct RichListItem {
120    pub source_range: Range<usize>,
121    pub spans: Vec<RichDocumentSpan>,
122    pub checked: Option<bool>,
123}
124
125impl RichListItem {
126    pub fn plain_text(&self) -> String {
127        spans_plain_text(&self.spans)
128    }
129}
130
131#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
132pub enum RichDocumentStatus {
133    #[default]
134    Neutral,
135    Pending,
136    Running,
137    Success,
138    Warning,
139    Error,
140}
141
142#[derive(Clone, Debug, PartialEq, Eq)]
143pub struct RichAttachment {
144    pub name: String,
145    pub media_type: Option<String>,
146    pub source: Option<String>,
147    pub size_bytes: Option<u64>,
148    pub description: Option<String>,
149}
150
151impl RichAttachment {
152    pub fn new(name: impl Into<String>) -> Self {
153        Self {
154            name: name.into(),
155            media_type: None,
156            source: None,
157            size_bytes: None,
158            description: None,
159        }
160    }
161}
162
163/// Application-defined structured block rendered through a registry entry.
164///
165/// `renderer` is an architecture-neutral dispatch key such as `tool-call`,
166/// `diff`, or `operation-log`. The fallback renderer remains usable when an
167/// application does not register a specialized widget.
168#[derive(Clone, Debug, PartialEq, Eq)]
169pub struct RichExtensionBlock {
170    pub renderer: String,
171    pub title: String,
172    pub summary: Option<String>,
173    pub body: String,
174    pub status: RichDocumentStatus,
175    pub initially_expanded: bool,
176    pub metadata: Vec<(String, String)>,
177}
178
179impl RichExtensionBlock {
180    pub fn new(renderer: impl Into<String>, title: impl Into<String>) -> Self {
181        Self {
182            renderer: renderer.into(),
183            title: title.into(),
184            summary: None,
185            body: String::new(),
186            status: RichDocumentStatus::Neutral,
187            initially_expanded: false,
188            metadata: Vec::new(),
189        }
190    }
191}
192
193#[derive(Clone, Debug, PartialEq, Eq)]
194pub enum RichDocumentBlockKind {
195    Paragraph {
196        spans: Vec<RichDocumentSpan>,
197    },
198    Heading {
199        level: u8,
200        spans: Vec<RichDocumentSpan>,
201    },
202    BlockQuote {
203        label: Option<String>,
204        spans: Vec<RichDocumentSpan>,
205    },
206    List {
207        start: Option<u64>,
208        items: Vec<RichListItem>,
209    },
210    CodeBlock {
211        language: Option<String>,
212        code: String,
213    },
214    ThematicBreak,
215    Attachment(RichAttachment),
216    Extension(RichExtensionBlock),
217}
218
219impl RichDocumentBlockKind {
220    pub fn renderer_key(&self) -> String {
221        match self {
222            Self::Paragraph { .. } => "paragraph".to_string(),
223            Self::Heading { .. } => "heading".to_string(),
224            Self::BlockQuote { .. } => "block-quote".to_string(),
225            Self::List { .. } => "list".to_string(),
226            Self::CodeBlock { .. } => "code-block".to_string(),
227            Self::ThematicBreak => "thematic-break".to_string(),
228            Self::Attachment(_) => "attachment".to_string(),
229            Self::Extension(extension) => format!("extension:{}", extension.renderer),
230        }
231    }
232
233    pub fn plain_text(&self) -> String {
234        match self {
235            Self::Paragraph { spans }
236            | Self::Heading { spans, .. }
237            | Self::BlockQuote { spans, .. } => spans_plain_text(spans),
238            Self::List { start, items } => {
239                let mut next = start.unwrap_or(1);
240                items
241                    .iter()
242                    .map(|item| {
243                        let marker = if start.is_some() {
244                            let marker = format!("{next}. ");
245                            next = next.saturating_add(1);
246                            marker
247                        } else {
248                            "- ".to_string()
249                        };
250                        format!("{marker}{}", item.plain_text())
251                    })
252                    .collect::<Vec<_>>()
253                    .join("\n")
254            }
255            Self::CodeBlock { code, .. } => code.clone(),
256            Self::ThematicBreak => String::new(),
257            Self::Attachment(attachment) => attachment.name.clone(),
258            Self::Extension(extension) => {
259                if extension.body.is_empty() {
260                    extension.title.clone()
261                } else {
262                    format!("{}\n{}", extension.title, extension.body)
263                }
264            }
265        }
266    }
267}
268
269#[derive(Clone, Debug, PartialEq, Eq)]
270pub struct RichDocumentBlock {
271    pub id: RichBlockId,
272    pub source_range: Range<usize>,
273    pub kind: RichDocumentBlockKind,
274}
275
276impl RichDocumentBlock {
277    pub fn plain_text(&self) -> String {
278        self.kind.plain_text()
279    }
280
281    pub fn renderer_key(&self) -> String {
282        self.kind.renderer_key()
283    }
284}
285
286#[derive(Clone, Debug, Default, PartialEq, Eq)]
287pub struct RichDocumentUpdate {
288    pub revision: u64,
289    pub reparsed_source: Range<usize>,
290    pub reused_prefix_blocks: usize,
291    pub changed_block_ids: Vec<RichBlockId>,
292    pub append_only: bool,
293}
294
295#[derive(Clone, Debug, Default, PartialEq, Eq)]
296pub struct RichDocumentSnapshot {
297    pub revision: u64,
298    pub markdown: String,
299    pub blocks: Vec<RichDocumentBlock>,
300    pub last_update: RichDocumentUpdate,
301}
302
303#[derive(Clone)]
304pub struct RichDocumentModel {
305    inner: Rc<RefCell<RichDocumentModelInner>>,
306    revision: Signal<u64>,
307    structure_revision: Signal<u64>,
308}
309
310struct RichDocumentModelInner {
311    markdown: String,
312    segments: Vec<RichDocumentSegment>,
313    block_signals: HashMap<RichBlockId, Signal<RichDocumentBlock>>,
314    ids_by_origin: HashMap<(usize, &'static str), RichBlockId>,
315    next_id: u64,
316    revision: u64,
317    last_update: RichDocumentUpdate,
318}
319
320enum RichDocumentSegment {
321    Markdown {
322        source_range: Range<usize>,
323        blocks: Vec<RichDocumentBlock>,
324    },
325    Structured(RichDocumentBlock),
326}
327
328impl RichDocumentSegment {
329    fn block_count(&self) -> usize {
330        match self {
331            Self::Markdown { blocks, .. } => blocks.len(),
332            Self::Structured(_) => 1,
333        }
334    }
335}
336
337impl RichDocumentModel {
338    pub fn new() -> Self {
339        Self {
340            inner: Rc::new(RefCell::new(RichDocumentModelInner {
341                markdown: String::new(),
342                segments: Vec::new(),
343                block_signals: HashMap::new(),
344                ids_by_origin: HashMap::new(),
345                next_id: 1,
346                revision: 0,
347                last_update: RichDocumentUpdate::default(),
348            })),
349            revision: Signal::named("RichDocumentModel", 0),
350            structure_revision: Signal::named("RichDocumentModel::structure", 0),
351        }
352    }
353
354    pub fn from_markdown(markdown: impl Into<String>) -> Self {
355        let model = Self::new();
356        model.set_markdown(markdown);
357        model
358    }
359
360    pub fn revision(&self) -> u64 {
361        self.inner.borrow().revision
362    }
363
364    pub fn markdown(&self) -> String {
365        self.inner.borrow().markdown.clone()
366    }
367
368    pub fn blocks(&self) -> Vec<RichDocumentBlock> {
369        flatten_blocks(&self.inner.borrow())
370    }
371
372    pub fn snapshot(&self) -> RichDocumentSnapshot {
373        let inner = self.inner.borrow();
374        RichDocumentSnapshot {
375            revision: inner.revision,
376            markdown: inner.markdown.clone(),
377            blocks: flatten_blocks(&inner),
378            last_update: inner.last_update.clone(),
379        }
380    }
381
382    pub fn last_update(&self) -> RichDocumentUpdate {
383        self.inner.borrow().last_update.clone()
384    }
385
386    pub(crate) fn structure_observable(&self) -> &Signal<u64> {
387        &self.structure_revision
388    }
389
390    pub(crate) fn block_signal(&self, id: RichBlockId) -> Option<Signal<RichDocumentBlock>> {
391        self.inner.borrow().block_signals.get(&id).cloned()
392    }
393
394    pub fn set_markdown(&self, markdown: impl Into<String>) -> bool {
395        let markdown = markdown.into();
396        let (changed, structure_changed) = {
397            let mut inner = self.inner.borrow_mut();
398            if inner.markdown == markdown {
399                return false;
400            }
401            let old = flatten_blocks(&inner);
402            inner.markdown = markdown;
403            let source_len = inner.markdown.len();
404            let parsed = parse_markdown_blocks(&inner.markdown, 0);
405            let markdown_blocks = assign_block_ids(&mut inner, parsed);
406            let structured = inner
407                .segments
408                .drain(..)
409                .filter_map(|segment| match segment {
410                    RichDocumentSegment::Structured(mut block) => {
411                        block.source_range = source_len..source_len;
412                        Some(block)
413                    }
414                    RichDocumentSegment::Markdown { .. } => None,
415                })
416                .map(RichDocumentSegment::Structured)
417                .collect::<Vec<_>>();
418            inner.segments = Vec::with_capacity(structured.len() + 1);
419            if source_len > 0 {
420                inner.segments.push(RichDocumentSegment::Markdown {
421                    source_range: 0..source_len,
422                    blocks: markdown_blocks,
423                });
424            }
425            inner.segments.extend(structured);
426            let structure_changed = commit_update(&mut inner, old, 0..source_len, 0, false);
427            (inner.revision, structure_changed)
428        };
429        let _ = self.revision.set(changed);
430        if structure_changed {
431            let _ = self.structure_revision.set(changed);
432        }
433        true
434    }
435
436    /// Append a streaming Markdown fragment and reparse only the mutable tail.
437    ///
438    /// All blocks before the final Markdown block are retained byte-for-byte,
439    /// including their stable IDs and any widget-local state keyed by them.
440    pub fn append_markdown(&self, fragment: &str) -> bool {
441        if fragment.is_empty() {
442            return false;
443        }
444        let (changed, structure_changed) = {
445            let mut inner = self.inner.borrow_mut();
446            let old = flatten_blocks(&inner);
447            let old_source_len = inner.markdown.len();
448            let last_markdown = inner.segments.last().and_then(|segment| match segment {
449                RichDocumentSegment::Markdown {
450                    source_range,
451                    blocks,
452                } => Some((source_range.clone(), blocks.clone())),
453                RichDocumentSegment::Structured(_) => None,
454            });
455            inner.markdown.push_str(fragment);
456            let source_len = inner.markdown.len();
457            let (reparse_start, reused_prefix_blocks) = if let Some((range, blocks)) = last_markdown
458            {
459                let reparse_start = blocks
460                    .last()
461                    .map(|block| block.source_range.start)
462                    .unwrap_or(range.start)
463                    .min(old_source_len);
464                let local_prefix = blocks
465                    .iter()
466                    .take_while(|block| block.source_range.end <= reparse_start)
467                    .count();
468                let segment_prefix = inner.segments[..inner.segments.len().saturating_sub(1)]
469                    .iter()
470                    .map(RichDocumentSegment::block_count)
471                    .sum::<usize>();
472                let parsed = parse_markdown_blocks(&inner.markdown[reparse_start..], reparse_start);
473                let mut next = blocks[..local_prefix].to_vec();
474                next.extend(assign_block_ids(&mut inner, parsed));
475                if let Some(RichDocumentSegment::Markdown {
476                    source_range,
477                    blocks,
478                }) = inner.segments.last_mut()
479                {
480                    source_range.end = source_len;
481                    *blocks = next;
482                }
483                (reparse_start, segment_prefix + local_prefix)
484            } else {
485                let reused = old.len();
486                let parsed = parse_markdown_blocks(fragment, old_source_len);
487                let blocks = assign_block_ids(&mut inner, parsed);
488                inner.segments.push(RichDocumentSegment::Markdown {
489                    source_range: old_source_len..source_len,
490                    blocks,
491                });
492                (old_source_len, reused)
493            };
494            let structure_changed = commit_update(
495                &mut inner,
496                old,
497                reparse_start..source_len,
498                reused_prefix_blocks,
499                true,
500            );
501            (inner.revision, structure_changed)
502        };
503        let _ = self.revision.set(changed);
504        if structure_changed {
505            let _ = self.structure_revision.set(changed);
506        }
507        true
508    }
509
510    pub fn append_attachment(&self, attachment: RichAttachment) -> RichBlockId {
511        self.append_structured(RichDocumentBlockKind::Attachment(attachment))
512    }
513
514    pub fn append_extension(&self, extension: RichExtensionBlock) -> RichBlockId {
515        self.append_structured(RichDocumentBlockKind::Extension(extension))
516    }
517
518    pub fn update_structured(&self, id: RichBlockId, kind: RichDocumentBlockKind) -> bool {
519        if !matches!(
520            kind,
521            RichDocumentBlockKind::Attachment(_) | RichDocumentBlockKind::Extension(_)
522        ) {
523            return false;
524        }
525        let (changed, structure_changed) = {
526            let mut inner = self.inner.borrow_mut();
527            let old = flatten_blocks(&inner);
528            let Some(segment_index) = inner.segments.iter().position(
529                |segment| matches!(segment, RichDocumentSegment::Structured(block) if block.id == id),
530            )
531            else {
532                return false;
533            };
534            let reused_prefix_blocks = inner.segments[..segment_index]
535                .iter()
536                .map(RichDocumentSegment::block_count)
537                .sum();
538            let RichDocumentSegment::Structured(block) = &mut inner.segments[segment_index] else {
539                unreachable!("structured segment index changed")
540            };
541            if block.kind == kind {
542                return false;
543            }
544            block.kind = kind;
545            inner.revision = inner.revision.wrapping_add(1);
546            inner.last_update = RichDocumentUpdate {
547                revision: inner.revision,
548                reparsed_source: inner.markdown.len()..inner.markdown.len(),
549                reused_prefix_blocks,
550                changed_block_ids: vec![id],
551                append_only: false,
552            };
553            let structure_changed = reconcile_block_signals(&mut inner, &old);
554            (inner.revision, structure_changed)
555        };
556        let _ = self.revision.set(changed);
557        if structure_changed {
558            let _ = self.structure_revision.set(changed);
559        }
560        true
561    }
562
563    fn append_structured(&self, kind: RichDocumentBlockKind) -> RichBlockId {
564        let (id, revision, structure_changed) = {
565            let mut inner = self.inner.borrow_mut();
566            let old = flatten_blocks(&inner);
567            let id = RichBlockId::new(inner.next_id);
568            inner.next_id = inner.next_id.wrapping_add(1).max(1);
569            let end = inner.markdown.len();
570            inner
571                .segments
572                .push(RichDocumentSegment::Structured(RichDocumentBlock {
573                    id,
574                    source_range: end..end,
575                    kind,
576                }));
577            inner.revision = inner.revision.wrapping_add(1);
578            inner.last_update = RichDocumentUpdate {
579                revision: inner.revision,
580                reparsed_source: end..end,
581                reused_prefix_blocks: inner
582                    .segments
583                    .iter()
584                    .take(inner.segments.len().saturating_sub(1))
585                    .map(RichDocumentSegment::block_count)
586                    .sum(),
587                changed_block_ids: vec![id],
588                append_only: true,
589            };
590            let structure_changed = reconcile_block_signals(&mut inner, &old);
591            (id, inner.revision, structure_changed)
592        };
593        let _ = self.revision.set(revision);
594        if structure_changed {
595            let _ = self.structure_revision.set(revision);
596        }
597        id
598    }
599}
600
601impl Default for RichDocumentModel {
602    fn default() -> Self {
603        Self::new()
604    }
605}
606
607impl Observable<u64> for RichDocumentModel {
608    fn source_id(&self) -> SourceId {
609        self.revision.source_id()
610    }
611
612    fn source_name(&self) -> Arc<str> {
613        self.revision.source_name()
614    }
615
616    fn get(&self) -> u64 {
617        self.revision.get()
618    }
619
620    fn subscribe(&self, observer: Observer) -> Subscription {
621        self.revision.subscribe(observer)
622    }
623}
624
625fn flatten_blocks(inner: &RichDocumentModelInner) -> Vec<RichDocumentBlock> {
626    let mut blocks = Vec::new();
627    for segment in &inner.segments {
628        match segment {
629            RichDocumentSegment::Markdown {
630                blocks: markdown, ..
631            } => blocks.extend(markdown.iter().cloned()),
632            RichDocumentSegment::Structured(block) => blocks.push(block.clone()),
633        }
634    }
635    blocks
636}
637
638fn assign_block_ids(
639    inner: &mut RichDocumentModelInner,
640    parsed: Vec<ParsedBlock>,
641) -> Vec<RichDocumentBlock> {
642    parsed
643        .into_iter()
644        .map(|parsed| {
645            let origin = (parsed.source_range.start, block_discriminant(&parsed.kind));
646            let id = *inner.ids_by_origin.entry(origin).or_insert_with(|| {
647                let id = RichBlockId::new(inner.next_id);
648                inner.next_id = inner.next_id.wrapping_add(1).max(1);
649                id
650            });
651            RichDocumentBlock {
652                id,
653                source_range: parsed.source_range,
654                kind: parsed.kind,
655            }
656        })
657        .collect()
658}
659
660fn commit_update(
661    inner: &mut RichDocumentModelInner,
662    old: Vec<RichDocumentBlock>,
663    reparsed_source: Range<usize>,
664    reused_prefix_blocks: usize,
665    append_only: bool,
666) -> bool {
667    inner.revision = inner.revision.wrapping_add(1);
668    let old_by_id = old
669        .iter()
670        .cloned()
671        .map(|block| (block.id, block))
672        .collect::<HashMap<_, _>>();
673    let next = flatten_blocks(inner);
674    let next_ids = next.iter().map(|block| block.id).collect::<HashSet<_>>();
675    let mut changed_block_ids = next
676        .iter()
677        .filter(|block| old_by_id.get(&block.id) != Some(block))
678        .map(|block| block.id)
679        .collect::<Vec<_>>();
680    changed_block_ids.extend(
681        old.iter()
682            .filter(|block| !next_ids.contains(&block.id))
683            .map(|block| block.id),
684    );
685    inner.last_update = RichDocumentUpdate {
686        revision: inner.revision,
687        reparsed_source,
688        reused_prefix_blocks,
689        changed_block_ids,
690        append_only,
691    };
692    reconcile_block_signals(inner, &old)
693}
694
695fn reconcile_block_signals(inner: &mut RichDocumentModelInner, old: &[RichDocumentBlock]) -> bool {
696    let next = flatten_blocks(inner);
697    let old_structure = old
698        .iter()
699        .map(|block| (block.id, block.renderer_key()))
700        .collect::<Vec<_>>();
701    let next_structure = next
702        .iter()
703        .map(|block| (block.id, block.renderer_key()))
704        .collect::<Vec<_>>();
705    let live = next.iter().map(|block| block.id).collect::<HashSet<_>>();
706    inner.block_signals.retain(|id, _| live.contains(id));
707    for block in next {
708        if let Some(signal) = inner.block_signals.get(&block.id) {
709            let _ = signal.set(block);
710        } else {
711            inner.block_signals.insert(
712                block.id,
713                Signal::named(format!("RichDocumentBlock({})", block.id), block),
714            );
715        }
716    }
717    old_structure != next_structure
718}
719
720fn block_discriminant(kind: &RichDocumentBlockKind) -> &'static str {
721    match kind {
722        RichDocumentBlockKind::Paragraph { .. } => "paragraph",
723        RichDocumentBlockKind::Heading { .. } => "heading",
724        RichDocumentBlockKind::BlockQuote { .. } => "quote",
725        RichDocumentBlockKind::List { .. } => "list",
726        RichDocumentBlockKind::CodeBlock { .. } => "code",
727        RichDocumentBlockKind::ThematicBreak => "rule",
728        RichDocumentBlockKind::Attachment(_) => "attachment",
729        RichDocumentBlockKind::Extension(_) => "extension",
730    }
731}
732
733struct ParsedBlock {
734    source_range: Range<usize>,
735    kind: RichDocumentBlockKind,
736}
737
738#[derive(Clone, Default)]
739struct InlineContext {
740    strong: usize,
741    emphasis: usize,
742    strikethrough: usize,
743    code: usize,
744    link: Option<RichLink>,
745    image: Option<RichInlineImage>,
746}
747
748enum ParseBlock {
749    Text {
750        start: usize,
751        end: usize,
752        kind: TextBlockKind,
753        spans: Vec<RichDocumentSpan>,
754    },
755    Code {
756        start: usize,
757        end: usize,
758        language: Option<String>,
759        code: String,
760    },
761    List {
762        start: usize,
763        end: usize,
764        ordered_start: Option<u64>,
765        items: Vec<RichListItem>,
766        current_item: Option<RichListItem>,
767    },
768}
769
770#[derive(Clone)]
771enum TextBlockKind {
772    Paragraph,
773    Heading(u8),
774    Quote(Option<String>),
775}
776
777fn parse_markdown_blocks(markdown: &str, base: usize) -> Vec<ParsedBlock> {
778    let mut options = Options::empty();
779    options.insert(Options::ENABLE_STRIKETHROUGH);
780    options.insert(Options::ENABLE_TASKLISTS);
781    options.insert(Options::ENABLE_TABLES);
782    options.insert(Options::ENABLE_GFM);
783    let mut blocks = Vec::new();
784    let mut current: Option<ParseBlock> = None;
785    let mut inline = InlineContext::default();
786    let mut quote_label: Option<String> = None;
787
788    for (event, local_range) in Parser::new_ext(markdown, options).into_offset_iter() {
789        let range = base + local_range.start..base + local_range.end;
790        match event {
791            MarkdownEvent::Start(Tag::Paragraph) => {
792                if current.is_none() {
793                    current = Some(ParseBlock::Text {
794                        start: range.start,
795                        end: range.end,
796                        kind: TextBlockKind::Paragraph,
797                        spans: Vec::new(),
798                    });
799                }
800            }
801            MarkdownEvent::End(TagEnd::Paragraph) => {
802                extend_end(&mut current, range.end);
803                if !matches!(current, Some(ParseBlock::List { .. })) {
804                    finish_block(&mut current, &mut blocks);
805                }
806            }
807            MarkdownEvent::Start(Tag::Heading { level, .. }) => {
808                finish_block(&mut current, &mut blocks);
809                current = Some(ParseBlock::Text {
810                    start: range.start,
811                    end: range.end,
812                    kind: TextBlockKind::Heading(heading_level(level)),
813                    spans: Vec::new(),
814                });
815            }
816            MarkdownEvent::End(TagEnd::Heading(_)) => {
817                extend_end(&mut current, range.end);
818                finish_block(&mut current, &mut blocks);
819            }
820            MarkdownEvent::Start(Tag::BlockQuote(kind)) => {
821                finish_block(&mut current, &mut blocks);
822                quote_label = kind.map(|kind| format!("{kind:?}"));
823                current = Some(ParseBlock::Text {
824                    start: range.start,
825                    end: range.end,
826                    kind: TextBlockKind::Quote(quote_label.clone()),
827                    spans: Vec::new(),
828                });
829            }
830            MarkdownEvent::End(TagEnd::BlockQuote(_)) => {
831                extend_end(&mut current, range.end);
832                finish_block(&mut current, &mut blocks);
833                quote_label = None;
834            }
835            MarkdownEvent::Start(Tag::CodeBlock(kind)) => {
836                finish_block(&mut current, &mut blocks);
837                current = Some(ParseBlock::Code {
838                    start: range.start,
839                    end: range.end,
840                    language: match kind {
841                        CodeBlockKind::Indented => None,
842                        CodeBlockKind::Fenced(language) => {
843                            let language = language.trim();
844                            (!language.is_empty()).then(|| language.to_string())
845                        }
846                    },
847                    code: String::new(),
848                });
849            }
850            MarkdownEvent::End(TagEnd::CodeBlock) => {
851                extend_end(&mut current, range.end);
852                finish_block(&mut current, &mut blocks);
853            }
854            MarkdownEvent::Start(Tag::List(start)) => {
855                if !matches!(current, Some(ParseBlock::List { .. })) {
856                    finish_block(&mut current, &mut blocks);
857                    current = Some(ParseBlock::List {
858                        start: range.start,
859                        end: range.end,
860                        ordered_start: start,
861                        items: Vec::new(),
862                        current_item: None,
863                    });
864                }
865            }
866            MarkdownEvent::End(TagEnd::List(_)) => {
867                finish_list_item(&mut current, range.end);
868                extend_end(&mut current, range.end);
869                finish_block(&mut current, &mut blocks);
870            }
871            MarkdownEvent::Start(Tag::Item) => {
872                finish_list_item(&mut current, range.start);
873                if let Some(ParseBlock::List { current_item, .. }) = &mut current {
874                    *current_item = Some(RichListItem {
875                        source_range: range.clone(),
876                        spans: Vec::new(),
877                        checked: None,
878                    });
879                }
880            }
881            MarkdownEvent::End(TagEnd::Item) => finish_list_item(&mut current, range.end),
882            MarkdownEvent::Start(Tag::Emphasis) => inline.emphasis += 1,
883            MarkdownEvent::End(TagEnd::Emphasis) => {
884                inline.emphasis = inline.emphasis.saturating_sub(1);
885            }
886            MarkdownEvent::Start(Tag::Strong) => inline.strong += 1,
887            MarkdownEvent::End(TagEnd::Strong) => {
888                inline.strong = inline.strong.saturating_sub(1);
889            }
890            MarkdownEvent::Start(Tag::Strikethrough) => inline.strikethrough += 1,
891            MarkdownEvent::End(TagEnd::Strikethrough) => {
892                inline.strikethrough = inline.strikethrough.saturating_sub(1);
893            }
894            MarkdownEvent::Start(Tag::Link {
895                dest_url, title, ..
896            }) => {
897                inline.link = Some(RichLink {
898                    destination: dest_url.to_string(),
899                    title: (!title.is_empty()).then(|| title.to_string()),
900                });
901            }
902            MarkdownEvent::End(TagEnd::Link) => inline.link = None,
903            MarkdownEvent::Start(Tag::Image {
904                dest_url, title, ..
905            }) => {
906                inline.image = Some(RichInlineImage {
907                    source: dest_url.to_string(),
908                    alt: String::new(),
909                    title: (!title.is_empty()).then(|| title.to_string()),
910                });
911            }
912            MarkdownEvent::End(TagEnd::Image) => {
913                if let Some(image) = inline.image.take() {
914                    let display = if image.alt.is_empty() {
915                        "Image".to_string()
916                    } else {
917                        image.alt.clone()
918                    };
919                    push_span(&mut current, display, range, &inline, Some(image));
920                }
921            }
922            MarkdownEvent::Text(text) => {
923                if let Some(image) = &mut inline.image {
924                    image.alt.push_str(&text);
925                } else if let Some(ParseBlock::Code { code, end, .. }) = &mut current {
926                    code.push_str(&text);
927                    *end = (*end).max(range.end);
928                } else {
929                    ensure_text_block(&mut current, range.start, quote_label.clone());
930                    push_span(&mut current, text.to_string(), range, &inline, None);
931                }
932            }
933            MarkdownEvent::Code(code) => {
934                ensure_text_block(&mut current, range.start, quote_label.clone());
935                inline.code += 1;
936                push_span(&mut current, code.to_string(), range, &inline, None);
937                inline.code = inline.code.saturating_sub(1);
938            }
939            MarkdownEvent::SoftBreak | MarkdownEvent::HardBreak => {
940                ensure_text_block(&mut current, range.start, quote_label.clone());
941                push_span(&mut current, "\n".to_string(), range, &inline, None);
942            }
943            MarkdownEvent::TaskListMarker(checked) => {
944                if let Some(ParseBlock::List {
945                    current_item: Some(item),
946                    ..
947                }) = &mut current
948                {
949                    item.checked = Some(checked);
950                }
951            }
952            MarkdownEvent::Rule => {
953                finish_block(&mut current, &mut blocks);
954                blocks.push(ParsedBlock {
955                    source_range: range,
956                    kind: RichDocumentBlockKind::ThematicBreak,
957                });
958            }
959            MarkdownEvent::Html(html) | MarkdownEvent::InlineHtml(html) => {
960                ensure_text_block(&mut current, range.start, quote_label.clone());
961                push_span(&mut current, html.to_string(), range, &inline, None);
962            }
963            MarkdownEvent::FootnoteReference(reference) => {
964                ensure_text_block(&mut current, range.start, quote_label.clone());
965                push_span(&mut current, format!("[{reference}]"), range, &inline, None);
966            }
967            _ => {}
968        }
969    }
970    finish_block(&mut current, &mut blocks);
971    blocks
972}
973
974fn heading_level(level: HeadingLevel) -> u8 {
975    match level {
976        HeadingLevel::H1 => 1,
977        HeadingLevel::H2 => 2,
978        HeadingLevel::H3 => 3,
979        HeadingLevel::H4 => 4,
980        HeadingLevel::H5 => 5,
981        HeadingLevel::H6 => 6,
982    }
983}
984
985fn ensure_text_block(current: &mut Option<ParseBlock>, start: usize, quote: Option<String>) {
986    if current.is_none() {
987        *current = Some(ParseBlock::Text {
988            start,
989            end: start,
990            kind: quote.map_or(TextBlockKind::Paragraph, |label| {
991                TextBlockKind::Quote(Some(label))
992            }),
993            spans: Vec::new(),
994        });
995    }
996}
997
998fn push_span(
999    current: &mut Option<ParseBlock>,
1000    text: String,
1001    source_range: Range<usize>,
1002    inline: &InlineContext,
1003    image: Option<RichInlineImage>,
1004) {
1005    let style = RichInlineStyle {
1006        strong: inline.strong > 0,
1007        emphasis: inline.emphasis > 0,
1008        strikethrough: inline.strikethrough > 0,
1009    };
1010    let kind = if let Some(image) = image {
1011        RichInlineKind::Image(image)
1012    } else if inline.code > 0 {
1013        RichInlineKind::Code
1014    } else if let Some(link) = &inline.link {
1015        RichInlineKind::Link(link.clone())
1016    } else {
1017        RichInlineKind::Text
1018    };
1019    let span = RichDocumentSpan {
1020        text,
1021        source_range: source_range.clone(),
1022        style,
1023        kind,
1024    };
1025    match current {
1026        Some(ParseBlock::Text { spans, end, .. }) => {
1027            spans.push(span);
1028            *end = (*end).max(source_range.end);
1029        }
1030        Some(ParseBlock::List {
1031            current_item, end, ..
1032        }) => {
1033            if current_item.is_none() {
1034                *current_item = Some(RichListItem {
1035                    source_range: source_range.clone(),
1036                    spans: Vec::new(),
1037                    checked: None,
1038                });
1039            }
1040            if let Some(item) = current_item {
1041                item.source_range.end = item.source_range.end.max(source_range.end);
1042                item.spans.push(span);
1043            }
1044            *end = (*end).max(source_range.end);
1045        }
1046        Some(ParseBlock::Code { .. }) | None => {}
1047    }
1048}
1049
1050fn finish_list_item(current: &mut Option<ParseBlock>, end: usize) {
1051    if let Some(ParseBlock::List {
1052        items,
1053        current_item,
1054        ..
1055    }) = current
1056        && let Some(mut item) = current_item.take()
1057    {
1058        item.source_range.end = item.source_range.end.max(end);
1059        items.push(item);
1060    }
1061}
1062
1063fn extend_end(current: &mut Option<ParseBlock>, end: usize) {
1064    match current {
1065        Some(ParseBlock::Text { end: current, .. })
1066        | Some(ParseBlock::Code { end: current, .. })
1067        | Some(ParseBlock::List { end: current, .. }) => *current = (*current).max(end),
1068        None => {}
1069    }
1070}
1071
1072fn finish_block(current: &mut Option<ParseBlock>, blocks: &mut Vec<ParsedBlock>) {
1073    let Some(block) = current.take() else {
1074        return;
1075    };
1076    let parsed = match block {
1077        ParseBlock::Text {
1078            start,
1079            end,
1080            kind,
1081            spans,
1082        } => {
1083            if spans.is_empty() {
1084                return;
1085            }
1086            let kind = match kind {
1087                TextBlockKind::Paragraph => RichDocumentBlockKind::Paragraph { spans },
1088                TextBlockKind::Heading(level) => RichDocumentBlockKind::Heading { level, spans },
1089                TextBlockKind::Quote(label) => RichDocumentBlockKind::BlockQuote { label, spans },
1090            };
1091            ParsedBlock {
1092                source_range: start..end.max(start),
1093                kind,
1094            }
1095        }
1096        ParseBlock::Code {
1097            start,
1098            end,
1099            language,
1100            code,
1101        } => ParsedBlock {
1102            source_range: start..end.max(start),
1103            kind: RichDocumentBlockKind::CodeBlock { language, code },
1104        },
1105        ParseBlock::List {
1106            start,
1107            end,
1108            ordered_start,
1109            mut items,
1110            current_item,
1111        } => {
1112            if let Some(item) = current_item {
1113                items.push(item);
1114            }
1115            ParsedBlock {
1116                source_range: start..end.max(start),
1117                kind: RichDocumentBlockKind::List {
1118                    start: ordered_start,
1119                    items,
1120                },
1121            }
1122        }
1123    };
1124    blocks.push(parsed);
1125}
1126
1127fn spans_plain_text(spans: &[RichDocumentSpan]) -> String {
1128    spans.iter().map(|span| span.text.as_str()).collect()
1129}
1130
1131#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1132pub enum RichSyntaxTokenKind {
1133    Keyword,
1134    String,
1135    Number,
1136    Comment,
1137    Type,
1138    Function,
1139    Property,
1140    Added,
1141    Removed,
1142    Header,
1143}
1144
1145#[derive(Clone, Debug, PartialEq, Eq)]
1146pub struct RichSyntaxSpan {
1147    pub range: Range<usize>,
1148    pub kind: RichSyntaxTokenKind,
1149}
1150
1151pub trait RichSyntaxHighlighter {
1152    fn highlight(&self, language: Option<&str>, source: &str) -> Vec<RichSyntaxSpan>;
1153}
1154
1155impl<F> RichSyntaxHighlighter for F
1156where
1157    F: Fn(Option<&str>, &str) -> Vec<RichSyntaxSpan>,
1158{
1159    fn highlight(&self, language: Option<&str>, source: &str) -> Vec<RichSyntaxSpan> {
1160        self(language, source)
1161    }
1162}
1163
1164/// Lightweight dependency-free lexer used by the default code-block renderer.
1165///
1166/// It deliberately recognizes broad token classes rather than implementing a
1167/// language grammar. Applications can replace it with tree-sitter, syntect, or
1168/// an LSP-backed highlighter through [`RichSyntaxHighlighter`].
1169#[derive(Clone, Copy, Debug, Default)]
1170pub struct BasicSyntaxHighlighter;
1171
1172impl RichSyntaxHighlighter for BasicSyntaxHighlighter {
1173    fn highlight(&self, language: Option<&str>, source: &str) -> Vec<RichSyntaxSpan> {
1174        let language = language.unwrap_or_default().to_ascii_lowercase();
1175        if matches!(language.as_str(), "diff" | "patch") {
1176            return highlight_diff(source);
1177        }
1178        highlight_code(&language, source)
1179    }
1180}
1181
1182fn highlight_diff(source: &str) -> Vec<RichSyntaxSpan> {
1183    let mut spans = Vec::new();
1184    let mut offset = 0;
1185    for line in source.split_inclusive('\n') {
1186        let kind = if line.starts_with("@@") || line.starts_with("diff ") {
1187            Some(RichSyntaxTokenKind::Header)
1188        } else if line.starts_with('+') && !line.starts_with("+++") {
1189            Some(RichSyntaxTokenKind::Added)
1190        } else if line.starts_with('-') && !line.starts_with("---") {
1191            Some(RichSyntaxTokenKind::Removed)
1192        } else {
1193            None
1194        };
1195        if let Some(kind) = kind {
1196            spans.push(RichSyntaxSpan {
1197                range: offset..offset + line.len(),
1198                kind,
1199            });
1200        }
1201        offset += line.len();
1202    }
1203    spans
1204}
1205
1206fn highlight_code(language: &str, source: &str) -> Vec<RichSyntaxSpan> {
1207    let mut spans = Vec::new();
1208    let bytes = source.as_bytes();
1209    let mut index = 0;
1210    while index < bytes.len() {
1211        if starts_line_comment(language, bytes, index) {
1212            let end = source[index..]
1213                .find('\n')
1214                .map_or(source.len(), |relative| index + relative);
1215            spans.push(RichSyntaxSpan {
1216                range: index..end,
1217                kind: RichSyntaxTokenKind::Comment,
1218            });
1219            index = end;
1220            continue;
1221        }
1222        if matches!(bytes[index], b'\'' | b'"' | b'`') {
1223            let quote = bytes[index];
1224            let start = index;
1225            index += 1;
1226            while index < bytes.len() {
1227                if bytes[index] == b'\\' {
1228                    index = (index + 2).min(bytes.len());
1229                } else if bytes[index] == quote {
1230                    index += 1;
1231                    break;
1232                } else {
1233                    index += 1;
1234                }
1235            }
1236            spans.push(RichSyntaxSpan {
1237                range: start..index,
1238                kind: RichSyntaxTokenKind::String,
1239            });
1240            continue;
1241        }
1242        if bytes[index].is_ascii_digit() {
1243            let start = index;
1244            index += 1;
1245            while index < bytes.len()
1246                && (bytes[index].is_ascii_alphanumeric()
1247                    || matches!(bytes[index], b'.' | b'_' | b'x' | b'o' | b'b'))
1248            {
1249                index += 1;
1250            }
1251            spans.push(RichSyntaxSpan {
1252                range: start..index,
1253                kind: RichSyntaxTokenKind::Number,
1254            });
1255            continue;
1256        }
1257        if bytes[index].is_ascii_alphabetic() || bytes[index] == b'_' {
1258            let start = index;
1259            index += 1;
1260            while index < bytes.len()
1261                && (bytes[index].is_ascii_alphanumeric() || bytes[index] == b'_')
1262            {
1263                index += 1;
1264            }
1265            let word = &source[start..index];
1266            if is_keyword(language, word) {
1267                spans.push(RichSyntaxSpan {
1268                    range: start..index,
1269                    kind: RichSyntaxTokenKind::Keyword,
1270                });
1271            } else if word.chars().next().is_some_and(char::is_uppercase) {
1272                spans.push(RichSyntaxSpan {
1273                    range: start..index,
1274                    kind: RichSyntaxTokenKind::Type,
1275                });
1276            }
1277            continue;
1278        }
1279        index += source[index..].chars().next().map_or(1, char::len_utf8);
1280    }
1281    spans
1282}
1283
1284fn starts_line_comment(language: &str, bytes: &[u8], index: usize) -> bool {
1285    if bytes.get(index..index + 2) == Some(b"//") {
1286        return true;
1287    }
1288    bytes[index] == b'#'
1289        && matches!(
1290            language,
1291            "python" | "py" | "shell" | "sh" | "bash" | "zsh" | "toml" | "yaml" | "yml"
1292        )
1293}
1294
1295fn is_keyword(language: &str, word: &str) -> bool {
1296    const COMMON: &[&str] = &[
1297        "as",
1298        "async",
1299        "await",
1300        "break",
1301        "case",
1302        "class",
1303        "const",
1304        "continue",
1305        "default",
1306        "do",
1307        "else",
1308        "enum",
1309        "export",
1310        "extends",
1311        "false",
1312        "fn",
1313        "for",
1314        "from",
1315        "function",
1316        "if",
1317        "impl",
1318        "import",
1319        "in",
1320        "interface",
1321        "let",
1322        "loop",
1323        "match",
1324        "mod",
1325        "move",
1326        "mut",
1327        "new",
1328        "none",
1329        "null",
1330        "pub",
1331        "return",
1332        "self",
1333        "static",
1334        "struct",
1335        "super",
1336        "switch",
1337        "trait",
1338        "true",
1339        "try",
1340        "type",
1341        "use",
1342        "var",
1343        "where",
1344        "while",
1345        "yield",
1346    ];
1347    COMMON.contains(&word)
1348        || (matches!(language, "python" | "py")
1349            && matches!(
1350                word,
1351                "def" | "elif" | "except" | "finally" | "lambda" | "with"
1352            ))
1353}
1354
1355#[cfg(test)]
1356mod model_tests {
1357    use super::*;
1358
1359    #[test]
1360    fn markdown_parser_preserves_structure_and_inline_actions() {
1361        let model = RichDocumentModel::from_markdown(
1362            "# Report\n\nRead [docs](https://example.test) and `code`.\n\n- one\n- [x] two\n\n```rust\nlet n = 42;\n```",
1363        );
1364        let blocks = model.blocks();
1365        assert!(matches!(
1366            blocks[0].kind,
1367            RichDocumentBlockKind::Heading { level: 1, .. }
1368        ));
1369        assert!(matches!(
1370            blocks[1].kind,
1371            RichDocumentBlockKind::Paragraph { ref spans }
1372                if spans.iter().any(|span| matches!(span.kind, RichInlineKind::Link(_)))
1373                    && spans.iter().any(|span| matches!(span.kind, RichInlineKind::Code))
1374        ));
1375        assert!(matches!(
1376            blocks[2].kind,
1377            RichDocumentBlockKind::List { ref items, .. }
1378                if items.len() == 2 && items[1].checked == Some(true)
1379        ));
1380        assert!(matches!(
1381            blocks[3].kind,
1382            RichDocumentBlockKind::CodeBlock { ref language, ref code }
1383                if language.as_deref() == Some("rust") && code.contains("let n")
1384        ));
1385    }
1386
1387    #[test]
1388    fn streaming_append_reparses_only_tail_and_preserves_prefix_ids() {
1389        let model = RichDocumentModel::from_markdown("# Stable\n\nStreaming");
1390        let before = model.blocks();
1391        model.append_markdown(" text\n\n- next");
1392        let after = model.blocks();
1393        assert_eq!(before[0].id, after[0].id);
1394        assert_eq!(before[1].id, after[1].id);
1395        assert_eq!(after[1].plain_text(), "Streaming text");
1396        let update = model.last_update();
1397        assert!(update.append_only);
1398        assert_eq!(update.reused_prefix_blocks, 1);
1399        assert_eq!(update.reparsed_source.start, before[1].source_range.start);
1400    }
1401
1402    #[test]
1403    fn structured_blocks_update_in_place() {
1404        let model = RichDocumentModel::new();
1405        let id = model.append_extension(RichExtensionBlock::new("tool-call", "Search"));
1406        let mut changed = RichExtensionBlock::new("tool-call", "Search");
1407        changed.status = RichDocumentStatus::Success;
1408        changed.body = "3 results".to_string();
1409        assert!(model.update_structured(id, RichDocumentBlockKind::Extension(changed)));
1410        assert_eq!(model.blocks()[0].id, id);
1411        assert_eq!(model.last_update().changed_block_ids, vec![id]);
1412    }
1413
1414    #[test]
1415    fn markdown_segments_remain_ordered_around_structured_blocks() {
1416        let model = RichDocumentModel::from_markdown("Before");
1417        let before_id = model.blocks()[0].id;
1418        let extension_id =
1419            model.append_extension(RichExtensionBlock::new("tool-call", "Operation"));
1420
1421        model.append_markdown("\n\nAfter");
1422        let first = model.blocks();
1423        assert_eq!(first.len(), 3);
1424        assert_eq!(first[0].id, before_id);
1425        assert_eq!(first[1].id, extension_id);
1426        assert_eq!(first[2].plain_text(), "After");
1427        let after_id = first[2].id;
1428
1429        model.append_markdown(" continued");
1430        let second = model.blocks();
1431        assert_eq!(second[0].id, before_id);
1432        assert_eq!(second[1].id, extension_id);
1433        assert_eq!(second[2].id, after_id);
1434        assert_eq!(second[2].plain_text(), "After continued");
1435        assert_eq!(model.last_update().reused_prefix_blocks, 2);
1436    }
1437
1438    #[test]
1439    fn replacement_diagnostics_include_removed_block_ids() {
1440        let model = RichDocumentModel::from_markdown("# Heading\n\nParagraph");
1441        let removed = model.blocks()[1].id;
1442        model.set_markdown("# Heading");
1443        assert!(model.last_update().changed_block_ids.contains(&removed));
1444    }
1445
1446    #[test]
1447    fn basic_highlighter_handles_code_and_diff_tokens() {
1448        let rust = BasicSyntaxHighlighter.highlight(Some("rust"), "let value = 42; // count");
1449        assert!(
1450            rust.iter()
1451                .any(|span| span.kind == RichSyntaxTokenKind::Keyword)
1452        );
1453        assert!(
1454            rust.iter()
1455                .any(|span| span.kind == RichSyntaxTokenKind::Number)
1456        );
1457        assert!(
1458            rust.iter()
1459                .any(|span| span.kind == RichSyntaxTokenKind::Comment)
1460        );
1461
1462        let diff = BasicSyntaxHighlighter.highlight(Some("diff"), "@@ -1 +1 @@\n-old\n+new\n");
1463        assert!(
1464            diff.iter()
1465                .any(|span| span.kind == RichSyntaxTokenKind::Header)
1466        );
1467        assert!(
1468            diff.iter()
1469                .any(|span| span.kind == RichSyntaxTokenKind::Removed)
1470        );
1471        assert!(
1472            diff.iter()
1473                .any(|span| span.kind == RichSyntaxTokenKind::Added)
1474        );
1475    }
1476}