From 333375df93c165bd9365e4b32ed3613a085ad7f2 Mon Sep 17 00:00:00 2001
From: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Date: Thu, 10 Sep 2026 14:26:12 +0700
Subject: [PATCH 1/3] ci: install the published CLI and hold it to its
 documented exit codes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`install.yml` answered "does `cargo add termlens` work for a stranger?" and
never asked the same of the binary. #310 was the cost: `termlens inspect
--version` exited 2 in the published 0.10.0, exited 2 again in 0.10.1, and
was found by a user of the published binary rather than by anything here.

A `cli` job installs `termlens-cli` from crates.io on Linux and macOS --
every run, never from a cache, because a cached binary is evidence about
whatever the registry served the day the cache was filled and this job
exists to be evidence about what it serves now.

It asserts every exit code `termlens --help` documents and STABILITY.md
promises: `--version` in all four positions returning the same string,
`inspect` printing a screen with its header and its trailer, `render` in
all four formats with `--svg` actually starting `<svg`, and `diff`
returning 0 for the same picture, 1 for a different one, and 2 for input it
cannot read.

The assertions are a script that takes the binary, not a block inlined in
the workflow, so the same contract runs against a path build. That is how a
check like this earns trust: re-introducing #310 by deleting one match arm
made it fail on `diff --version` -- exit 2, expected 0 -- and restoring the
arm made it pass.

`ci.yml` runs it on every pull request against `target/debug/termlens`. The
published check is the net; this is the fast feedback, and #326's whole
complaint is that the failure was found too late. `gates-listed` required
the new commands in CONTRIBUTING §1, which is that gate doing its job.

One thing this pinned rather than fixed: `termlens inspect > file` is not a
file `termlens render` will read -- the `--- exited:` trailer is a human
line, not part of the snapshot format, and the parser says "line 26: e".
The script strips it, and the round trip deserves its own issue.

Closes #326

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
---
 .github/scripts/check-cli-contract.sh | 115 ++++++++++++++++++++++++++
 .github/workflows/ci.yml              |   7 ++
 .github/workflows/install.yml         |  77 ++++++++++++++++-
 CHANGELOG.md                          |  21 +++++
 CONTRIBUTING.md                       |   2 +
 5 files changed, 220 insertions(+), 2 deletions(-)
 create mode 100755 .github/scripts/check-cli-contract.sh

diff --git a/.github/scripts/check-cli-contract.sh b/.github/scripts/check-cli-contract.sh
new file mode 100755
index 0000000..590e1eb
--- /dev/null
+++ b/.github/scripts/check-cli-contract.sh
@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# The published CLI's documented contract, as exit-code assertions.
+#
+# `termlens --help` states three exit codes -- 0 ran, 1 diff found a
+# difference, 2 termlens itself could not run -- and STABILITY.md promises
+# them. Nothing checked them against an *installed* binary until #326: the
+# `install` workflow verified `cargo add termlens` and never `cargo install
+# termlens-cli`, so #310 (`termlens inspect --version` exiting 2) shipped in
+# 0.10.0 and again in 0.10.1 and was found by a user of the published binary.
+#
+# Takes the binary to exercise, so the same assertions run against a release
+# from crates.io in CI and against `target/debug/termlens` locally -- which
+# is how you check that the assertions can fail at all:
+#
+#   cargo build -p termlens-cli
+#   .github/scripts/check-cli-contract.sh target/debug/termlens
+#
+# Portability: macOS ships bash 3.2 and BSD sed. No `declare -A`, no GNU-only
+# sed flags, no process substitution in the assertions.
+set -euo pipefail
+
+BIN=${1:?usage: check-cli-contract.sh <path-to-termlens>}
+command -v "$BIN" >/dev/null 2>&1 || [ -x "$BIN" ] || {
+  echo "check-cli-contract: $BIN is not executable" >&2
+  exit 2
+}
+
+WORK=$(mktemp -d 2>/dev/null || mktemp -d -t termlens-cli-contract)
+trap 'rm -rf "$WORK"' EXIT
+status=0
+
+# `<label> <expected-exit> <command…>`; runs it, compares, records.
+expect() {
+  label=$1
+  want=$2
+  shift 2
+  got=0
+  "$@" > "$WORK/out" 2> "$WORK/err" || got=$?
+  if [ "$got" = "$want" ]; then
+    printf '  ok    %-46s exit %s\n' "$label" "$got"
+  else
+    printf '  FAIL  %-46s exit %s, expected %s\n' "$label" "$got" "$want" >&2
+    sed 's/^/        /' "$WORK/err" >&2 || true
+    status=1
+  fi
+}
+
+contains() {
+  label=$1
+  needle=$2
+  file=$3
+  if grep -qF -- "$needle" "$file"; then
+    printf '  ok    %-46s contains %s\n' "$label" "$needle"
+  else
+    printf '  FAIL  %-46s does not contain %s\n' "$label" "$needle" >&2
+    status=1
+  fi
+}
+
+echo "cli contract: $BIN"
+
+# --- the version, in every position. #310 was exactly this.
+expect "--version"                 0 "$BIN" --version
+top=$("$BIN" --version 2>/dev/null || echo "<failed>")
+for sub in inspect diff render; do
+  expect "$sub --version"          0 "$BIN" "$sub" --version
+  sub_version=$("$BIN" "$sub" --version 2>/dev/null || echo "<failed>")
+  if [ "$sub_version" = "$top" ]; then
+    printf '  ok    %-46s same string as top level\n' "$sub --version"
+  else
+    printf '  FAIL  %-46s said %s, top level said %s\n' \
+      "$sub --version" "$sub_version" "$top" >&2
+    status=1
+  fi
+done
+
+# --- inspect drives a real PTY and prints a screen with its trailer.
+expect "inspect a program"         0 "$BIN" inspect sh -c 'printf hi'
+"$BIN" inspect sh -c 'printf hi' > "$WORK/raw.txt" 2>/dev/null || true
+contains "inspect prints the screen"  "hi"            "$WORK/raw.txt"
+contains "inspect prints the header"  "size: "        "$WORK/raw.txt"
+contains "inspect prints the trailer" "--- exited: "  "$WORK/raw.txt"
+
+# A saved screen is that output without the human trailer (see the note in
+# `install.yml`: the trailer is not part of the snapshot format).
+sed '/^--- exited:/d' "$WORK/raw.txt" > "$WORK/a.snap"
+"$BIN" inspect sh -c 'printf bye' 2>/dev/null | sed '/^--- exited:/d' > "$WORK/b.snap"
+printf 'not a saved screen at all\n' > "$WORK/junk.txt"
+
+# --- render, every format, from a saved screen.
+expect "render --text"             0 "$BIN" render --text "$WORK/a.snap"
+expect "render --svg"              0 "$BIN" render --svg  "$WORK/a.snap"
+expect "render --html"             0 "$BIN" render --html "$WORK/a.snap"
+expect "render --ansi"             0 "$BIN" render --ansi "$WORK/a.snap"
+"$BIN" render --svg "$WORK/a.snap" > "$WORK/out.svg" 2>/dev/null || true
+if head -c 4 "$WORK/out.svg" | grep -q '<svg'; then
+  printf '  ok    %-46s starts with <svg\n' "render --svg"
+else
+  printf '  FAIL  %-46s does not start with <svg\n' "render --svg" >&2
+  status=1
+fi
+
+# --- diff, which is the one command with three meaningful exit codes.
+expect "diff, same picture"        0 "$BIN" diff "$WORK/a.snap" "$WORK/a.snap"
+expect "diff, different pictures"  1 "$BIN" diff "$WORK/a.snap" "$WORK/b.snap"
+expect "diff, unreadable input"    2 "$BIN" diff "$WORK/junk.txt" "$WORK/a.snap"
+expect "render, unreadable input"  2 "$BIN" render --text "$WORK/junk.txt"
+expect "diff, missing file"        2 "$BIN" diff "$WORK/nope.snap" "$WORK/a.snap"
+expect "an unknown subcommand"     2 "$BIN" nonesuch
+expect "--help"                    0 "$BIN" --help
+
+if [ "$status" -eq 0 ]; then
+  echo "cli contract: PASS — every documented exit code holds"
+fi
+exit "$status"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9915ef8..60990d8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -64,6 +64,13 @@ jobs:
       - run: cargo test --workspace --all-features
         env:
           TERMLENS_ARTIFACT_DIR: ${{ runner.temp }}/termlens
+      # The CLI's documented exit codes, against this tree. `install.yml`
+      # runs the same script against the *published* binary, which is the
+      # net; this is the fast feedback. #310 was a `--version` that exited 2
+      # in two published releases and was found by a user, so the point is
+      # to fail on the pull request rather than after the publish.
+      - run: cargo build -p termlens-cli
+      - run: .github/scripts/check-cli-contract.sh target/debug/termlens
       # The screens of whatever failed, in the step summary (#251). The
       # suite dogfoods the action with the CLI from this tree.
       - uses: ./.github/actions/report
diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml
index 5027727..e42dd6e 100644
--- a/.github/workflows/install.yml
+++ b/.github/workflows/install.yml
@@ -22,9 +22,18 @@
 #     shapes are verified (#238).
 #
 # The consumer is a real crate in an empty directory, and the test it runs is
-# a real PTY — which is the whole product, so nothing else would do. Nothing
-# here checks this repository out: the version and the feature list come from
+# a real PTY — which is the whole product, so nothing else would do. The
+# `consume` job checks nothing out: the version and the feature list come from
 # the registry, because the registry is what a consumer gets.
+#
+# The `cli` job answers the same question for the *binary*, which had no
+# answer at all until #326: this workflow verified `cargo add termlens` and
+# never `cargo install termlens-cli`, so #310 — `termlens inspect --version`
+# exiting 2 — shipped in 0.10.0, shipped again in 0.10.1, and was found by a
+# user of the published binary rather than by anything here. It checks the
+# repository out for one file, `.github/scripts/check-cli-contract.sh`: the
+# subject still comes from the registry, only the harness comes from here,
+# which is also what lets the same assertions run against a path build.
 name: install
 
 on:
@@ -244,3 +253,67 @@ jobs:
             fi
           fi
           cargo test --tests -- --nocapture
+
+  # The published CLI, installed the way a user installs it, held to the
+  # three exit codes `termlens --help` documents and STABILITY.md promises.
+  cli:
+    name: cli (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+      - name: Ask the registry what was published
+        id: crate
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+          WANTED: ${{ inputs.version }}
+        run: |
+          api="https://crates.io/api/v1/crates/termlens-cli"
+          agent="termlens-install-check (github actions)"
+          version="${WANTED#v}"
+          version="${version:-${TAG#v}}"
+          if [ -z "$version" ]; then
+            version=$(curl -sSf -H "User-Agent: $agent" "$api" | jq -r .crate.max_stable_version)
+          fi
+
+          # `termlens-cli` is published after `termlens` in the same release,
+          # so the index can trail the release event by longer here than for
+          # the library. Wait rather than fail.
+          for attempt in $(seq 30); do
+            body=$(curl -sS -H "User-Agent: $agent" "$api/$version") || body=""
+            if [ "$(printf '%s' "$body" | jq -r '.version.num // empty')" = "$version" ]; then
+              break
+            fi
+            echo "waiting for termlens-cli $version to appear on crates.io (${attempt}/30)"
+            sleep 10
+          done
+
+          num=$(printf '%s' "$body" | jq -r '.version.num // empty')
+          if [ "$num" != "$version" ]; then
+            echo "::error::termlens-cli $version never appeared on crates.io"
+            exit 1
+          fi
+          if [ "$(printf '%s' "$body" | jq -r .version.yanked)" != "false" ]; then
+            echo "::error::termlens-cli $version is yanked"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "verifying termlens-cli $version"
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # v1
+        with:
+          toolchain: stable
+      # From the registry, every run, never from a cache: a cached binary is
+      # evidence about whatever crates.io served the day the cache was
+      # filled, and this job exists to be evidence about what it serves now.
+      - name: Install the published CLI
+        env:
+          VERSION: ${{ steps.crate.outputs.version }}
+        run: cargo install termlens-cli --version "=$VERSION" --locked --force
+      - name: Hold it to its documented contract
+        run: .github/scripts/check-cli-contract.sh "$(command -v termlens)"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89fa337..9dd6230 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,27 @@ listed under a **Changed** or **Removed** heading.
 
 ## [Unreleased]
 
+### Added
+
+- **The published CLI is installed and held to its documented contract**
+  (#326). `install.yml` verified `cargo add termlens` and never
+  `cargo install termlens-cli`, so #310 — `termlens inspect --version`
+  exiting 2 — shipped in 0.10.0, shipped again in 0.10.1, and was found by a
+  user of the published binary rather than by anything here.
+
+  A `cli` job installs `termlens-cli` from crates.io on Linux and macOS —
+  every run, never from a cache — and asserts every exit code
+  `termlens --help` documents: `--version` in all four positions returning
+  the same string, `inspect` printing a screen with its header and trailer,
+  `render` in all four formats, and `diff` returning **0** for the same
+  picture, **1** for a different one and **2** for input it cannot read.
+
+  The assertions live in `.github/scripts/check-cli-contract.sh` and take
+  the binary to exercise, so the same script runs against a path build. `ci.yml`
+  does exactly that on every pull request: the published check is the net,
+  the tree check is the fast feedback. Re-introducing #310 locally was
+  observed to fail it.
+
 ### Fixed
 
 - **`termlens <subcommand> --version` is no longer an unknown option.**
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ccb8dac..3f0fd9a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,6 +34,8 @@ cargo test --workspace --no-default-features --features decode
 cargo test --workspace --no-default-features --features regex
 cargo test --workspace --no-default-features --features serde
 cargo test --workspace                                   # default features
+cargo build -p termlens-cli                              # then the CLI's documented exit codes:
+.github/scripts/check-cli-contract.sh target/debug/termlens
 RUSTDOCFLAGS='-D warnings' cargo doc --no-deps
 RUSTDOCFLAGS='-D warnings' cargo doc --no-deps --all-features
 cargo deny check                          # cargo install cargo-deny

From 9deffbe27519524a894681165c0f57405e403693 Mon Sep 17 00:00:00 2001
From: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Date: Thu, 10 Sep 2026 14:34:10 +0700
Subject: [PATCH 2/3] fix: stop naming the SGRs the attribute shadow implements
 as unimplemented

`Screen::unsupported()` is documented as listing every sequence *the
emulator* did not implement. It was listing the backend's gaps instead: 5,
6, 8, 9, 25, 28 and 29 are exactly the parameters `emu/shadow.rs` exists to
recover -- vt100 drops them, they arrive at `unhandled_csi`, and the shadow
parser then puts the attribute on the cell anyway.

So one screen said `Style::blink` was true and `unsupported()` said `^[[5m`
had been dropped, at the same instant. A reader checking the list before
trusting a blink or masked-password assertion concluded a correct assertion
was unreliable, and `assert!(screen.unsupported().is_empty())` -- the
natural "did my app emit anything this harness cannot see?" check -- could
not pass for any application using either attribute.

An SGR whose every parameter the shadow recovers is now handled. One
parameter outside the set keeps the whole sequence, because dropping a
mixed sequence would hide a real gap: `^[[5;59m` is blink recovered and
underline colour modelled by nobody, and it stays.

Three tests, one per line of the issue's done-when. The third records the
residue rather than hiding it: `^[[1;5;31m` is still named although bold,
red and blink all reach the cell -- measured, not assumed. `1` and `31` are
vt100's to implement and this tracker knows the shadow's set, not the
backend's. Narrowing it means enumerating vt100's SGR surface, which is a
bigger claim than a patch should make.

`shadow::carrier` and `unhandled::SHADOW_SGR_PARAMS` describe the same set
in two places and could drift silently in both directions -- a parameter
added to one and not the other is either named while its attribute reaches
the cell, or dropped from the record while nothing carries it. A test holds
them equal; removing 29 from one list was observed to fail it.

The `styled_json` insta snapshot loses `^[[8m` and `^[[28m`: that fixture
renders conceal, so it was reporting conceal as unimplemented on a screen
that shows it. The fix, visible in a recording.

Closes #320

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
---
 CHANGELOG.md                                  |  30 +++++
 crates/termlens/src/emu/shadow.rs             |  28 +++++
 crates/termlens/src/emu/unhandled.rs          |  26 +++++
 .../snapshots/export__json__styled_json.snap  |   5 +-
 crates/termlens/tests/unsupported.rs          | 105 ++++++++++++++++++
 5 files changed, 190 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9dd6230..d77c153 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,36 @@ listed under a **Changed** or **Removed** heading.
 
 ### Fixed
 
+- **`unsupported()` no longer names the four SGR parameters the attribute
+  shadow implements** (#320). `5`/`25` (blink), `9`/`29` (strikethrough),
+  and `6`/`8`/`28` with them are exactly what `emu/shadow.rs` exists to
+  recover: vt100 drops them, the shadow parser puts the attribute on the
+  cell, and the tracker then reported the *backend's* gap under an accessor
+  documented as naming the emulator's.
+
+  The consequence was the one the accessor was added to prevent, inverted: a
+  screen said `Style::blink` was true and `unsupported()` said `^[[5m` had
+  been dropped, at the same instant — so a reader checking the list before
+  trusting a blink or masked-password assertion concluded a correct
+  assertion was unreliable, and
+  `assert!(screen.unsupported().is_empty())` could never pass for an
+  application that uses either attribute.
+
+  Found by `termlens-demo` driving a real ratatui application against the
+  published 0.10.1, which is what the testing tier is for.
+
+  **What still gets named.** An SGR with one parameter nobody models keeps
+  the whole sequence: `^[[59m` (underline colour) alone, and `^[[5;59m`,
+  where blink is recovered and `59` is not. Dropping a mixed sequence
+  because part of it is implemented would hide a real gap.
+
+  **The residue, measured rather than assumed.** `^[[1;5;31m` is still
+  named although bold, red *and* blink all reach the cell — `1` and `31`
+  are vt100's to implement, and this tracker knows what the shadow
+  recovers, not what the backend does. Narrowing that needs vt100's own SGR
+  surface enumerated, which is more than a patch should claim; a test
+  records the behaviour so it is a documented edge rather than a surprise.
+
 - **`termlens <subcommand> --version` is no longer an unknown option.**
   The flag was handled only in the top-level dispatch, so `termlens inspect
   --version` exited 2 while `-h`/`--help` worked in that position. All three
diff --git a/crates/termlens/src/emu/shadow.rs b/crates/termlens/src/emu/shadow.rs
index e3e0e5f..c4e33c4 100644
--- a/crates/termlens/src/emu/shadow.rs
+++ b/crates/termlens/src/emu/shadow.rs
@@ -320,6 +320,11 @@ fn rewrite_sgr(seq: &[u8]) -> Option<Vec<u8>> {
 }
 
 /// The shadow parameter carrying `param`, if any.
+///
+/// Every `Some` here except `0` is a parameter vt100 drops and this parser
+/// recovers, so `unhandled::SHADOW_SGR_PARAMS` must list exactly those —
+/// otherwise `Screen::unsupported()` names a sequence whose effect is on
+/// the cell (#320). A test in this module holds the two in step.
 fn carrier(param: u32) -> Option<u32> {
     match param {
         0 => Some(0),     // reset all: means the same in both streams
@@ -337,6 +342,29 @@ fn carrier(param: u32) -> Option<u32> {
 mod tests {
     use super::*;
 
+    /// The two lists that describe the same set, held together (#320).
+    ///
+    /// `carrier` decides what this parser recovers; `SHADOW_SGR_PARAMS`
+    /// decides what the unhandled tracker declines to record. They were
+    /// written apart and can drift apart, and the drift is silent in both
+    /// directions: a parameter added here and not there is named as
+    /// unimplemented while its attribute reaches the cell, and one added
+    /// there and not here is dropped from the record while nothing carries
+    /// it.
+    #[test]
+    fn the_recovered_parameters_are_exactly_what_the_tracker_declines() {
+        let recovered: Vec<u16> = (0..=255u32)
+            .filter(|&p| p != 0 && carrier(p).is_some())
+            .map(|p| p as u16)
+            .collect();
+        let mut declined = crate::emu::unhandled::SHADOW_SGR_PARAMS.to_vec();
+        declined.sort_unstable();
+        assert_eq!(
+            recovered, declined,
+            "shadow::carrier recovers {recovered:?}, unhandled declines {declined:?}"
+        );
+    }
+
     /// The real rewriter's output, as a readable string.
     fn shadowed(bytes: &[u8]) -> String {
         let mut shadow = AttrShadow::new(4, 20, 0);
diff --git a/crates/termlens/src/emu/unhandled.rs b/crates/termlens/src/emu/unhandled.rs
index f24f313..39e1a90 100644
--- a/crates/termlens/src/emu/unhandled.rs
+++ b/crates/termlens/src/emu/unhandled.rs
@@ -94,6 +94,19 @@ fn params_text(params: &[&[u16]]) -> String {
 /// console's handshake in every Windows snapshot's list (#149).
 const TRACKED_PRIVATE_MODES: &[u16] = &[9, 1000, 1002, 1003, 1005, 1006, 1015, 1004, 2026, 9001];
 
+/// The SGR parameters [`shadow`](super::shadow) recovers: blink, conceal,
+/// strikethrough and their three "off" forms.
+///
+/// vt100 drops these, so they arrive here as unhandled — and the shadow
+/// parser then puts the attribute on the cell anyway, which is the whole
+/// reason it exists. Recording them said the emulator did not implement a
+/// sequence whose effect `Style::blink` reports on the same `Screen`
+/// (#320): the accessor names *the emulator's* gaps, and this is the
+/// backend's, in front of which termlens does the work.
+///
+/// Kept in step with `shadow::sgr_substitute` by a test.
+pub(super) const SHADOW_SGR_PARAMS: &[u16] = &[5, 6, 8, 9, 25, 28, 29];
+
 impl Callbacks for Unhandled {
     fn visual_bell(&mut self, _: &mut vt100::Screen) {
         self.visual_bells = self.visual_bells.saturating_add(1);
@@ -166,6 +179,19 @@ impl Callbacks for Unhandled {
                 .iter()
                 .flat_map(|p| p.iter())
                 .all(|m| TRACKED_PRIVATE_MODES.contains(m)),
+            // An SGR every one of whose parameters the shadow recovers is
+            // implemented, and naming it here would contradict the cell
+            // (#320). One parameter outside the set and the whole sequence
+            // is still recorded: dropping it would hide a genuine gap, and
+            // `^[[5;59m` — blink recovered, underline colour modelled by
+            // nobody — is exactly that shape.
+            (None, None, 'm') => {
+                let mut seen = false;
+                params.iter().flat_map(|p| p.iter()).all(|p| {
+                    seen = true;
+                    SHADOW_SGR_PARAMS.contains(p)
+                }) && seen
+            }
             _ => false,
         };
         if handled {
diff --git a/crates/termlens/tests/snapshots/export__json__styled_json.snap b/crates/termlens/tests/snapshots/export__json__styled_json.snap
index 17b58bc..f6a42d2 100644
--- a/crates/termlens/tests/snapshots/export__json__styled_json.snap
+++ b/crates/termlens/tests/snapshots/export__json__styled_json.snap
@@ -2113,10 +2113,7 @@ expression: s
       false
     ],
     "insert_mode": false,
-    "unsupported": [
-      "^[[8m",
-      "^[[28m"
-    ],
+    "unsupported": [],
     "unsupported_overflow": 0,
     "visual_bells": 0
   }
diff --git a/crates/termlens/tests/unsupported.rs b/crates/termlens/tests/unsupported.rs
index a8b545d..0cbde62 100644
--- a/crates/termlens/tests/unsupported.rs
+++ b/crates/termlens/tests/unsupported.rs
@@ -108,3 +108,108 @@ fn the_record_is_bounded() -> termlens::Result<()> {
     assert!(t.wait_exit()?.success());
     Ok(())
 }
+
+/// #320: an SGR the attribute shadow recovers is *implemented*, and naming
+/// it here contradicted the cell on the same `Screen` — `Style::blink` said
+/// the cell blinks while `unsupported()` said `^[[5m` was dropped. It also
+/// made the natural check impossible: `assert!(s.unsupported().is_empty())`
+/// could never pass for an application that blinks or strikes through.
+///
+/// Measured against 0.10.1 by `termlens-demo` driving a real ratatui
+/// application, which is where the defect was found.
+#[test]
+#[cfg_attr(
+    windows,
+    ignore = "ConPTY renders what it implements and drops the rest before termlens sees a byte, so the record there is the console's, not the application's (#149)"
+)]
+fn the_sgrs_the_shadow_recovers_are_not_named_as_unimplemented() -> termlens::Result<()> {
+    // Every parameter `shadow::sgr_substitute` carries, on and off.
+    for param in [5u16, 6, 8, 9, 25, 28, 29] {
+        let mut t = emit(&["--csi", &format!("{param}m"), "text", "--wait"])?;
+        t.wait_until(|s| s.contains("text"))?;
+        assert_eq!(
+            shapes(&t),
+            Vec::<String>::new(),
+            "^[[{param}m is recovered by the shadow, so nothing is unimplemented"
+        );
+        t.send(Key::Enter)?;
+        assert!(t.wait_exit()?.success());
+    }
+
+    // And the attribute really is on the cell — the half that makes the
+    // above a fix rather than silence.
+    let mut t = emit(&["--csi", "5m", "--csi", "9m", "marked", "--wait"])?;
+    t.wait_until(|s| s.contains("marked"))?;
+    let s = t.screen();
+    let style = *s.cell(0, 0).expect("the cell").style();
+    assert!(style.blink && style.strikethrough, "{style:?}");
+    assert!(s.unsupported().is_empty(), "{:?}", shapes(&t));
+    t.send(Key::Enter)?;
+    assert!(t.wait_exit()?.success());
+    Ok(())
+}
+
+/// The other half of #320: an SGR nobody models is still named. `59` is
+/// underline colour — the shadow does not carry it and neither does vt100 —
+/// and it appeared in the original report alongside the four false ones.
+#[test]
+#[cfg_attr(
+    windows,
+    ignore = "ConPTY renders what it implements and drops the rest before termlens sees a byte, so the record there is the console's, not the application's (#149)"
+)]
+fn an_sgr_nobody_models_is_still_named() -> termlens::Result<()> {
+    let mut t = emit(&["--csi", "59m", "text", "--wait"])?;
+    t.wait_until(|s| s.contains("text"))?;
+    assert_eq!(shapes(&t), ["^[[59m"]);
+    t.send(Key::Enter)?;
+    assert!(t.wait_exit()?.success());
+    Ok(())
+}
+
+/// A mixed SGR is reported whole, and this test says which parameter keeps
+/// it in the record.
+///
+/// `^[[5;59m` carries one parameter the shadow recovers (`5`, blink) and one
+/// nobody models (`59`). Dropping the sequence because *some* of it is
+/// implemented would hide the gap, so the rule is all-or-nothing per
+/// sequence: one unrecovered parameter keeps the whole shape.
+///
+/// The cost of that rule, measured rather than assumed: `^[[1;5;31m` is
+/// still named even though bold, red *and* blink all reach the cell — `1`
+/// and `31` are vt100's to implement, and this tracker knows what the
+/// shadow recovers, not what the backend does. Narrowing it further means
+/// enumerating vt100's own SGR surface, which is a bigger claim than a
+/// patch should make.
+#[test]
+#[cfg_attr(
+    windows,
+    ignore = "ConPTY renders what it implements and drops the rest before termlens sees a byte, so the record there is the console's, not the application's (#149)"
+)]
+fn a_mixed_sgr_is_named_by_the_parameter_nobody_models() -> termlens::Result<()> {
+    let mut t = emit(&["--csi", "5;59m", "text", "--wait"])?;
+    t.wait_until(|s| s.contains("text"))?;
+    let s = t.screen();
+    assert_eq!(shapes(&t), ["^[[5;59m"], "59 keeps it: {s}");
+    assert!(
+        s.cell(0, 0).expect("the cell").style().blink,
+        "and 5 still reached the cell: {s}"
+    );
+    t.send(Key::Enter)?;
+    assert!(t.wait_exit()?.success());
+
+    // The documented residue: everything here was applied, and it is still
+    // named. A test says so rather than a reader discovering it.
+    let mut t = emit(&["--csi", "1;5;31m", "text", "--wait"])?;
+    t.wait_until(|s| s.contains("text"))?;
+    let s = t.screen();
+    let style = *s.cell(0, 0).expect("the cell").style();
+    assert!(style.bold && style.blink, "all three applied: {style:?}");
+    assert_eq!(
+        shapes(&t),
+        ["^[[1;5;31m"],
+        "still named: the tracker knows the shadow's set, not vt100's"
+    );
+    t.send(Key::Enter)?;
+    assert!(t.wait_exit()?.success());
+    Ok(())
+}

From 588490294beeb3d4b9c2dd24acdb00d17aa1d4fd Mon Sep 17 00:00:00 2001
From: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
Date: Thu, 10 Sep 2026 14:35:26 +0700
Subject: [PATCH 3/3] chore: release v0.10.2

Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
---
 CHANGELOG.md                   |  2 ++
 Cargo.lock                     | 18 +++++++++---------
 Cargo.toml                     |  2 +-
 crates/termlens-cli/Cargo.toml |  2 +-
 4 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d77c153..233327c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ listed under a **Changed** or **Removed** heading.
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-09-10
+
 ### Added
 
 - **The published CLI is installed and held to its documented contract**
diff --git a/Cargo.lock b/Cargo.lock
index 02e135b..97568d3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -343,7 +343,7 @@ checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
 
 [[package]]
 name = "emit"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "libc",
 ]
@@ -432,7 +432,7 @@ checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 
 [[package]]
 name = "form-echo"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "crossterm",
 ]
@@ -524,7 +524,7 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "hello-tui"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "crossterm",
  "termlens",
@@ -544,7 +544,7 @@ checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
 
 [[package]]
 name = "image-echo"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "miniz_oxide",
 ]
@@ -1085,7 +1085,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui-app"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "ratatui",
  "serde_json",
@@ -1217,7 +1217,7 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "resize-echo"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "crossterm",
 ]
@@ -1519,7 +1519,7 @@ dependencies = [
 
 [[package]]
 name = "termlens"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "anyhow",
  "insta",
@@ -1537,7 +1537,7 @@ dependencies = [
 
 [[package]]
 name = "termlens-cli"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "serde_json",
  "termlens",
@@ -1696,7 +1696,7 @@ checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
 [[package]]
 name = "unicode-torture"
-version = "0.10.1"
+version = "0.10.2"
 
 [[package]]
 name = "unicode-truncate"
diff --git a/Cargo.toml b/Cargo.toml
index cdaac68..b34d03a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,7 +8,7 @@ resolver = "2"
 members = ["crates/termlens", "crates/termlens-cli", "fixtures/*"]
 
 [workspace.package]
-version = "0.10.1"
+version = "0.10.2"
 edition = "2021"
 # Minimum supported Rust version. Checked by the `msrv` CI job, which reads
 # this field; bumping it is a minor (not patch) change per our SemVer policy.
diff --git a/crates/termlens-cli/Cargo.toml b/crates/termlens-cli/Cargo.toml
index 5c5bdb9..0f32e7f 100644
--- a/crates/termlens-cli/Cargo.toml
+++ b/crates/termlens-cli/Cargo.toml
@@ -23,7 +23,7 @@ doc = false
 # The version is the one release bumps alongside `workspace.package.version`
 # (docs/RELEASING.md); a path dependency needs it to publish. `serde` so a
 # saved screen can be JSON as well as the text format.
-termlens = { version = "0.10.1", path = "../termlens", default-features = false, features = ["serde"] }
+termlens = { version = "0.10.2", path = "../termlens", default-features = false, features = ["serde"] }
 serde_json.workspace = true
 
 [lints]