Today — docs/DESIGN.md §3 is the normative spec for the snapshot text format: the header line, the grid, the styles: block, what is deliberately not in it. Screen::parse (added in 0.10.0) is the function that reads that format back, and it is where the round-trip rules live — a hidden cursor comes back at 0,0, the header's row count decides where the grid ends, a trimmed grid carrying a styles block resolves as content. Measured on 0.10.1: grep -c 'Screen::parse' docs/DESIGN.md → 0.
Why it is worth fixing — §3 is what someone reads to implement against the format or to trust a saved snapshot. A spec that never mentions its own reader sends them to the rustdoc to discover that the format round-trips at all.
Fix — a short paragraph at the end of §3: Screen::parse reads the format back, what survives the trip and what does not (out-of-band state is default; a hidden cursor's position is not recorded), and that termlens-cli uses it to diff and render saved screens. Keep it to the facts already in Screen::parse's rustdoc — this is a pointer, not a second spec.
Done when
A good first contribution: one file, no architecture decisions. Start with
CONTRIBUTING.md
— §1 lists every gate you can run locally, and §3 asks that a change land
with a test. Commits are Conventional Commits and need git commit -s
(DCO). Happy to review a draft PR early.
Today —
docs/DESIGN.md§3 is the normative spec for the snapshot text format: the header line, the grid, thestyles:block, what is deliberately not in it.Screen::parse(added in 0.10.0) is the function that reads that format back, and it is where the round-trip rules live — a hidden cursor comes back at0,0, the header's row count decides where the grid ends, a trimmed grid carrying a styles block resolves as content. Measured on 0.10.1:grep -c 'Screen::parse' docs/DESIGN.md→ 0.Why it is worth fixing — §3 is what someone reads to implement against the format or to trust a saved snapshot. A spec that never mentions its own reader sends them to the rustdoc to discover that the format round-trips at all.
Fix — a short paragraph at the end of §3:
Screen::parsereads the format back, what survives the trip and what does not (out-of-band state is default; a hidden cursor's position is not recorded), and thattermlens-cliuses it to diff and render saved screens. Keep it to the facts already inScreen::parse's rustdoc — this is a pointer, not a second spec.Done when
Screen::parseand says what a round trip preserves.Screen::parse's rustdoc.A good first contribution: one file, no architecture decisions. Start with
CONTRIBUTING.md
— §1 lists every gate you can run locally, and §3 asks that a change land
with a test. Commits are Conventional Commits and need
git commit -s(DCO). Happy to review a draft PR early.