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

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

15 KiB
Raw Permalink Blame History

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 (< → <). 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 &#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.