Files
pipelines/app/notes/C2-markdown.md
T
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

243 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.