diff --git a/app/lib/features/chat/ui/transcript/chat_markdown.dart b/app/lib/features/chat/ui/transcript/chat_markdown.dart new file mode 100644 index 00000000..54b0ae79 --- /dev/null +++ b/app/lib/features/chat/ui/transcript/chat_markdown.dart @@ -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 _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 +/// `&lt;` becomes `<` 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 lines; +} + +final class MarkdownList extends MarkdownBlock { + const MarkdownList({required this.ordered, required this.items}); + final bool ordered; + final List items; +} + +final class MarkdownTable extends MarkdownBlock { + const MarkdownTable(this.header, this.rows); + final List header; + final List> rows; +} + +final class MarkdownRule extends MarkdownBlock { + const MarkdownRule(); +} + +/// Parses [source] into the block list a renderer walks. Never throws. +List parseMarkdown(String? source) { + final lines = decodeHtmlEntities( + source ?? '', + ).replaceAll('\r\n', '\n').replaceAll('\r', '\n').split('\n'); + final blocks = []; + 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 = []; + 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 = []; + 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 = >[]; + 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 = []; + 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 = [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 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 _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 _fitRow(List 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 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 spans; +} + +final class MarkdownEmphasis extends MarkdownInline { + const MarkdownEmphasis(this.spans); + final List spans; +} + +final class MarkdownLink extends MarkdownInline { + const MarkdownLink(this.url, this.spans); + final String url; + final List 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 parseInline(String? text) { + final source = text ?? ''; + final spans = []; + 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; +} diff --git a/app/lib/features/chat/ui/transcript/chat_markdown_view.dart b/app/lib/features/chat/ui/transcript/chat_markdown_view.dart new file mode 100644 index 00000000..10b29cdc --- /dev/null +++ b/app/lib/features/chat/ui/transcript/chat_markdown_view.dart @@ -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? onOpenLink; + + @override + State 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? onOpenLink, +}) => ChatMarkdownView(text: text, onOpenLink: onOpenLink); + +class _ChatMarkdownViewState extends State { + final Map _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 _spans( + BuildContext context, + List 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 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; +} diff --git a/app/notes/C2-markdown.md b/app/notes/C2-markdown.md new file mode 100644 index 00000000..2f320850 --- /dev/null +++ b/app/notes/C2-markdown.md @@ -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 (`&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 + `�` or `�` 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` 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 `` 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. diff --git a/app/test/features/chat/ui/transcript/chat_markdown_presentation_test.dart b/app/test/features/chat/ui/transcript/chat_markdown_presentation_test.dart new file mode 100644 index 00000000..6bb18e29 --- /dev/null +++ b/app/test/features/chat/ui/transcript/chat_markdown_presentation_test.dart @@ -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( + 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(find.byType(Table)); + final decoration = table.children.first.decoration; + expect(decoration, isA(), reason: '$cupertino'); + expect((decoration! as BoxDecoration).color, fill, reason: '$cupertino'); + final headers = tester + .widgetList(find.byType(Semantics)) + .where( + (widget) => widget.properties.role == SemanticsRole.columnHeader, + ); + expect(headers, hasLength(2), reason: '$cupertino'); + expect( + tester + .widgetList(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(); + }); +} diff --git a/app/test/features/chat/ui/transcript/chat_markdown_test.dart b/app/test/features/chat/ui/transcript/chat_markdown_test.dart new file mode 100644 index 00000000..76452b53 --- /dev/null +++ b/app/test/features/chat/ui/transcript/chat_markdown_test.dart @@ -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 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('&lt; "x" ' ''), + '< "x" \' \'', + ); + expect(decodeHtmlEntities('&amp;'), '&'); + expect(decodeHtmlEntities(' …—'), '\u00a0\u2026\u2014'); + }); + + test('keeps unknown and malformed references as written', () { + expect( + decodeHtmlEntities('&bogus; & &#xZZ; �'), + '&bogus; & &#xZZ; �', + ); + }); + + test('an overflowing numeric reference stays literal and never throws', () { + const overflow = '� �'; + 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('� �'), + '� �', + ); + expect(decodeHtmlEntities('A A'), '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().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(), hasLength(3)); + expect(blocks.last, isA()); + }); + + 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()); + 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().single.text, 'x = 1'); + expect(spans.whereType(), hasLength(2)); + expect(spans.whereType(), 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().single, isNotNull); + expect( + spans.whereType().first.text, + 'snake_case_name and ', + ); + expect(spans.whereType().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().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,

x

', + '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 = 'bold? '; + final spans = parseInline(source); + expect(spans.whereType().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(), isEmpty); + }); + }); +} diff --git a/app/test/features/chat/ui/transcript/chat_markdown_test_support.dart b/app/test/features/chat/ui/transcript/chat_markdown_test_support.dart new file mode 100644 index 00000000..8a46f2a3 --- /dev/null +++ b/app/test/features/chat/ui/transcript/chat_markdown_test_support.dart @@ -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 +literal ~~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 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(find.byType(Text)).map(textOf).join('\n'); + +Text textWidget(WidgetTester tester, String text) => tester + .widgetList(find.byType(Text)) + .firstWhere((widget) => textOf(widget) == text); + +Iterable _spansBelow(InlineSpan root) sync* { + if (root is! TextSpan) return; + yield root; + for (final child in root.children ?? const []) { + yield* _spansBelow(child); + } +} + +List spansOf(WidgetTester tester, String text) { + final widget = tester + .widgetList(find.byType(Text)) + .firstWhere((widget) => textOf(widget).contains(text)); + return _spansBelow(widget.textSpan!).toList(); +} diff --git a/app/test/features/chat/ui/transcript/chat_markdown_view_test.dart b/app/test/features/chat/ui/transcript/chat_markdown_view_test.dart new file mode 100644 index 00000000..caac9d48 --- /dev/null +++ b/app/test/features/chat/ui/transcript/chat_markdown_view_test.dart @@ -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 = []; + 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(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
(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()); + expect(bad.recognizer, isNull); + expect(bad.style?.decoration, isNull); + expect(auto.recognizer, isA()); + final boldLink = links.firstWhere((span) => span.text == 'bold link'); + expect(boldLink.recognizer, isA()); + 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(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 = []; + 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 � and � 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); + }); +} diff --git a/app/tool/chat_markdown_probe.dart b/app/tool/chat_markdown_probe.dart new file mode 100644 index 00000000..5de848a0 --- /dev/null +++ b/app/tool/chat_markdown_probe.dart @@ -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. +literal html 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)), + ), + ); +} diff --git a/app/tool/chat_markdown_probe.mjs b/app/tool/chat_markdown_probe.mjs new file mode 100644 index 00000000..d3e294cc --- /dev/null +++ b/app/tool/chat_markdown_probe.mjs @@ -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); + } + } +}