Files
pipelines/app/lib/features/chat/ui/transcript/chat_markdown.dart
T
alan a5afc55a9d feat(app): render native transcript markdown
Port the web markdown subset to a pure Dart parser and a native
Material/Cupertino block renderer, with a caller seam for assistant text
parts and safe http(s) link activation.

- parser: entities, paragraphs, H1-H6, fenced code, quotes, lists, tables,
  rules, inline code/emphasis/links; entity overflow stays literal
- renderer: host text roles, inline/fenced code fills, table header fill,
  heading level and list/columnHeader semantics, horizontal code/table
  scrolling, native selection
- tests cover parser safety, both hosts, the seam and real taps
- probe plus note record the web evidence and remaining limits
2026-10-21 23:34:33 +01:00

452 lines
13 KiB
Dart

/// A pure, widget-free port of `web/src/markdown.js` for assistant prose.
///
/// The subset is deliberately the same one the browser renders: paragraphs,
/// `#`..`######` headings, fenced code (``` / ~~~, language label else `code`),
/// block quotes, bullet and ordered lists, `|` tables with a `---` delimiter
/// row, thematic rules, and inline code / bold / italic / links / bare http(s)
/// autolinks. Anything outside it stays plain text and is never dropped.
library;
const Map<String, String> _namedEntities = {
'amp': '&',
'lt': '<',
'gt': '>',
'quot': '"',
'apos': "'",
'nbsp': '\u00A0',
'hellip': '\u2026',
'mdash': '\u2014',
'ndash': '\u2013',
'lsquo': '\u2018',
'rsquo': '\u2019',
'ldquo': '\u201C',
'rdquo': '\u201D',
};
final RegExp _entity = RegExp(
r'&(#x[0-9A-Fa-f]+|#[0-9]+|[A-Za-z][A-Za-z0-9]*);',
);
final RegExp _hexReference = RegExp(r'^#x[0-9A-Fa-f]+$');
final RegExp _decimalReference = RegExp(r'^#[0-9]+$');
/// Decodes the HTML entities a message may carry in one left-to-right pass, so
/// `&amp;lt;` becomes `&lt;` and is never decoded twice. Unknown or malformed
/// references stay exactly as written.
String decodeHtmlEntities(String text) {
if (!text.contains('&')) return text;
return text.replaceAllMapped(_entity, (match) {
final body = match.group(1)!;
final named = _namedEntities[body];
if (named != null) return named;
return _numericReference(body) ?? match.group(0)!;
});
}
String? _numericReference(String body) {
int? codePoint;
if (body.startsWith('#x') || body.startsWith('#X')) {
if (_hexReference.hasMatch(body)) {
// `tryParse` returns null for a value too large for an int; the web
// reference parses such a value as an out-of-range number instead, and
// both paths keep the literal. Never let an entity throw.
codePoint = int.tryParse(body.substring(2), radix: 16);
}
} else if (body.startsWith('#')) {
if (_decimalReference.hasMatch(body)) {
codePoint = int.tryParse(body.substring(1));
}
}
if (codePoint == null || codePoint < 1 || codePoint > 0x10FFFF) return null;
return String.fromCharCode(codePoint);
}
// ---- Blocks -----------------------------------------------------------------
/// One rendered markdown block.
sealed class MarkdownBlock {
const MarkdownBlock();
}
final class MarkdownHeading extends MarkdownBlock {
const MarkdownHeading(this.level, this.text);
final int level;
final String text;
}
final class MarkdownParagraph extends MarkdownBlock {
const MarkdownParagraph(this.text);
final String text;
}
final class MarkdownCode extends MarkdownBlock {
const MarkdownCode(this.language, this.code);
final String language;
final String code;
}
final class MarkdownQuote extends MarkdownBlock {
const MarkdownQuote(this.lines);
final List<String> lines;
}
final class MarkdownList extends MarkdownBlock {
const MarkdownList({required this.ordered, required this.items});
final bool ordered;
final List<String> items;
}
final class MarkdownTable extends MarkdownBlock {
const MarkdownTable(this.header, this.rows);
final List<String> header;
final List<List<String>> rows;
}
final class MarkdownRule extends MarkdownBlock {
const MarkdownRule();
}
/// Parses [source] into the block list a renderer walks. Never throws.
List<MarkdownBlock> parseMarkdown(String? source) {
final lines = decodeHtmlEntities(
source ?? '',
).replaceAll('\r\n', '\n').replaceAll('\r', '\n').split('\n');
final blocks = <MarkdownBlock>[];
var i = 0;
while (i < lines.length) {
final line = lines[i];
final trimmed = line.trim();
if (trimmed.isEmpty) {
i += 1;
continue;
}
final fence = _fenceRun(trimmed);
if (fence != null) {
final language = trimmed.substring(fence.length).trim().split(' ').first;
final code = <String>[];
i += 1;
while (i < lines.length && _fenceRun(lines[i].trim()) == null) {
code.add(lines[i]);
i += 1;
}
if (i < lines.length) i += 1; // consume the closing fence
blocks.add(MarkdownCode(language, code.join('\n')));
continue;
}
final level = _headingLevel(trimmed);
if (level > 0) {
blocks.add(
MarkdownHeading(level, _trimEndHashes(trimmed.substring(level).trim())),
);
i += 1;
continue;
}
if (_isRule(trimmed)) {
blocks.add(const MarkdownRule());
i += 1;
continue;
}
if (trimmed.startsWith('>')) {
final quote = <String>[];
while (i < lines.length && lines[i].trim().startsWith('>')) {
quote.add(_quoteLine(lines[i]));
i += 1;
}
blocks.add(MarkdownQuote(quote));
continue;
}
if (_isTableStart(lines, i)) {
final header = _splitRow(lines[i]);
i += 2; // header + delimiter row
final rows = <List<String>>[];
while (i < lines.length &&
lines[i].contains('|') &&
lines[i].trim().isNotEmpty) {
rows.add(_fitRow(_splitRow(lines[i]), header.length));
i += 1;
}
blocks.add(MarkdownTable(header, rows));
continue;
}
final marker = _listMarker(line);
if (marker != null) {
final ordered = marker.ordered;
final items = <String>[];
while (i < lines.length && _listMarker(lines[i])?.ordered == ordered) {
items.add(_listMarker(lines[i])!.text);
i += 1;
}
blocks.add(MarkdownList(ordered: ordered, items: items));
continue;
}
final paragraph = <String>[line.trim()];
i += 1;
while (i < lines.length &&
lines[i].trim().isNotEmpty &&
!_startsBlock(lines, i)) {
paragraph.add(lines[i].trim());
i += 1;
}
blocks.add(MarkdownParagraph(paragraph.join(' ')));
}
return blocks;
}
/// The fence run (` ``` ` / `~~~`) a line opens or closes with, or null.
String? _fenceRun(String trimmed) {
if (trimmed.isEmpty) return null;
final first = trimmed[0];
if (first != '`' && first != '~') return null;
var end = 0;
while (end < trimmed.length && trimmed[end] == first) {
end += 1;
}
return end >= 3 ? trimmed.substring(0, end) : null;
}
int _headingLevel(String trimmed) {
var hashes = 0;
while (hashes < trimmed.length && trimmed[hashes] == '#') {
hashes += 1;
}
if (hashes == 0 || hashes > 6) return 0;
return trimmed.length == hashes || trimmed[hashes] == ' ' ? hashes : 0;
}
String _trimEndHashes(String text) => text.replaceFirst(RegExp(r'#+$'), '');
bool _isRule(String trimmed) {
if (trimmed.length < 3) return false;
final first = trimmed[0];
if (!'-*_'.contains(first)) return false;
for (var i = 0; i < trimmed.length; i += 1) {
if (trimmed[i] != first) return false;
}
return true;
}
/// True when [lines] at [index] is a table header followed by a `---` row.
bool _isTableStart(List<String> lines, int index) {
if (index + 1 >= lines.length || !lines[index].contains('|')) return false;
final delimiter = _splitRow(lines[index + 1]);
if (delimiter.isEmpty || _splitRow(lines[index]).length < 2) return false;
return delimiter.every(
(cell) =>
cell.isNotEmpty &&
cell.split('').every((char) => char == '-' || char == ':') &&
cell.contains('-'),
);
}
/// Splits a table row on unescaped `|`, dropping the outer empty cells.
List<String> _splitRow(String line) {
var value = line.trim();
if (value.startsWith('|')) value = value.substring(1);
if (value.endsWith('|')) value = value.substring(0, value.length - 1);
return value
.split('|')
.map((cell) => cell.replaceAll(r'\|', '|').trim())
.toList();
}
List<String> _fitRow(List<String> row, int size) => [
for (var index = 0; index < size; index += 1)
index < row.length ? row[index] : '',
];
final RegExp _orderedItem = RegExp(r'^(\d{1,9})[.)]\s+(.*)$');
final RegExp _bulletItem = RegExp(r'^([-*+])\s+(.*)$');
_ListMarker? _listMarker(String line) {
final trimmed = line.replaceFirst(RegExp(r'^\s+'), '');
final orderedMatch = _orderedItem.firstMatch(trimmed);
if (orderedMatch != null) {
return _ListMarker(true, orderedMatch.group(2)!);
}
final bulletMatch = _bulletItem.firstMatch(trimmed);
if (bulletMatch != null) return _ListMarker(false, bulletMatch.group(2)!);
return null;
}
final class _ListMarker {
const _ListMarker(this.ordered, this.text);
final bool ordered;
final String text;
}
/// True when [lines] at [index] begins a block that interrupts a paragraph.
bool _startsBlock(List<String> lines, int index) {
final trimmed = lines[index].trim();
return _fenceRun(trimmed) != null ||
_headingLevel(trimmed) > 0 ||
_isRule(trimmed) ||
trimmed.startsWith('>') ||
_listMarker(lines[index]) != null ||
_isTableStart(lines, index);
}
String _quoteLine(String line) {
var value = line.trim();
if (value.startsWith('>')) value = value.substring(1);
if (value.startsWith(' ')) value = value.substring(1);
return value.replaceFirst(RegExp(r'\s+$'), '');
}
// ---- Inline -----------------------------------------------------------------
/// One inline markdown span.
sealed class MarkdownInline {
const MarkdownInline();
}
final class MarkdownPlain extends MarkdownInline {
const MarkdownPlain(this.text);
final String text;
}
final class MarkdownInlineCode extends MarkdownInline {
const MarkdownInlineCode(this.text);
final String text;
}
final class MarkdownStrong extends MarkdownInline {
const MarkdownStrong(this.spans);
final List<MarkdownInline> spans;
}
final class MarkdownEmphasis extends MarkdownInline {
const MarkdownEmphasis(this.spans);
final List<MarkdownInline> spans;
}
final class MarkdownLink extends MarkdownInline {
const MarkdownLink(this.url, this.spans);
final String url;
final List<MarkdownInline> spans;
}
final RegExp _wordChar = RegExp(r'[\p{L}\p{N}]', unicode: true);
final RegExp _whitespace = RegExp(r'\s');
/// Parses inline markup into a flat span tree. Handles `` `code` ``,
/// `**bold**` / `__bold__`, `*italic*` / `_italic_`, `[label](url)` and bare
/// `http(s)://` autolinks; everything else stays plain text. Underscore
/// emphasis requires word boundaries so `snake_case` is never italicised.
List<MarkdownInline> parseInline(String? text) {
final source = text ?? '';
final spans = <MarkdownInline>[];
final buffer = StringBuffer();
var i = 0;
void flush() {
if (buffer.isNotEmpty) {
spans.add(MarkdownPlain(buffer.toString()));
buffer.clear();
}
}
while (i < source.length) {
final c = source[i];
if (c == '`') {
final end = source.indexOf('`', i + 1);
if (end > i) {
flush();
spans.add(MarkdownInlineCode(source.substring(i + 1, end)));
i = end + 1;
} else {
buffer.write(c);
i += 1;
}
} else if (c == '*' || c == '_') {
final doubled = i + 1 < source.length && source[i + 1] == c;
final marker = doubled ? c + c : c;
final boundOk = c != '_' || i == 0 || !_wordChar.hasMatch(source[i - 1]);
final end = boundOk ? source.indexOf(marker, i + marker.length) : -1;
final closes =
end > i + marker.length &&
(c != '_' ||
end + 1 >= source.length ||
!_wordChar.hasMatch(source[end + 1]));
if (closes) {
flush();
final inner = parseInline(source.substring(i + marker.length, end));
spans.add(doubled ? MarkdownStrong(inner) : MarkdownEmphasis(inner));
i = end + marker.length;
} else {
buffer.write(c);
i += 1;
}
} else if (c == '[') {
final close = source.indexOf(']', i + 1);
if (close > i && close + 1 < source.length && source[close + 1] == '(') {
final urlEnd = source.indexOf(')', close + 2);
final url = urlEnd > close
? source.substring(close + 2, urlEnd).trim()
: '';
if (url.isNotEmpty) {
flush();
spans.add(
MarkdownLink(url, parseInline(source.substring(i + 1, close))),
);
i = urlEnd + 1;
} else {
buffer.write(c);
i += 1;
}
} else {
buffer.write(c);
i += 1;
}
} else {
final url = _autolinkAt(source, i);
if (url != null) {
flush();
spans.add(MarkdownLink(url, [MarkdownPlain(url)]));
i += url.length;
} else {
buffer.write(c);
i += 1;
}
}
}
flush();
return spans;
}
/// A bare `http(s)://` URL starting exactly at [index], with trailing
/// punctuation trimmed.
String? _autolinkAt(String text, int index) {
if (!text.startsWith('http://', index) &&
!text.startsWith('https://', index)) {
return null;
}
var end = index;
while (end < text.length &&
!_whitespace.hasMatch(text[end]) &&
!'<>"\''.contains(text[end])) {
end += 1;
}
var url = text.substring(index, end);
while (url.isNotEmpty && '.,;:!?)]}'.contains(url[url.length - 1])) {
url = url.substring(0, url.length - 1);
}
return url.length > 'https://'.length ? url : null;
}
/// Only `http`/`https` link targets may be activated; the transcript is
/// untrusted model output, so `javascript:`/`data:` stay plain labels.
bool isSafeMarkdownLink(String url) =>
RegExp(r'^https?://', caseSensitive: false).hasMatch(url);
/// The label a fenced code block shows: its language, or `code` when unnamed.
String markdownCodeLabel(String language) {
final value = language.trim();
return value.isEmpty ? 'code' : value;
}