markstream
Streaming Markdown for Flutter, with rich content and source-aware selection.
中文 · pub.dev · Guide · Example · GitHub
Build AI chat interfaces, Markdown previews, reading views, and rich assistant responses. Markstream combines incremental parsing, Flutter-native rendering, rich-content selection, and an extensible AST in one package.
Developed in Kelivo, now available as an independently maintained Flutter library.
Why Markstream?
- Streaming is part of the parser. Feed cumulative text snapshots; completed leading blocks retain their identity while the unfinished tail changes.
- Selection understands the document. Select across paragraphs, inline code, tables, and custom widgets; preserve Markdown formatting when copying.
- Rich content, configurable syntax. Tables, tasks, alerts, details, HTML, math syntax, and custom directives fit into the same rendering pipeline.
- Source coordinates stay meaningful. Immutable AST nodes retain UTF-16 ranges in the original text for search highlighting, annotations, and TTS.
- Your application owns the integrations. Plug in syntax highlighting, math rendering, image loading, links, citations, and application-specific blocks.
Supported content and capabilities
| Area | Included |
|---|---|
| Rich text | Headings, bold, italic, strikethrough, ==highlight==, inline code, escapes, and HTML entities |
| Document structure | Ordered/unordered and nested lists, block quotes, horizontal rules, task checkboxes, and radio items |
| Tables | Column alignment, rich text in cells, horizontal scrolling, pagination, TSV selection, Markdown/CSV copying, and a PNG-capture callback |
| Code blocks | Fences, language labels, copy controls, folding, wrapping options, and bounded rendering of large blocks; syntax colors via CodeHighlighter |
| Math | Inline $…$ / \(…\) and display $$…$$ / \[…\] parsing, with source-aware LaTeX selection; visual typesetting via MathRenderer |
| Links and images | Explicit/reference links, autolinks, and image syntax; navigation via LinkHandler, image resolution/display via ImageBuilder |
| Alerts and directives | GitHub-style NOTE/TIP/IMPORTANT/WARNING/CAUTION alerts, :::note-style cards, and custom directive builders |
| Expandable content | <details> / <summary> blocks with retained expansion state |
| Native HTML | A sanitized subset including text styles, links, images, lists, tables, alignment, subscript/superscript, and bounded inline CSS |
| Streaming | Cumulative updates, retained completed blocks, incomplete-block policies, optional optimistic inline closure, and update coalescing for long replies |
| Selection and copying | Cross-block selection, selectable inline widgets, plain text and Markdown copying, and source ranges for selected content |
| Source highlights | Original-source ranges for search hits, annotations, and speech tracking, without reparsing the document |
| Themes and labels | Light/dark color schemes, body/code typography, per-component tokens, background modes, and configurable action labels |
| Extensions | Custom block/inline syntax, named inline builders, fenced-code builders, directive builders, and toolbar actions |
| Parsing and export | LLM/CommonMark/GFM profiles, immutable AST, structure scans, and Markdown/HTML/plain-text serialization |
| Text layout | Text scaling, RTL layouts, CJK-aware parsing, and source mapping across decoded entities and escaped text |
Features depend on the selected parsing profile. Visual math, syntax coloring, image display, and link navigation use adapters; they are not bundled engines. The default renderer displays LaTeX source, unhighlighted code, and image alt text until the respective adapter is supplied.
Preview

This preview is rendered by the actual package with its built-in widgets and theme. It does not use application-specific math or highlighting adapters.
Install
flutter pub add markstream
Or add a version constraint:
dependencies:
markstream: ^0.1.1
Requires Flutter 3.44.9+ and Dart 3.12.1+ (below 4.0.0).
The package has only two runtime dependencies: Flutter and
lucide_icons_flutter.
Quick start
import 'package:flutter/material.dart';
import 'package:markstream/markstream.dart';
void main() => runApp(
const MaterialApp(
home: Scaffold(
body: SelectionArea(
child: SingleChildScrollView(
padding: EdgeInsets.all(24),
child: MarkstreamView(
source: '# Hello\n\nMarkdown with **bold**, `code`, and more.',
),
),
),
),
),
);
MarkstreamView sizes itself to its content. The application supplies the
scroll container, SelectionArea, and selection menu.
Stream AI responses
Keep the same view mounted and pass the complete text received so far:
MarkstreamView(
source: accumulatedMarkdown,
streaming: isReceiving,
)
Set streaming to false when generation finishes. Replacement, truncation,
and parser-option changes are supported as well as appending. An unchanged
snapshot reuses the existing parsed document. For fine-grained control, use
IncrementalDocument and pass its snapshot through document: instead.
The runnable example includes source editing, simulated streaming, and side-by-side or tabbed previews.
Copy selections as Markdown
Create a MarkstreamSelectionController in the owning widget and pass it to
the view:
MarkstreamView(
source: markdown,
selectionController: selectionController,
)
Use hasSelection, selectedPlainText, selectedMarkdown, and
copySelectionAsMarkdown(). A controller can cover multiple views inside one
selection area and copy them in visual order. Dispose it with the owning widget.
Inline widgets can participate through SelectableSpanAdapter; extension
builders provide explicit text segments so copied content remains meaningful.
See selection and rendering.
Make it fit your app
| Extension point | Use it for |
|---|---|
MarkstreamTheme |
Typography, colors, component surfaces, spacing, and background modes |
MarkstreamLabels |
Localized labels and default card titles |
CodeHighlighter |
A synchronous or asynchronous syntax highlighter that preserves code text |
MathRenderer |
Your preferred LaTeX widget; Markstream retains selection of the source |
ImageBuilder |
Network, file, cached, or custom image widgets |
LinkHandler |
URL launching, in-app routing, or link previews |
MarkstreamExtensions |
Citation chips, custom inline syntax, diagram fences, and application-specific cards |
codeExtraActions / tableExtraActions |
Save, share, or export actions owned by your application |
For example, register a custom directive while retaining built-in child rendering and selection:
final extensions = MarkstreamExtensions(
directiveBuilders: {
'answer': (context, node, rendering) => MarkstreamDirectiveCard(
kind: 'note',
title: 'Answer',
theme: rendering.theme,
child: Column(
children: [
for (final child in node.children)
rendering.buildBlock(child as BlockNode),
],
),
),
},
);
Keep extension registrations stable across streaming updates. See the guide for adapter contracts, syntax profiles, theming, HTML support, source highlights, serialization, and source-coordinate rules.
Platforms and validation
The rendering layer uses Flutter widgets and has no native platform plugin. It targets Android, iOS, macOS, Windows, Linux, and Web.
The standalone release was checked with Flutter 3.47.6 / Dart 3.13.5: 309 package tests, 2 example tests, static analysis, and macOS/Web builds. Widget tests exercise desktop and Android-style selection, text scaling, RTL, and mixed rich content. These checks do not replace native-device testing in an application's own environment.
CommonMark and GFM are configurable profiles, not claims of complete specification compliance. The known differences are documented; the specification runner reports exact-output differences rather than treating a percentage as a passing threshold. Native HTML supports a safe subset, not arbitrary browser layout or JavaScript.
Documentation and development
| Resource | Contents |
|---|---|
| Guide | Parser profiles, incremental documents, adapters, themes, HTML, and source highlights |
| Rendering and selection | Retained rendering, rich blocks, selection, copying, and performance bounds |
| Example | Run the editable streaming playground on macOS or Web |
| Benchmarks | Fixed fixtures, commands, and measurement boundaries |
| Source and maintenance | Extraction provenance and independent synchronization with Kelivo |
| Changelog | Release history |
flutter pub get
dart analyze --fatal-infos lib test
flutter test
cd example
flutter pub get
flutter test
flutter run -d macos
CI also checks formatting and builds the Web example. Benchmarks are separate diagnostic runs, not assertions or performance guarantees. Contributions and bug reports are welcome on GitHub.
License
MIT, starting with version 0.1.1. You can use, modify, and distribute the project-authored code in commercial and closed-source applications while retaining the copyright and license notice. Third-party data and test fixtures retain their own licenses; see THIRD_PARTY_NOTICES.md.
Libraries
- markstream
- Markdown parsing and rendering for streaming Flutter applications.
- markstream_core
- Markdown syntax and source coordinates without Flutter dependencies.