# 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.