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
15 KiB
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 elsecode), 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, sosnake_case_namestays plain),[label](url)links and barehttp(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 anint(19+ decimal or 17+ hex digits) and a value beyond0x10FFFFare both kept literally withint.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/httpstargets are safe.javascript:,data:,ftp:and relative targets render as their label. The parser exposesisSafeMarkdownLink; the renderer attaches a tap recognizer only to safe links and only when the caller suppliesonOpenLink. Without that callback a safe link renders as its label with no false affordance. chatMarkdownText(BuildContext, String, {onOpenLink})is theChatMessageTextBuilderseam already present onChatMessageView; a test passeschatMarkdownTextdirectly astextBuilder.- Rendering uses native
Text.richblocks inside the nativeSelectionArea, with host theme roles only. Headings use a non-increasing host sequence: MaterialheadlineSmall/titleLarge/titleMediumfor H1/H2/H3–H6, or CupertinonavLargeTitleTextStyle/navTitleTextStylefor 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 withheadingLevel1–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 (orcode), 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 exposecolumnHeaderroles; lists exposelist/listItemroles. - A link recognizer is placed on the link's text leaves because a
TextSpanonly 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. SelectionAreaasserts onMaterialLocalizations. Material hosts already provide it; a bareCupertinoAppgets one nestedLocalizationsscope 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 useDivider. 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:
_numericReferenceusedint.parse, which throwsFormatExceptionon a reference overflowing a 64-bit int, so a message with�or�failedChatMarkdownView.buildon the VM. It now usesint.tryParseand keeps the existing1..0x10FFFFguard, 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,
parseMarkdowndoes 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 previousint.parseimplementation and passes now (negative control run). - Advisory, applied:
_autolinkAtreuses a hoistedRegExp(r'\s')instead of compiling one per character, and_selectablenow callsusesCupertinoHostfromlib/ui/adaptive/host.dartinstead of repeating theLocalizations.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);
_linksrecognizer 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
(
titleSmall14 for H4, thenbodyLarge16 for H5,bodyMedium14 for H6); Cupertino H3–H6 were plaintextStyle. Material now usesheadlineSmall/titleLarge/titleMediumfor H1/H2/H3–H6 and Cupertino usesnavLargeTitleTextStyle/navTitleTextStylefor 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-headingsize. 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 exposeSemantics(headingLevel: level, container: true); table header cells exposeSemanticsRole.columnHeaderinstead of a generic heading flag; lists exposeSemanticsRole.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
(
tabLabelTextStyleis a 10 px tab-bar style that rendered thedartlabel too small and failed OCR), so the code label keepstextStylethere. No monospace, syntax highlighting, parse caching, scrollbar affordance or link accent colour was added; those remain product/integration decisions. - Fixture:
tool/chat_markdown_probe.dartnow 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-changedon the seven Dart files: 0 changed;node --check tool/chat_markdown_probe.mjs: passed.flutter build webfor the probe (Material and Cupertino) and forlib/main.dart: all built. Both browser probes passed OCR and the new AX assertions (h1–h6levels,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-changedon the four Dart candidate files: 0 changed. The 233-input entity differential againstweb/src/markdown.js(decodeHtmlEntitiesonly, 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.mjsinweb/: 0 failures, confirming the reference parser expectations the port follows.node --check tool/chat_markdown_probe.mjs: passed.flutter build webfortool/chat_markdown_probe.dartwith bothCHAT_MARKDOWN_PROBE_STYLE=materialandcupertino: both built on visit 1 and again after the fix (17.1s / 20.6s).flutter build webfor the normallib/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, thedartcode label and code text,Open docs, the inertunsafelabel, the bare autolink, literal<b>markup and~~strikethrough~~. It also asserted that raw**,```,| ---andjavascript:alertnever appears; the semantics tree exposed thedart,•and1.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:
okhas aTapGestureRecognizerthat 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.mdedit (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.