merge(app): land native transcript markdown rendering

This commit is contained in:
2026-10-21 23:37:38 +01:00
9 changed files with 2133 additions and 0 deletions
@@ -0,0 +1,451 @@
/// 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;
}
@@ -0,0 +1,353 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
import 'package:flutter/semantics.dart';
import '../../../../ui/adaptive/host.dart';
import '../sessions/chat_adaptive.dart';
import 'chat_markdown.dart';
/// Renders one assistant text part with native text widgets and the host's own
/// theme roles. Link activation is the caller's job: [onOpenLink] receives only
/// an `http`/`https` target. No font family, size, colour or component
/// dimension is overridden; code keeps its exact whitespace and scrolls
/// sideways instead of widening the transcript.
class ChatMarkdownView extends StatefulWidget {
const ChatMarkdownView({super.key, required this.text, this.onOpenLink});
final String text;
final ValueChanged<String>? onOpenLink;
@override
State<ChatMarkdownView> createState() => _ChatMarkdownViewState();
}
/// The transcript's `ChatMessageTextBuilder` seam: a caller that already has the
/// markdown renderer can pass this function as `textBuilder`.
Widget chatMarkdownText(
BuildContext context,
String text, {
ValueChanged<String>? onOpenLink,
}) => ChatMarkdownView(text: text, onOpenLink: onOpenLink);
class _ChatMarkdownViewState extends State<ChatMarkdownView> {
final Map<String, TapGestureRecognizer> _links = {};
@override
void dispose() {
for (final recognizer in _links.values) {
recognizer.dispose();
}
super.dispose();
}
@override
Widget build(BuildContext context) {
final cupertino =
chatControlsStyleOf(context) == ChatControlsStyle.cupertino;
return _selectable(
context,
Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
spacing: 8,
children: [
for (final block in parseMarkdown(widget.text))
_block(context, block, cupertino),
],
),
);
}
/// Selection is provided by the native [SelectionArea]. A Cupertino-only app
/// has no `MaterialLocalizations`, which `SelectionArea` asserts on, so one
/// English default localization scope is added there for its context menu.
Widget _selectable(BuildContext context, Widget child) {
final area = SelectionArea(child: child);
if (!usesCupertinoHost(context)) return area;
return Localizations(
locale: Localizations.maybeLocaleOf(context) ?? const Locale('en'),
delegates: const [
DefaultWidgetsLocalizations.delegate,
DefaultMaterialLocalizations.delegate,
DefaultCupertinoLocalizations.delegate,
],
child: area,
);
}
Widget _block(BuildContext context, MarkdownBlock block, bool cupertino) {
switch (block) {
case MarkdownHeading(level: final level, text: final text):
return Semantics(
container: true,
headingLevel: level,
child: _text(
context,
text,
cupertino: cupertino,
style: _headingStyle(context, level, cupertino),
),
);
case MarkdownParagraph(text: final text):
return _text(context, text, cupertino: cupertino);
case MarkdownRule():
return Divider(color: _dividerColor(context, cupertino));
case MarkdownQuote(lines: final lines):
return DecoratedBox(
decoration: BoxDecoration(
border: BorderDirectional(
start: BorderSide(color: _dividerColor(context, cupertino)),
),
),
child: Padding(
padding: const EdgeInsetsDirectional.only(start: 12),
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
spacing: 4,
children: [
for (final line in lines)
if (line.trim().isNotEmpty)
_text(context, line, cupertino: cupertino),
],
),
),
);
case MarkdownList(ordered: final ordered, items: final items):
return Semantics(
container: true,
explicitChildNodes: true,
role: SemanticsRole.list,
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
spacing: 4,
children: [
for (var index = 0; index < items.length; index += 1)
Semantics(
container: true,
role: SemanticsRole.listItem,
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Padding(
padding: const EdgeInsetsDirectional.only(end: 8),
child: Text(ordered ? '${index + 1}.' : '\u2022'),
),
Expanded(
child: _text(
context,
items[index],
cupertino: cupertino,
),
),
],
),
),
],
),
);
case MarkdownTable(header: final header, rows: final rows):
return SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: Table(
defaultColumnWidth: const IntrinsicColumnWidth(),
border: TableBorder.all(color: _dividerColor(context, cupertino)),
children: [
TableRow(
decoration: BoxDecoration(
color: _headerFill(context, cupertino),
),
children: [
for (final cell in header)
_cell(context, cell, cupertino, header: true),
],
),
for (final row in rows)
TableRow(
children: [
for (final cell in row) _cell(context, cell, cupertino),
],
),
],
),
);
case MarkdownCode(language: final language, code: final code):
final labelStyle = _roleStyle(
context,
cupertino
? CupertinoTheme.of(context).textTheme.textStyle
: Theme.of(context).textTheme.labelSmall,
);
return Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.start,
spacing: 4,
children: [
Text(markdownCodeLabel(language), style: labelStyle),
DecoratedBox(
decoration: BoxDecoration(color: _codeFill(context, cupertino)),
child: Padding(
padding: const EdgeInsets.all(12),
child: SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: Text(code),
),
),
),
],
);
}
}
Widget _cell(
BuildContext context,
String text,
bool cupertino, {
bool header = false,
}) {
final style = header
? _roleStyle(
context,
cupertino
? CupertinoTheme.of(context).textTheme.navTitleTextStyle
: Theme.of(context).textTheme.labelLarge,
)
: null;
return Semantics(
role: header ? SemanticsRole.columnHeader : null,
child: Padding(
padding: const EdgeInsets.all(8),
child: _text(context, text, cupertino: cupertino, style: style),
),
);
}
Widget _text(
BuildContext context,
String text, {
required bool cupertino,
TextStyle? style,
}) {
return Text.rich(
TextSpan(children: _spans(context, parseInline(text), cupertino)),
style: style,
);
}
List<InlineSpan> _spans(
BuildContext context,
List<MarkdownInline> spans,
bool cupertino,
) => [
for (final span in spans)
switch (span) {
MarkdownPlain(text: final text) => TextSpan(text: text),
MarkdownInlineCode(text: final text) => TextSpan(
text: text,
// The same host-theme surface as a fenced block marks the run as
// code without a font, size or literal colour override.
style: TextStyle(backgroundColor: _codeFill(context, cupertino)),
),
MarkdownStrong(spans: final inner) => TextSpan(
style: const TextStyle(fontWeight: FontWeight.bold),
children: _spans(context, inner, cupertino),
),
MarkdownEmphasis(spans: final inner) => TextSpan(
style: const TextStyle(fontStyle: FontStyle.italic),
children: _spans(context, inner, cupertino),
),
MarkdownLink(url: final url, spans: final inner) => _link(
context,
url,
inner,
cupertino,
),
},
];
InlineSpan _link(
BuildContext context,
String url,
List<MarkdownInline> spans,
bool cupertino,
) {
final children = _spans(context, spans, cupertino);
final onOpenLink = widget.onOpenLink;
if (!isSafeMarkdownLink(url) || onOpenLink == null) {
return TextSpan(children: children);
}
final recognizer = _links.putIfAbsent(url, TapGestureRecognizer.new);
recognizer.onTap = () => onOpenLink(url);
return _withRecognizer(
TextSpan(
style: const TextStyle(decoration: TextDecoration.underline),
children: children,
),
recognizer,
);
}
/// A `TextSpan` only dispatches a recognizer when it also owns text, not when
/// it only owns children, so a link's recognizer is copied onto its text
/// leaves. The underline stays on the shared parent.
InlineSpan _withRecognizer(InlineSpan span, TapGestureRecognizer recognizer) {
if (span is! TextSpan) return span;
final children = span.children;
return TextSpan(
text: span.text,
style: span.style,
recognizer: span.text == null ? span.recognizer : recognizer,
children: children == null
? null
: [for (final child in children) _withRecognizer(child, recognizer)],
);
}
/// Heading roles are a non-increasing sequence from the host's own text
/// theme. H3–H6 share one title role, matching the web renderer's flat
/// lower-heading treatment, and no level falls back to a body role, so a
/// heading never reads like a paragraph. Cupertino has two title roles, so
/// H2–H6 share the middle-title role rather than plain body text.
TextStyle? _headingStyle(BuildContext context, int level, bool cupertino) {
final TextStyle? role;
if (cupertino) {
final theme = CupertinoTheme.of(context).textTheme;
role = switch (level) {
1 => theme.navLargeTitleTextStyle,
_ => theme.navTitleTextStyle,
};
} else {
final text = Theme.of(context).textTheme;
role = switch (level) {
1 => text.headlineSmall,
2 => text.titleLarge,
_ => text.titleMedium,
};
}
return _roleStyle(context, role);
}
/// Merges a host theme role into the ambient text style. Cupertino roles are
/// `inherit: false`, which `Text` cannot merge directly.
TextStyle? _roleStyle(BuildContext context, TextStyle? role) => role == null
? null
: DefaultTextStyle.of(
context,
).style.copyWith(inherit: true).merge(role.copyWith(inherit: true));
Color _dividerColor(BuildContext context, bool cupertino) {
if (cupertino) return CupertinoColors.separator.resolveFrom(context);
final theme = Theme.of(context);
return theme.dividerTheme.color ?? theme.dividerColor;
}
Color _codeFill(BuildContext context, bool cupertino) => cupertino
? CupertinoColors.tertiarySystemFill.resolveFrom(context)
: Theme.of(context).colorScheme.surfaceContainerHighest;
Color _headerFill(BuildContext context, bool cupertino) => cupertino
? CupertinoColors.tertiarySystemFill.resolveFrom(context)
: Theme.of(context).colorScheme.surfaceContainerHigh;
}
+242
View File
@@ -0,0 +1,242 @@
# C2 markdown — native transcript markdown
Implements the C2 markdown slice: a pure Dart port of `web/src/markdown.js` and
one native block renderer, with a caller seam for assistant text parts and safe
link activation. No chat screen, composer, network, shell, pubspec, server or
legacy client file changed.
## Behavior
- The parser is a faithful port of the current web subset: paragraphs, `#`–`######`
headings, fenced code (` ``` `/`~~~`, language label else `code`), block
quotes, bullet and ordered lists, `|` tables with a `---` delimiter row,
thematic rules, inline code, `**bold**` / `__bold__`, `*italic*` /
`_italic_` (underscore emphasis only at word boundaries, so `snake_case_name`
stays plain), `[label](url)` links and bare `http(s)://` autolinks.
- HTML entities are decoded in one left-to-right pass (`&amp;lt;` → `&lt;`).
Unknown or malformed references stay exactly as written. A numeric reference
too large for an `int` (19+ decimal or 17+ hex digits) and a value beyond
`0x10FFFF` are both kept literally with `int.tryParse`, so no entity can throw
during a build.
- Constructs outside the subset are retained as text, never dropped: HTML is
literal, reference links and strikethrough stay visible, and a link with an
empty target stays literal. Indented nested list items are retained as flat
items because the web parser strips their indentation; that is the current
reference behavior, not a nested structure.
- Only `http`/`https` targets are safe. `javascript:`, `data:`, `ftp:` and
relative targets render as their label. The parser exposes
`isSafeMarkdownLink`; the renderer attaches a tap recognizer only to safe
links and only when the caller supplies `onOpenLink`. Without that callback a
safe link renders as its label with no false affordance.
- `chatMarkdownText(BuildContext, String, {onOpenLink})` is the
`ChatMessageTextBuilder` seam already present on `ChatMessageView`; a test
passes `chatMarkdownText` directly as `textBuilder`.
- Rendering uses native `Text.rich` blocks inside the native `SelectionArea`,
with host theme roles only. Headings use a non-increasing host sequence:
Material `headlineSmall`/`titleLarge`/`titleMedium` for H1/H2/H3–H6, or
Cupertino `navLargeTitleTextStyle`/`navTitleTextStyle` for H1/H2–H6. No level
falls back to a body role, and H3–H6 share one title role, matching the web
renderer's flat lower-heading treatment. Each heading is its own semantics
node with `headingLevel` 1–6, so assistive technology gets the real level.
Bold and italic are the semantic inline emphasis the subset requires; no font
family, size, colour or component dimension is overridden. Links are
underlined only when they are tappable. Inline code carries the same host
theme fill as a fenced block (`surfaceContainerHighest` /
`tertiarySystemFill`) with no font, size or literal colour override. Code
blocks show their language label (or `code`), keep verbatim whitespace and
scroll horizontally instead of widening the transcript. Tables scroll
horizontally, use the theme divider colour, give the header row a host
surface fill, and expose `columnHeader` roles; lists expose `list`/`listItem`
roles.
- A link recognizer is placed on the link's text leaves because a `TextSpan`
only dispatches a recognizer when it owns text, not when it only owns
children. The underline stays on the shared parent. A real tap test exercises
both hosts.
- `SelectionArea` asserts on `MaterialLocalizations`. Material hosts already
provide it; a bare `CupertinoApp` gets one nested `Localizations` scope with
the default Widgets/Material/Cupertino delegates so native selection and its
toolbar also work there. The app's own locale delegates are unchanged.
- Lists use native text rows with `•` / `1.` markers; quotes use a theme divider
rule and native padding; rules use `Divider`. No custom painters, fixed row or
button dimensions, bespoke palette or CSS token port.
## Files
| Path | Lines | Role |
| --- | ---: | --- |
| `lib/features/chat/ui/transcript/chat_markdown.dart` | 451 | Pure entities/blocks/inline parser and models |
| `lib/features/chat/ui/transcript/chat_markdown_view.dart` | 353 | Native Material/Cupertino block renderer + seam |
| `test/features/chat/ui/transcript/chat_markdown_test.dart` | 214 | 20 parser/entity/safety tests |
| `test/features/chat/ui/transcript/chat_markdown_view_test.dart` | 209 | 5 Material/Cupertino/seam/tap/overflow tests |
| `test/features/chat/ui/transcript/chat_markdown_presentation_test.dart` | 210 | 5 heading, inline-code, table-header and semantics tests |
| `test/features/chat/ui/transcript/chat_markdown_test_support.dart` | 107 | Shared dark-host fixture and span helpers |
| `tool/chat_markdown_probe.dart` | 63 | Material/Cupertino dark fixture, all six heading levels |
| `tool/chat_markdown_probe.mjs` | 284 | Reproducible Chrome + OCR/semantics probe |
| `notes/C2-markdown.md` | — | This note |
Both production files exceed the 250-line aim (parser 451, renderer 353). The
parser is one cohesive pure port with typed block/inline model declarations and
the complete helper set; the task ownership allowed `chat_markdown.dart` plus
one block-widget file, so I did not split it into arbitrary fragments. The
renderer's extra size is the native selection wrapper, link-recognizer handling
and the host role/semantics mapping. Test files were split by responsibility so
each stays under the aim. The repository already contains 300-line controller
files.
## Review fixes (visit 2)
The review found one must-fix defect and ten nonblocking advisories.
- **Must-fix, fixed:** `_numericReference` used `int.parse`, which throws
`FormatException` on a reference overflowing a 64-bit int, so a message with
`&#99999999999999999999;` or `&#xFFFFFFFFFFFFFFFFFFFFFFFF;` failed
`ChatMarkdownView.build` on the VM. It now uses `int.tryParse` and keeps the
existing `1..0x10FFFF` guard, so an overflow takes the same "keep the literal"
path as the web reference. Both reference-format regexes are hoisted so they
are compiled once.
- **Regression coverage, added:** parser tests for the two overflowing forms
(literal retained, `parseMarkdown` does not throw) and for values beyond the
Unicode range plus long leading-zero forms that must still decode. A widget
test pumps a message containing both overflowing references, asserts no
exception and that the text is shown literally. The parser test fails against
the previous `int.parse` implementation and passes now (negative control run).
- **Advisory, applied:** `_autolinkAt` reuses a hoisted `RegExp(r'\s')` instead
of compiling one per character, and `_selectable` now calls
`usesCupertinoHost` from `lib/ui/adaptive/host.dart` instead of repeating the
`Localizations.of<MaterialLocalizations>` test.
- **Advisories left as designed/for follow-up:** no syntax highlighting or
parse caching was added (not required by this item and outside a review fix);
`_links` recognizer retention and light-mode/link-activation browser capture
remain follow-ups for the transcript integration and UI review. The
inline-code visual distinction and list/link semantics called out later by
the UI review were addressed in visit 3 (below).
## UI review fixes (visit 3)
The UI review found two must-fix rendered defects and six nonblocking notes.
- **M1, fixed:** the six heading levels were an inverted/collapsed hierarchy
(`titleSmall` 14 for H4, then `bodyLarge` 16 for H5, `bodyMedium` 14 for H6);
Cupertino H3–H6 were plain `textStyle`. Material now uses
`headlineSmall`/`titleLarge`/`titleMedium` for H1/H2/H3–H6 and Cupertino uses
`navLargeTitleTextStyle`/`navTitleTextStyle` for H1/H2–H6. The sequence is
non-increasing, no heading uses a body role, and H3–H6 are flat, matching the
web renderer's single `.md-heading` size. Tests assert all six levels on both
hosts.
- **M2, fixed:** inline code was rendered exactly like plain prose. It now uses
the same host theme fill as a fenced block (`surfaceContainerHighest` /
`CupertinoColors.tertiarySystemFill`) with no font family, size or literal
colour change. The renderer test asserts the inline-code span has that
background while the neighbouring plain span has none, on both hosts.
- **Nonblocking, fixed:** the Cupertino table header was identical to body rows
and headings/tables had imprecise accessibility roles. The header row now
carries a host surface fill (`surfaceContainerHigh` /
`tertiarySystemFill`) and a bold Cupertino title role; headings expose
`Semantics(headingLevel: level, container: true)`; table header cells expose
`SemanticsRole.columnHeader` instead of a generic heading flag; lists expose
`SemanticsRole.list`/`listItem`. A widget semantics test and the real-browser
probe both verify levels 1–6, list/listitem and columnheader.
- **Nonblocking, left as designed:** Cupertino has no neutral small-label role
(`tabLabelTextStyle` is a 10 px tab-bar style that rendered the `dart` label
too small and failed OCR), so the code label keeps `textStyle` there. No
monospace, syntax highlighting, parse caching, scrollbar affordance or link
accent colour was added; those remain product/integration decisions.
- **Fixture:** `tool/chat_markdown_probe.dart` now carries all six heading
levels, and the probe asserts AX heading levels 1–6 plus list/listitem and
columnheader roles instead of only checking prose OCR. The official captures
were regenerated after the fix.
- **Negative control, run:** with the previous heading mapping and plain inline
code temporarily restored, three new presentation tests failed (Material H3
expected 16, actual 14; Cupertino heading weight expected w600, actual null;
inline-code background expected a fill, actual null). Restoring the fixed
renderer (SHA-1 `9991d66ee176298c420eb0b0a0b4cd00cee67cad`) makes all five
pass again.
## Checks (actual)
- Visit 3 (`UI review fixes`): `flutter test test/features/chat/ui/transcript`:
**43 tests passed** (20 parser, 5 renderer, 5 presentation, 13 existing);
`flutter test test/features/chat`: **104 tests passed**; `flutter analyze`:
**No issues found**; `dart format --output=none --set-exit-if-changed` on the
seven Dart files: **0 changed**; `node --check tool/chat_markdown_probe.mjs`:
passed. `flutter build web` for the probe (Material and Cupertino) and for
`lib/main.dart`: all built. Both browser probes passed OCR and the new AX
assertions (`h1`–`h6` levels, `list`/`listitem`, `columnheader`).
- Visit 2 (`review fixes`): `flutter test test/features/chat/ui/transcript`:
**38 tests passed** (20 parser, 5 renderer, 13 existing);
`flutter test test/features/chat`: **99 tests passed**; `flutter analyze`:
**No issues found**; `dart format --set-exit-if-changed` on the four Dart
candidate files: **0 changed**. The 233-input entity differential against
`web/src/markdown.js` (`decodeHtmlEntities` only, including 1–30 digit
decimal/hex forms, leading zeros, surrogates, range edges and malformed
bodies) reported **0 divergences**.
- `flutter test test/features/chat/ui/transcript`: **35 tests passed** (18 new
parser tests, 4 new renderer tests, 13 existing transcript tests) on visit 1.
- `flutter test test/features/chat`: **96 tests passed** on visit 1.
- `flutter analyze`: **No issues found**.
- `node --test test/markdown.test.mjs` in `web/`: **0 failures**, confirming the
reference parser expectations the port follows.
- `node --check tool/chat_markdown_probe.mjs`: passed.
- `flutter build web` for `tool/chat_markdown_probe.dart` with both
`CHAT_MARKDOWN_PROBE_STYLE=material` and `cupertino`: both built on visit 1 and
again after the fix (17.1s / 20.6s).
- `flutter build web` for the normal `lib/main.dart`: built on both visits.
- Browser probes, each against its own loopback OS-assigned port with dark
appearance, 390x844 at DPR 2 and real Chrome: both Material and Cupertino
passed. OCR asserted headings, paragraph, bold/italic/inline text,
`snake_case_name`, quote lines, both list kinds, table header/cells, the `dart`
code label and code text, `Open docs`, the inert `unsafe` label, the bare
autolink, literal `<b>` markup and `~~strikethrough~~`. It also asserted that
raw `**`, ` ``` `, `| ---` and `javascript:alert` never appears; the semantics
tree exposed the `dart`, `•` and `1.` labels. The visit-2 captures were
byte-identical to visit 1, so that fix did not change rendering; visit 3
intentionally changes the pixels and its new hashes are below.
- Widget tests are the functional proof for link safety: `ok` has a
`TapGestureRecognizer` that invokes the supplied callback, `bad`
(`javascript:alert`) has no recognizer and no underline, and the autolink is
tappable. A real pointer tap on the link invokes the callback on both the
Material and Cupertino hosts. The tests also inspect the exact code string
with its whitespace inside a horizontal scroll, the table row/cell structure,
the Material/Cupertino heading roles, the absence of raw `#`/`**` through the
seam, and run at 2.0x text on 390x844 in dark hosts without an exception.
## Browser evidence
Captures and evidence in
`/Users/alan/.local/share/pipelines/data/artifacts/83/public/c2-markdown/`:
- `material-markdown.png` — Material dark host, all blocks.
- `cupertino-markdown.png` — Cupertino dark host, all blocks.
- `material-evidence.json`, `cupertino-evidence.json` — origin, capture paths and
checks.
Visit-3 re-capture hashes (SHA-256, after the heading/inline-code fix):
```
94dc02af2b7b8ba8fb464e8d6501cfe58830c040332354261ede3e79231caebb material-markdown.png
21e2f51c2aec7b8a914b9245a1f2fca126d733632bdd1e99fba40d9da8a71c80 cupertino-markdown.png
```
Both captures show the six-level hierarchy (`Heading one` largest, `Heading
two` smaller, `Heading three`–`Heading six` on one title role), the inline-code
fill, and the filled table header. The probe's evidence JSONs record the loopback
origin, checks and AX levels/roles.
The captures are rendering evidence. Link activation is covered by the real-tap
widget test rather than the fixture because the production seam intentionally
takes the caller's `onOpenLink`; no URL-opening dependency was added.
## Not done / integration notes
- The chat transcript and session screen are not wired to `chatMarkdownText`;
that is the next integration step and would also supply the host's link
opener. Assistant text without a builder still renders verbatim.
- No `PARITY.md` edit (not in this lane's ownership); manager should update the
Chat message surfaces row when the screen wiring lands.
- Inline code is parsed and rendered without backticks and carries the host
code fill as its only distinction; no monospace family, size or literal colour
was introduced.
- Browser evidence is web only. Android/iOS/macOS were not built, run or
installed and remain unverified.
- No commit, merge, push, deployment or canonical URL change. All seven new files
are the uncommitted candidate.
@@ -0,0 +1,210 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter/semantics.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/ui/transcript/chat_markdown_view.dart';
import 'chat_markdown_test_support.dart';
void main() {
testWidgets('Material headings keep a non-increasing hierarchy', (
tester,
) async {
await phoneViewport(tester);
await tester.pumpWidget(
markdownHost(const ChatMarkdownView(text: markdownHeadings)),
);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final context = tester.element(find.byType(ChatMarkdownView));
final text = Theme.of(context).textTheme;
final roles = [
text.headlineSmall,
text.titleLarge,
text.titleMedium,
text.titleMedium,
text.titleMedium,
text.titleMedium,
];
var previousSize = double.infinity;
for (var level = 1; level <= 6; level += 1) {
final label = markdownHeadingLabels[level - 1];
final heading = textWidget(tester, label);
final role = roles[level - 1]!;
expect(heading.style?.fontSize, role.fontSize, reason: label);
expect(heading.style?.fontWeight, role.fontWeight, reason: label);
expect(
heading.style!.fontSize!,
lessThanOrEqualTo(previousSize),
reason: label,
);
previousSize = heading.style!.fontSize!;
final semantics = tester
.widgetList<Semantics>(
find.ancestor(
of: find.text(label),
matching: find.byType(Semantics),
),
)
.singleWhere((widget) => widget.properties.headingLevel != null);
expect(semantics.properties.headingLevel, level, reason: label);
}
final paragraph = textWidget(tester, 'A plain paragraph.');
expect(paragraph.style, isNull);
expect(roles.last!.fontWeight, isNot(text.bodyMedium?.fontWeight));
});
testWidgets('Cupertino headings stay on title roles above body text', (
tester,
) async {
await phoneViewport(tester);
await tester.pumpWidget(
markdownHost(
const ChatMarkdownView(text: markdownHeadings),
cupertino: true,
),
);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final context = tester.element(find.byType(ChatMarkdownView));
final theme = CupertinoTheme.of(context).textTheme;
final roles = [
theme.navLargeTitleTextStyle,
theme.navTitleTextStyle,
theme.navTitleTextStyle,
theme.navTitleTextStyle,
theme.navTitleTextStyle,
theme.navTitleTextStyle,
];
var previousSize = double.infinity;
for (var level = 1; level <= 6; level += 1) {
final label = markdownHeadingLabels[level - 1];
final heading = textWidget(tester, label);
final role = roles[level - 1];
expect(heading.style?.fontSize, role.fontSize, reason: label);
expect(heading.style?.fontWeight, role.fontWeight, reason: label);
expect(
heading.style!.fontSize!,
lessThanOrEqualTo(previousSize),
reason: label,
);
previousSize = heading.style!.fontSize!;
expect(
heading.style!.fontWeight,
isNot(theme.textStyle.fontWeight),
reason: label,
);
}
});
testWidgets('inline code carries the host code surface on both hosts', (
tester,
) async {
await phoneViewport(tester);
for (final cupertino in [false, true]) {
await tester.pumpWidget(
markdownHost(
const ChatMarkdownView(
text: 'Use `inline_code()` in the middle of this sentence.',
),
cupertino: cupertino,
),
);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final context = tester.element(find.byType(ChatMarkdownView));
final fill = cupertino
? CupertinoColors.tertiarySystemFill.resolveFrom(context)
: Theme.of(context).colorScheme.surfaceContainerHighest;
final spans = spansOf(tester, 'Use');
final code = spans.firstWhere((span) => span.text == 'inline_code()');
final plain = spans.firstWhere(
(span) => span.text == ' in the middle of this sentence.',
);
expect(code.style?.backgroundColor, fill, reason: '$cupertino');
expect(plain.style?.backgroundColor, isNull, reason: '$cupertino');
expect(code.style?.fontSize, isNull, reason: '$cupertino');
expect(code.style?.fontFamily, isNull, reason: '$cupertino');
}
});
testWidgets('a table header carries its own surface and column role', (
tester,
) async {
await phoneViewport(tester);
for (final cupertino in [false, true]) {
await tester.pumpWidget(
markdownHost(
const ChatMarkdownView(
text: '| Name | Value |\n| --- | --- |\n| a | 1 |',
),
cupertino: cupertino,
),
);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final context = tester.element(find.byType(ChatMarkdownView));
final fill = cupertino
? CupertinoColors.tertiarySystemFill.resolveFrom(context)
: Theme.of(context).colorScheme.surfaceContainerHigh;
final table = tester.widget<Table>(find.byType(Table));
final decoration = table.children.first.decoration;
expect(decoration, isA<BoxDecoration>(), reason: '$cupertino');
expect((decoration! as BoxDecoration).color, fill, reason: '$cupertino');
final headers = tester
.widgetList<Semantics>(find.byType(Semantics))
.where(
(widget) => widget.properties.role == SemanticsRole.columnHeader,
);
expect(headers, hasLength(2), reason: '$cupertino');
expect(
tester
.widgetList<Semantics>(find.byType(Semantics))
.where((widget) => widget.properties.header == true),
isEmpty,
reason: '$cupertino',
);
}
});
testWidgets('semantics expose heading levels, lists and column headers', (
tester,
) async {
final handle = tester.ensureSemantics();
await phoneViewport(tester);
await tester.pumpWidget(
markdownHost(const ChatMarkdownView(text: markdownSample)),
);
await tester.pumpAndSettle();
final heading = tester.getSemantics(find.text('Second'));
expect(heading.getSemanticsData().headingLevel, 2);
final item = tester.getSemantics(
find
.byWidgetPredicate(
(widget) =>
widget is Semantics &&
widget.properties.role == SemanticsRole.listItem,
)
.first,
);
expect(item.getSemanticsData().role, SemanticsRole.listItem);
expect(item.parent?.getSemanticsData().role, SemanticsRole.list);
final header = tester.getSemantics(
find
.byWidgetPredicate(
(widget) =>
widget is Semantics &&
widget.properties.role == SemanticsRole.columnHeader,
)
.first,
);
expect(header.getSemanticsData().role, SemanticsRole.columnHeader);
expect(tester.takeException(), isNull);
handle.dispose();
});
}
@@ -0,0 +1,214 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/ui/transcript/chat_markdown.dart';
String _visible(List<MarkdownInline> spans) => spans
.map(
(span) => switch (span) {
MarkdownPlain(text: final text) => text,
MarkdownInlineCode(text: final text) => text,
MarkdownStrong(spans: final inner) => _visible(inner),
MarkdownEmphasis(spans: final inner) => _visible(inner),
MarkdownLink(spans: final inner) => _visible(inner),
},
)
.join();
void main() {
group('entities', () {
test('decodes named and numeric references exactly once', () {
expect(
decodeHtmlEntities('&amp;lt; &quot;x&quot; &#39; &#x27;'),
'&lt; "x" \' \'',
);
expect(decodeHtmlEntities('&amp;amp;'), '&amp;');
expect(decodeHtmlEntities('&nbsp;&hellip;&mdash;'), '\u00a0\u2026\u2014');
});
test('keeps unknown and malformed references as written', () {
expect(
decodeHtmlEntities('&bogus; &amp &#xZZ; &#0;'),
'&bogus; &amp &#xZZ; &#0;',
);
});
test('an overflowing numeric reference stays literal and never throws', () {
const overflow = '&#99999999999999999999; &#xFFFFFFFFFFFFFFFFFFFFFFFF;';
expect(decodeHtmlEntities(overflow), overflow);
final blocks = parseMarkdown(overflow);
expect((blocks.single as MarkdownParagraph).text, overflow);
});
test('numeric references beyond the Unicode range stay literal', () {
expect(
decodeHtmlEntities('&#x110000; &#1114112;'),
'&#x110000; &#1114112;',
);
expect(decodeHtmlEntities('&#00000000065; &#x000041;'), 'A A');
});
});
group('blocks', () {
test('paragraphs join wrapped lines and keep trailing text', () {
final blocks = parseMarkdown('one line\nsecond line\n\nnext');
expect(blocks, hasLength(2));
expect((blocks[0] as MarkdownParagraph).text, 'one line second line');
expect((blocks[1] as MarkdownParagraph).text, 'next');
});
test('headings cover levels one to six and closing hashes', () {
final blocks = parseMarkdown(
'# one\n## two\n### three####\n#### four\n##### five\n###### six\n'
'####### seven\n#nospace',
);
final headings = blocks.whereType<MarkdownHeading>().toList();
expect(
[for (final heading in headings) heading.level],
[1, 2, 3, 4, 5, 6],
);
expect(
[for (final heading in headings) heading.text],
['one', 'two', 'three', 'four', 'five', 'six'],
);
expect(
(blocks[headings.length] as MarkdownParagraph).text,
'####### seven #nospace',
);
});
test('fenced code keeps verbatim whitespace and the language', () {
final blocks = parseMarkdown(
'```dart\n final x = 1;\n\n print(x);\n```\nafter',
);
final code = blocks.first as MarkdownCode;
expect(code.language, 'dart');
expect(code.code, ' final x = 1;\n\n print(x);');
expect(markdownCodeLabel(code.language), 'dart');
expect((blocks.last as MarkdownParagraph).text, 'after');
});
test('an unnamed fence is labelled code and unclosed code is kept', () {
final blocks = parseMarkdown('~~~\nbody');
final code = blocks.single as MarkdownCode;
expect(code.language, '');
expect(code.code, 'body');
expect(markdownCodeLabel(code.language), 'code');
});
test('quotes, bullet lists and ordered lists keep their content', () {
final blocks = parseMarkdown(
'> quoted **line**\n> second\n\n- one\n* two\n\n1. first\n2) second',
);
expect(blocks, hasLength(3));
expect((blocks[0] as MarkdownQuote).lines, ['quoted **line**', 'second']);
final bullets = blocks[1] as MarkdownList;
expect(bullets.ordered, isFalse);
expect(bullets.items, ['one', 'two']);
final ordered = blocks[2] as MarkdownList;
expect(ordered.ordered, isTrue);
expect(ordered.items, ['first', 'second']);
});
test('thematic rules need three identical markers', () {
final blocks = parseMarkdown('---\n***\n___\n- - -');
expect(blocks.whereType<MarkdownRule>(), hasLength(3));
expect(blocks.last, isA<MarkdownList>());
});
test('a table requires a delimiter row and fits rows to the header', () {
final blocks = parseMarkdown(
'| a | b |\n| --- | :---: |\n| 1 | 2 |\n| 3 |',
);
final table = blocks.single as MarkdownTable;
expect(table.header, ['a', 'b']);
expect(table.rows, [
['1', '2'],
['3', ''],
]);
final plain = parseMarkdown('a | b\nnope');
expect(plain.single, isA<MarkdownParagraph>());
expect((plain.single as MarkdownParagraph).text, 'a | b nope');
});
});
group('inline', () {
test('code, bold and italic spans keep plain text', () {
final spans = parseInline('a `x = 1` **bold** *italic* __also__');
expect(_visible(spans), 'a x = 1 bold italic also');
expect(spans.whereType<MarkdownInlineCode>().single.text, 'x = 1');
expect(spans.whereType<MarkdownStrong>(), hasLength(2));
expect(spans.whereType<MarkdownEmphasis>(), hasLength(1));
});
test('underscore emphasis never splits snake_case', () {
final spans = parseInline('snake_case_name and _real italic_ and _x');
expect(_visible(spans), 'snake_case_name and real italic and _x');
expect(spans.whereType<MarkdownEmphasis>().single, isNotNull);
expect(
spans.whereType<MarkdownPlain>().first.text,
'snake_case_name and ',
);
expect(spans.whereType<MarkdownPlain>().last.text, ' and _x');
});
test('unclosed markers stay plain text', () {
expect(_visible(parseInline('**open and `tick')), '**open and `tick');
});
test('links and bare http(s) URLs become link spans', () {
final spans = parseInline(
'See [docs](https://example.com/a) or https://example.com/b.',
);
final links = spans.whereType<MarkdownLink>().toList();
expect(links, hasLength(2));
expect(links[0].url, 'https://example.com/a');
expect(_visible(links[0].spans), 'docs');
expect(links[1].url, 'https://example.com/b');
expect(_visible(spans), 'See docs or https://example.com/b.');
});
test('only http and https targets are safe to activate', () {
expect(isSafeMarkdownLink('https://example.com'), isTrue);
expect(isSafeMarkdownLink('HTTP://example.com'), isTrue);
expect(isSafeMarkdownLink('http://example.com'), isTrue);
for (final unsafe in [
'javascript:alert(1)',
'data:text/html,<h1>x</h1>',
'ftp://example.com',
'//example.com',
'/artifacts/a.txt',
]) {
expect(isSafeMarkdownLink(unsafe), isFalse, reason: unsafe);
}
});
});
group('constructs outside the subset', () {
test('HTML stays literal text and is never interpreted', () {
const source = '<b>bold?</b> <script>alert(1)</script>';
final spans = parseInline(source);
expect(spans.whereType<MarkdownPlain>().single.text, source);
expect(_visible(spans), source);
});
test('strikethrough and reference links stay visible as text', () {
const source = '~~old~~ and [label][ref] and [missing]';
final blocks = parseMarkdown(source);
expect((blocks.single as MarkdownParagraph).text, source);
expect(_visible(parseInline(source)), source);
});
test('an indented nested item is retained rather than dropped', () {
final blocks = parseMarkdown('- outer\n - inner\n continuation');
final list = blocks.first as MarkdownList;
expect(list.items, ['outer', 'inner']);
expect((blocks.last as MarkdownParagraph).text, 'continuation');
});
test('a link with an empty target stays literal', () {
const source = '[label]()';
expect(_visible(parseInline(source)), source);
expect(parseInline(source).whereType<MarkdownLink>(), isEmpty);
});
});
}
@@ -0,0 +1,107 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
/// One representative message used by the markdown renderer tests.
const markdownSample = '''
# Title
Paragraph with **bold**, *italic*, `inline` and snake_case_name.
## Second
> quote one
> quote two
- bullet one
- bullet two
1. first
2. second
| Name | Value |
| --- | --- |
| a | 1 |
```dart
const answer = 42;
keep spaces
```
---
[ok](https://example.com/ok) [**bold link**](https://example.com/bold) [bad](javascript:alert) https://example.com/auto
<b>literal</b> ~~gone~~
''';
/// All six heading levels plus a body paragraph.
const markdownHeadingLabels = [
'Level one',
'Level two',
'Level three',
'Level four',
'Level five',
'Level six',
];
const markdownHeadings = '''
# Level one
## Level two
### Level three
#### Level four
##### Level five
###### Level six
A plain paragraph.
''';
/// Mounts a markdown renderer in a dark host at 2x text scaling.
Widget markdownHost(Widget child, {bool cupertino = false}) {
Widget builder(BuildContext context, Widget? body) => MediaQuery(
data: MediaQuery.of(
context,
).copyWith(textScaler: const TextScaler.linear(2)),
child: body!,
);
if (cupertino) {
return CupertinoApp(
theme: const CupertinoThemeData(brightness: Brightness.dark),
builder: builder,
home: CupertinoPageScaffold(
child: SafeArea(child: SingleChildScrollView(child: child)),
),
);
}
return MaterialApp(
theme: ThemeData(
brightness: Brightness.dark,
platform: TargetPlatform.android,
),
builder: builder,
home: Scaffold(
body: SafeArea(child: SingleChildScrollView(child: child)),
),
);
}
Future<void> phoneViewport(WidgetTester tester) async {
tester.view.physicalSize = const Size(390, 844);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.resetPhysicalSize);
addTearDown(tester.view.resetDevicePixelRatio);
}
String textOf(Text widget) =>
widget.data ?? widget.textSpan?.toPlainText() ?? '';
String allText(WidgetTester tester) =>
tester.widgetList<Text>(find.byType(Text)).map(textOf).join('\n');
Text textWidget(WidgetTester tester, String text) => tester
.widgetList<Text>(find.byType(Text))
.firstWhere((widget) => textOf(widget) == text);
Iterable<TextSpan> _spansBelow(InlineSpan root) sync* {
if (root is! TextSpan) return;
yield root;
for (final child in root.children ?? const <InlineSpan>[]) {
yield* _spansBelow(child);
}
}
List<TextSpan> spansOf(WidgetTester tester, String text) {
final widget = tester
.widgetList<Text>(find.byType(Text))
.firstWhere((widget) => textOf(widget).contains(text));
return _spansBelow(widget.textSpan!).toList();
}
@@ -0,0 +1,209 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/domain/chat_transcript.dart';
import 'package:pipelines_app/features/chat/ui/transcript/chat_markdown_view.dart';
import 'package:pipelines_app/features/chat/ui/transcript/chat_message_view.dart';
import 'chat_markdown_test_support.dart';
void main() {
testWidgets('Material renders every block with host theme roles', (
tester,
) async {
await phoneViewport(tester);
final opened = <String>[];
await tester.pumpWidget(
markdownHost(
ChatMarkdownView(text: markdownSample, onOpenLink: opened.add),
),
);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final context = tester.element(find.byType(ChatMarkdownView));
final theme = Theme.of(context);
final heading = tester
.widgetList<Text>(find.byType(Text))
.firstWhere((widget) => textOf(widget) == 'Title');
expect(heading.style?.fontSize, theme.textTheme.headlineSmall?.fontSize);
final all = allText(tester);
for (final text in [
'Title',
'Second',
'quote one',
'quote two',
'bullet one',
'bullet two',
'first',
'second',
'const answer = 42;\n keep spaces',
'literal',
'~~gone~~',
]) {
expect(all, contains(text));
}
final paragraph = spansOf(tester, 'Paragraph with');
final bold = paragraph.firstWhere(
(span) => span.children != null && span.toPlainText() == 'bold',
);
final italic = paragraph.firstWhere(
(span) => span.children != null && span.toPlainText() == 'italic',
);
expect(bold.style?.fontWeight, FontWeight.bold);
expect(italic.style?.fontStyle, FontStyle.italic);
final inlineCode = paragraph.firstWhere(
(span) => span.toPlainText() == 'inline',
);
expect(
inlineCode.style?.backgroundColor,
theme.colorScheme.surfaceContainerHighest,
);
final plain = paragraph.firstWhere(
(span) => span.toPlainText() == ' and snake_case_name.',
);
expect(plain.style?.fontStyle, isNull);
expect(find.text('\u2022'), findsNWidgets(2));
expect(find.text('1.'), findsOneWidget);
expect(find.text('2.'), findsOneWidget);
expect(find.text('dart'), findsOneWidget);
final table = tester.widget<Table>(find.byType(Table));
expect(table.children, hasLength(2));
expect(table.children.first.children, hasLength(2));
expect(all, contains('a'));
final code = find.byWidgetPredicate(
(widget) =>
widget is Text &&
widget.data == 'const answer = 42;\n keep spaces',
);
expect(code, findsOneWidget);
final scroll = find.ancestor(
of: code,
matching: find.byWidgetPredicate(
(widget) =>
widget is SingleChildScrollView &&
widget.scrollDirection == Axis.horizontal,
),
);
expect(scroll, findsOneWidget);
expect(find.byType(Divider), findsOneWidget);
final links = spansOf(tester, 'https://example.com/auto');
final ok = links.firstWhere((span) => span.text == 'ok');
final bad = links.firstWhere((span) => span.text == 'bad');
final auto = links.firstWhere(
(span) => span.text == 'https://example.com/auto',
);
expect(ok.recognizer, isA<TapGestureRecognizer>());
expect(bad.recognizer, isNull);
expect(bad.style?.decoration, isNull);
expect(auto.recognizer, isA<TapGestureRecognizer>());
final boldLink = links.firstWhere((span) => span.text == 'bold link');
expect(boldLink.recognizer, isA<TapGestureRecognizer>());
expect(
links.any(
(span) =>
span.children != null &&
span.toPlainText() == 'bold link' &&
span.style?.fontWeight == FontWeight.bold,
),
isTrue,
);
(ok.recognizer! as TapGestureRecognizer).onTap!();
expect(opened, ['https://example.com/ok']);
});
testWidgets('Cupertino renders the same blocks in a dark host', (
tester,
) async {
await phoneViewport(tester);
await tester.pumpWidget(
markdownHost(ChatMarkdownView(text: markdownSample), cupertino: true),
);
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
final context = tester.element(find.byType(ChatMarkdownView));
final heading = tester
.widgetList<Text>(find.byType(Text))
.firstWhere((widget) => textOf(widget) == 'Title');
expect(
heading.style?.fontSize,
CupertinoTheme.of(context).textTheme.navLargeTitleTextStyle.fontSize,
);
final all = allText(tester);
expect(all, contains('quote one'));
expect(all, contains('const answer = 42;'));
expect(find.text('code'), findsNothing);
expect(find.text('dart'), findsOneWidget);
});
testWidgets('a safe link responds to a real tap on both hosts', (
tester,
) async {
await phoneViewport(tester);
final opened = <String>[];
for (final cupertino in [false, true]) {
opened.clear();
await tester.pumpWidget(
markdownHost(
ChatMarkdownView(
text: '[ok](https://example.com/ok)',
onOpenLink: opened.add,
),
cupertino: cupertino,
),
);
await tester.pumpAndSettle();
await tester.tapAt(
tester.getTopLeft(find.byType(Text)) + const Offset(6, 6),
);
await tester.pump();
expect(opened, ['https://example.com/ok'], reason: '$cupertino');
}
});
testWidgets('an overflowing entity renders literally instead of failing', (
tester,
) async {
await phoneViewport(tester);
const text =
'value &#99999999999999999999; and &#xFFFFFFFFFFFFFFFFFFFFFFFF; stay';
await tester.pumpWidget(markdownHost(ChatMarkdownView(text: text)));
await tester.pumpAndSettle();
expect(tester.takeException(), isNull);
expect(allText(tester), contains(text));
});
testWidgets('the text builder seam renders assistant markdown', (
tester,
) async {
await phoneViewport(tester);
final row = transcriptRows([
{
'id': 'a1',
'role': 'assistant',
'parts': [
{'type': 'text', 'text': '# Title\n\nA **bold** answer.'},
],
},
]).single;
await tester.pumpWidget(
markdownHost(ChatMessageView(row: row, textBuilder: chatMarkdownText)),
);
await tester.pumpAndSettle();
expect(find.byType(ChatMarkdownView), findsOneWidget);
final all = allText(tester);
expect(all, contains('Title'));
expect(all, isNot(contains('#')));
expect(all, isNot(contains('**')));
expect(all, contains('bold'));
expect(tester.takeException(), isNull);
});
}
+63
View File
@@ -0,0 +1,63 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:pipelines_app/features/chat/ui/transcript/chat_markdown_view.dart';
const _style = String.fromEnvironment(
'CHAT_MARKDOWN_PROBE_STYLE',
defaultValue: 'material',
);
const _sample = '''
# Heading one
## Heading two
### Heading three
#### Heading four
##### Heading five
###### Heading six
A paragraph with **bold**, *italic*, `inline code`, and snake_case_name staying plain.
> quoted line one
> quoted line two
- bullet one
- bullet two
1. first item
2. second item
| Name | Value |
| --- | --- |
| alpha | 1 |
| beta | 2 |
```dart
const answer = 42;
keep spaces
```
---
[Open docs](https://example.com/docs) and [unsafe](javascript:alert) stay safe.
Bare https://example.com/auto link.
<b>literal html</b> and ~~strikethrough~~ stay text.
''';
/// One assistant markdown sample for the Material and Cupertino dark captures.
void main() {
final content = ListView(
padding: const EdgeInsets.all(16),
children: const [ChatMarkdownView(text: _sample)],
);
if (_style == 'cupertino') {
runApp(
CupertinoApp(
theme: const CupertinoThemeData(brightness: Brightness.dark),
home: CupertinoPageScaffold(child: SafeArea(child: content)),
),
);
return;
}
runApp(
MaterialApp(
theme: ThemeData(
brightness: Brightness.dark,
platform: TargetPlatform.android,
),
home: Scaffold(body: SafeArea(child: content)),
),
);
}
+284
View File
@@ -0,0 +1,284 @@
// Real-browser evidence for the C2 markdown fixture.
//
// Build one host, then run from app/:
// flutter build web -t tool/chat_markdown_probe.dart \
// --dart-define=CHAT_MARKDOWN_PROBE_STYLE=material \
// --output build/probe-chat-markdown-material
// node tool/chat_markdown_probe.mjs --root build/probe-chat-markdown-material \
// --out DIR --style material
//
// The Cupertino host is the same build with CHAT_MARKDOWN_PROBE_STYLE=cupertino.
// Flutter web paints SelectableText on the canvas, so OCR checks the rendered
// prose while the semantics tree checks headings and the dark host.
import { createServer } from 'node:http';
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { spawn, execFile } from 'node:child_process';
import { once } from 'node:events';
import { promisify } from 'node:util';
import { setTimeout as delay } from 'node:timers/promises';
import { extname, join, resolve, sep } from 'node:path';
import { tmpdir } from 'node:os';
const args = new Map();
for (let i = 2; i < process.argv.length; i++) {
const value = process.argv[i];
if (value.startsWith('--')) args.set(value.slice(2), process.argv[++i]);
}
const root = resolve(args.get('root') ?? 'build/probe-chat-markdown-material');
const out = resolve(args.get('out') ?? 'build/chat-markdown-probe');
const style = args.get('style') ?? 'material';
const chromePath =
process.env.CHROME_PATH ??
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
await mkdir(out, { recursive: true });
const mime = {
'.html': 'text/html; charset=utf-8',
'.js': 'text/javascript; charset=utf-8',
'.mjs': 'text/javascript; charset=utf-8',
'.json': 'application/json; charset=utf-8',
'.wasm': 'application/wasm',
'.png': 'image/png',
'.svg': 'image/svg+xml',
'.ico': 'image/x-icon',
'.ttf': 'font/ttf',
'.otf': 'font/otf',
'.woff': 'font/woff',
'.woff2': 'font/woff2',
'.bin': 'application/octet-stream',
};
const server = createServer(async (req, res) => {
try {
const pathname = decodeURIComponent(
new URL(req.url, 'http://localhost').pathname,
);
let filePath = resolve(root, '.' + pathname);
if (filePath !== root && !filePath.startsWith(root + sep)) {
res.writeHead(403).end();
return;
}
if (pathname === '/' || pathname.endsWith('/')) {
filePath = join(filePath, 'index.html');
}
const file = await readFile(filePath);
res
.writeHead(200, {
'content-type': mime[extname(filePath)] ?? 'application/octet-stream',
})
.end(file);
} catch {
res.writeHead(404).end('not found');
}
});
server.listen(0, '127.0.0.1');
await once(server, 'listening');
const origin = `http://127.0.0.1:${server.address().port}`;
const profile = await mkdtemp(join(tmpdir(), 'c2-markdown-chrome-'));
const chrome = spawn(
chromePath,
[
'--headless=new',
'--no-first-run',
'--no-default-browser-check',
'--disable-gpu',
'--remote-debugging-port=0',
`--user-data-dir=${profile}`,
'about:blank',
],
{ stdio: ['ignore', 'ignore', 'pipe'] },
);
let stderr = '';
chrome.stderr.on('data', (data) => {
stderr += data;
});
const waitFor = async (fn, what) => {
for (let i = 0; i < 150; i++) {
const value = await fn();
if (value) return value;
await delay(100);
}
throw new Error(`Timed out waiting for ${what}: ${stderr.slice(-1500)}`);
};
let ws;
const evidence = { origin, style, captures: [], checks: [] };
try {
const endpoint = await waitFor(
() => stderr.match(/DevTools listening on (ws:\/\/[^\s]+)/)?.[1],
'Chrome DevTools',
);
ws = new WebSocket(endpoint);
await once(ws, 'open');
let id = 0;
const pending = new Map();
ws.addEventListener('message', (event) => {
const message = JSON.parse(event.data);
if (message.id && pending.has(message.id)) {
pending.get(message.id)(message);
pending.delete(message.id);
}
});
const send = (method, params = {}, sessionId) =>
new Promise((resolveCall) => {
const callId = ++id;
pending.set(callId, resolveCall);
ws.send(
JSON.stringify({
id: callId,
method,
params,
...(sessionId ? { sessionId } : {}),
}),
);
});
const created = await send('Target.createTarget', { url: 'about:blank' });
const target = created.result.targetId;
const session = (
await send('Target.attachToTarget', { targetId: target, flatten: true })
).result.sessionId;
await send('Page.enable', {}, session);
await send('Runtime.enable', {}, session);
await send(
'Emulation.setDeviceMetricsOverride',
{ width: 390, height: 844, deviceScaleFactor: 2, mobile: true },
session,
);
await send(
'Emulation.setEmulatedMedia',
{ features: [{ name: 'prefers-color-scheme', value: 'dark' }] },
session,
);
const evaluate = async (expression) => {
const response = await send(
'Runtime.evaluate',
{ expression, returnByValue: true, awaitPromise: true },
session,
);
if (response.error) {
throw new Error(`Runtime.evaluate failed: ${JSON.stringify(response)}`);
}
return response.result?.result?.value;
};
await send('Page.navigate', { url: `${origin}/` }, session);
await delay(3500);
const contentType = await evaluate(
"fetch('/').then(r => r.headers.get('content-type'))",
);
if (!String(contentType).toLowerCase().startsWith('text/html')) {
throw new Error(`Root index is not text/html: ${contentType}`);
}
await evaluate("document.querySelector('flt-semantics-placeholder')?.click()");
await delay(1200);
const capture = async (name) => {
const data = (
await send('Page.captureScreenshot', { format: 'png' }, session)
).result.data;
const file = join(out, `${name}.png`);
await writeFile(file, Buffer.from(data, 'base64'));
evidence.captures.push(file);
return file;
};
const ocr = async (path) => {
const { stdout } = await promisify(execFile)('tesseract', [path, 'stdout']);
return stdout.replace(/\s+/g, ' ');
};
const requireOcr = (text, wanted) => {
if (!text.toLowerCase().includes(wanted.toLowerCase())) {
throw new Error(`OCR lacks ${JSON.stringify(wanted)}: ${text.slice(0, 2500)}`);
}
};
const shot = await capture(`${style}-markdown`);
const text = await ocr(shot);
for (const wanted of [
'Heading one',
'Heading two',
'Heading three',
'Heading four',
'Heading five',
'Heading six',
'paragraph with bold',
'italic',
'inline code',
'snake_case_name',
'quoted line one',
'bullet one',
'bullet two',
'first item',
'Name',
'Value',
'alpha',
'beta',
'dart',
'const answer = 42',
'Open docs',
'unsafe',
'example.com/auto',
'literal html',
'strikethrough',
]) {
requireOcr(text, wanted);
}
for (const absent of ['**', '```', '| ---', 'javascript:alert']) {
if (text.includes(absent)) {
throw new Error(`OCR leaked raw marker ${JSON.stringify(absent)}`);
}
}
const nodes = await evaluate(`[...document.querySelectorAll(
'flt-semantics, h1, h2, h3, h4, h5, h6')]
.map(x => ({ label: x.getAttribute('aria-label'), role: x.getAttribute('role'),
level: x.getAttribute('aria-level') ??
(/^H[1-6]$/.test(x.tagName) ? x.tagName.slice(1) : null),
text: (x.innerText || '').trim() }))
.filter(x => x.label || x.text || x.role || x.level)`);
const serialized = JSON.stringify(nodes);
for (const wanted of ['dart', '\u2022', '1.']) {
if (!serialized.includes(wanted)) {
throw new Error(`Semantics lacks ${JSON.stringify(wanted)}`);
}
}
const levels = new Set(nodes.map((node) => node.level).filter(Boolean));
for (const level of ['1', '2', '3', '4', '5', '6']) {
if (!levels.has(level)) {
throw new Error(`Semantics lacks heading level ${level}: ${serialized}`);
}
}
const roles = new Set(nodes.map((node) => node.role).filter(Boolean));
for (const role of ['list', 'listitem', 'columnheader']) {
if (!roles.has(role)) {
throw new Error(`Semantics lacks role ${role}: ${serialized}`);
}
}
evidence.checks.push({
check:
'OCR prose, unsafe label, no raw markup, code/list labels, heading levels 1-6, list and columnheader roles',
headings: [...levels].sort(),
roleSample: [...roles].filter((role) =>
['list', 'listitem', 'columnheader', 'link', 'table', 'row', 'cell'].includes(role),
),
nodes: nodes.length,
});
const report = JSON.stringify(evidence, null, 2);
await writeFile(join(out, `${style}-evidence.json`), report);
console.log(report);
} finally {
ws?.close();
chrome.kill();
server.close();
for (let attempt = 0; attempt < 10; attempt++) {
try {
await rm(profile, { recursive: true, force: true });
break;
} catch {
await delay(200);
}
}
}