a5afc55a9d
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
243 lines
15 KiB
Markdown
243 lines
15 KiB
Markdown
# 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<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.
|