feat: cross-block & cross-widget text selection (0.2.0)

[mike-doctorina]

Summary

Adds cross-block and cross-widget text selection to flutter_md — the headline feature of the upcoming 0.2.0 release. A user can now drag-select across paragraphs, lists, tables, code fences and quotes, across multiple MarkdownWidgets, and even keep the selection alive while a ListView disposes and re-creates items (chat scrolling). Copy produces either plain text or reconstructed Markdown.

Because stock SelectionArea/SelectableRegion cannot do this (Phase-1 spikes documented the glue/disposal defects and the private scrollable delegate that hides list items), the selection is anchored on the immutable Markdown model rather than on mounted render objects. Logical anchors make text extraction mount-independent, and the highlight is drawn outside the cached content ui.Picture, so selection and drag repaints never rebuild the glyph cache.

Closes #25. Builds on the render refactor tracked alongside it.

What's new

Selection core (lib/src/selection.dart) — MarkdownSelectionController (anchors on the model, spans blocks/widgets, survives disposal), MarkdownPosition / MarkdownSelection, MarkdownDocumentRef, MarkdownSelectedContent, MarkdownSelectionGroup (only one selection active at a time; also resets external SelectableText), the content-anchored MarkdownReconciliationPolicy (streaming-safe), the shared markdownBlockRenderedText linearizer, and the MarkdownSelectionSurface contract.

Selectable rendering — MarkdownRenderObject implements MarkdownSelectionSurface, maps pointers to logical positions and paints the highlight outside the cached Picture (repaint boundary when selectable). A MultiPainterSelectable mixin (+ SelectableFragment) extends this across the many TextPainters of a list's items and a table's cells, so a drag can start/end inside a list item or table cell and copied text keeps the \n / \t separators.

Interaction (lib/src/selection_scope.dart) — MarkdownSelectionScope drives selection from mouse/trackpad/stylus drag and touch long-press-drag, plus:

• Keyboard, mirroring SelectableRegion: Ctrl/Cmd+C copy, Ctrl/Cmd+A select-all, Shift+arrows extend by character/word/line/document (and vertically by geometry), Esc clear.
• Granular gestures: double-click/tap selects a word, triple selects the block, single click collapses, Shift-click extends; word boundaries use platform segmentation (so can't stays whole).
• Context toolbar (right-click / long-press) via an adaptive AdaptiveTextSelectionToolbar, fully customizable through contextMenuBuilder.
• Native handles + magnifier on touch platforms, driven by SelectionOverlay; endpoints push LeaderLayers so handles follow scrolling content across widgets.
• Cursor feedback: hand over links, I-beam while selectable, default otherwise.
• New SelectableText-style params: focusNode, enabled, selectionColor, contextMenuBuilder, magnifierConfiguration, selectionControls, onSelectionChanged.

Copy-as-Markdown — MarkdownMarkupFormatter reconstructs Markdown structure on copy (heading #s, nested list markers with task checkboxes, > prefixes, fenced code, pipe tables) for fully-covered blocks, falling back to sliced plain text on partial boundary blocks. The default copy behaviour is unchanged (MarkdownPlainTextFormatter).

MarkdownWidget gains optional documentId / controller (resolved from the ambient scope). Fully backward compatible: without a documentId the widget is inert.

Supporting changes

• Render layer split — lib/src/render.dart (~1750 lines) decomposed into lib/src/render/ (block_painter.dart, markdown_painter.dart, markdown_render_object.dart, span_builder.dart, and one file per block type under blocks/).
• Docs — new docs/architecture.md, development.md, parser.md, rendering.md, selection.md, and a docs/migration/0.0.x-to-0.2.x.md guide. README + CHANGELOG updated; version bumped to 0.2.0.
• Benchmarks — a benchmark_compare/ package comparing parse/render performance of flutter_md vs flutter_markdown vs gpt_markdown, plus a new selection_drag benchmark tier proving the highlight adds ~4 µs over a cache hit and never re-records the Picture.
• Example — reworked into tabs: the existing live Editor, a Selection tab spanning every block type across two grouped controllers + a plain SelectableText, and a Chat tab with real token-by-token streaming, typing indicator, auto-stick-to-bottom, and cross-message selection through scroll/disposal.

Adversarial review fixes folded in

• Crash when dragging near a zero-size selection surface (inverted num.clamp bounds for e.g. an empty streaming message).
• List offset drift: markdownBlockRenderedText now joins list items unconditionally to match the painter, so an empty leading/middle item no longer misaligns the highlight or truncates the copy.
• Handle drag that collapsed the selection onto itself disposed the live overlay mid-gesture — moveSelectionEdgeToGlobal now keeps ≥1 caret gap.
• Guards for controller swap (stale handle leaders) and for running without an Overlay/MaterialApp host.

Compatibility

0.2.x is almost entirely backward compatible. The only required code change is a new alert branch for direct MD$Block.map / switch callers (already shipped in 0.1.0). See the migration guide.

Testing

• dart format --line-length 80 — clean
• dart analyze --fatal-infos --fatal-warnings lib/ test/ — no issues
• flutter test test/unit_test.dart — 459 unit tests green (selection: core, widget integration, keyboard, handles, markup formatter)
• flutter test in example/ — smoke test green
• Render benchmark shows no regression (paint_hit ~41 µs, selection_drag ~45 µs)

---

🤖 Generated with Claude Code