fix(tui): align events vocabulary + filter-keys hint with A1 (#109)

Two A1-era cleanups bundled from the 2026-05-21 EN<->ZH TUI audit:

1. EN event panel said "joined" but the events are `*_seen`.
   `ble_device_seen` / `bonjour_service_seen` / `lan_host_seen`
   rendered in EN as `[BLE] device joined:` / `[BJ] service joined:`
   / `[LAN] host joined:`. ZH already said `设备出现 / 服务出现 /
   主机出现` and the JSONL `type` always said `*_seen`. "Joined"
   also lies about semantics — events fire on the first passive
   observation, including strangers' phones walking past. Renamed
   three EN i18n keys to `device seen: ` / `service seen: ` /
   `host seen: `; ZH unchanged.

2. Events filter docs claimed `1/2/3/4/0` but A1 added `5/6/7`.
   Bindings 5/6/7 → ble/bonjour/lan are wired in
   `EventsScreen.BINDINGS`, but four user-facing strings (modal
   footer + help-modal prose, EN + ZH) still listed only the
   legacy five keys. Extended to `1/2/3/4/5/6/7/0` in both
   locales so the new filters are discoverable from the TUI alone.

Spec: tui-shell EventsPanel-format requirement MODIFIED — three
bullets + one scenario example flip from `joined` to `seen` and
note why the verb matters.

Tests: 3 string-assertion flips in test_tui_helpers.py
(device/service/host joined -> seen). 768 pytest passed, snapshot
regression green, both openspec validates clean.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chenchaoyi

CHANGELOG.md

@@ -12,6 +12,8 @@ behaviours between releases.
 ## [Unreleased]
 
 ### Fixed
+- **Events panel said "joined" but the events are `*_seen`.** EN UI rendered `ble_device_seen` / `bonjour_service_seen` / `lan_host_seen` as `[BLE] device joined:` / `[BJ] service joined:` / `[LAN] host joined:`. ZH already said `设备出现 / 服务出现 / 主机出现` (appeared / seen). The JSONL `type` field always said `*_seen`. The EN wording also lied about semantics — "joined" reads like *paired / associated*, but the event fires on the first passive observation, including strangers' phones walking past. Renamed three EN i18n keys to `device seen: ` / `service seen: ` / `host seen: `; ZH unchanged.
+- **Events filter footer claimed `1/2/3/4/0`; A1 added `5/6/7`.** The EventsScreen filter cycle has eight buckets since A1 (`ble` / `bonjour` / `lan` on keys `5` / `6` / `7`), the bindings work, but four user-facing strings — events-modal footer and help-modal "Events modal (m)" paragraph, EN + ZH — still listed only the legacy five keys. Extended to `1/2/3/4/5/6/7/0` in both locales so the new filters are discoverable from the TUI alone.
 - **BLE `ble_device_left` re-emission bug.** A device at the edge of range whose adverts the macOS Bluetooth stack briefly stopped delivering would TTL-evict, re-populate `_devices` from the next advert, evict again, and re-emit `BLEDeviceLeftEvent` on every cycle. One identifier in a real 5.6 h capture produced 229 left events from a single seen — 67,548 BLE events / 13 MB JSONL for the session. `BLEPoller._detect_transitions` now gates left-emission on a per-session `_departed_identifiers` set: at most one left per seen, identifier silent for the rest of the session after departure. JSONL size for the captured session drops ~63%.
 
 ## [1.4.0] — 2026-05-21

docs/zh/CHANGELOG.md

@@ -11,6 +11,8 @@
 ## [Unreleased]
 
 ### 修复
+- **事件面板英文写「joined」、但事件其实是 `*_seen`。** EN UI 把 `ble_device_seen` / `bonjour_service_seen` / `lan_host_seen` 渲染成 `[BLE] device joined:` / `[BJ] service joined:` / `[LAN] host joined:`，但 ZH 一直是 `设备出现 / 服务出现 / 主机出现`，JSONL `type` 字段一直是 `*_seen`。"joined" 还会让人误以为「配对 / 关联」—— 实际事件触发的是首次被动观察到，包括路过的陌生人手机。把三个 EN i18n key 改为 `device seen: ` / `service seen: ` / `host seen: `；ZH 不变。
+- **事件过滤页脚仍写 `1/2/3/4/0`，A1 早就加了 `5/6/7`。** EventsScreen 过滤循环自 A1 起已经是八桶（`ble` / `bonjour` / `lan` 绑定到 `5` / `6` / `7`），按键也接好了，但事件弹窗页脚 + 帮助弹窗里的「Events modal (m)」段落（EN + ZH 共四处）还在只列旧的五个键。统一改为 `1/2/3/4/5/6/7/0`，让新加的过滤桶在 TUI 里就能被发现。
 - **BLE `ble_device_left` 重复发送的 bug。** 范围边缘的设备如果广播被 macOS 蓝牙栈短暂卡掉一次，会触发 TTL 失效；紧接着下一条广播又把 `_devices` 填回去、再失效、再发 `BLEDeviceLeftEvent`，循环不止。真实 5.6 小时抓取里有一个 identifier 从单个 seen 派生了 **229** 个 left 事件，整个会话产出 67,548 个 BLE 事件 / 13 MB JSONL。`BLEPoller._detect_transitions` 现在用会话级 `_departed_identifiers` 集合给 left-emission 加门：一个 seen 最多对应一个 left，发完之后该 identifier 本会话内静音。该抓取的 JSONL 体积下降约 63%。
 
 ## [1.4.0] — 2026-05-21

openspec/changes/align-events-vocabulary/design.md

@@ -0,0 +1,97 @@
+# design — align-events-vocabulary
+
+## Why bundle the two findings
+
+Both findings are A1-era cleanup: the seen-side EN wording and
+the filter-keys hint both got written when the cycle had five
+buckets, before the three new transition event types were added.
+They touch the same `i18n.py` / `tui.py` files and the same
+spec section. Shipping them in one PR avoids a second
+re-translation cycle for a one-string change.
+
+## i18n key rename, not value-only edit
+
+The catalog entries are `"device joined: "` → `"设备出现："`. The
+ZH value is already correct. So the change is on the EN side —
+the catalog key (which is also the EN-rendered string in
+diting's i18n model).
+
+The clean way to do this:
+
+```python
+# i18n.py — was
+"device joined: ": "设备出现：",
+"service joined: ": "服务出现：",
+"host joined: ": "主机出现：",
+
+# becomes
+"device seen: ": "设备出现：",
+"service seen: ": "服务出现：",
+"host seen: ": "主机出现：",
+```
+
+Call sites at `tui.py:1947, 1970, 1993` flip from
+`t("device joined: ")` → `t("device seen: ")` etc.
+
+If any old build reads a JSONL log produced by a new build,
+the analyzer is locale-stable English keys (`ble_device_seen`)
+— the renamed UI string never enters the log. No back-compat
+concern there.
+
+## Filter-keys hint wording
+
+Current: `Press 1/2/3/4/0 to filter; m or Esc to close`.
+
+Three options for the extended form:
+
+1. **Explicit:** `Press 1/2/3/4/5/6/7/0 to filter; m or Esc to close`
+2. **Range:** `Press 1–7 to filter, 0 to clear; m or Esc to close`
+3. **Implicit:** `Press 1–7/0 to filter; m or Esc to close`
+
+(1) is the obvious extension and what the audit recommended.
+(2) and (3) are more compact, but `1–7` is less mechanically
+discoverable than the keys-as-digits list — a user scanning the
+footer for which key sets `lan` does not learn that 7 is the
+answer without trying. (1) wins on user discoverability.
+
+Same expansion applies to the help-modal prose at
+`tui.py:612` / `i18n.py:880, 886`. ZH counterpart at
+`i18n.py:1249` likewise.
+
+## What the spec MUST change
+
+`openspec/specs/tui-shell/spec.md:135-147` lists the seven A1
+types' rendered formats with `device joined` / `service joined`
+/ `host joined`. Three bullets and one scenario example flip
+to `seen`. Everything else in the requirement stays.
+
+The filter-cycle requirement at `spec.md:96-117` is already
+correct (it lists the eight buckets and the scenarios). The
+audit-finding is about the prose hint, not the spec — no spec
+change needed for finding #2.
+
+## Test changes
+
+Three string-only flips in `test_tui_helpers.py`:
+
+- `:2659` `assert "device joined" in text` → `assert "device seen" in text`
+- `:2692` `assert "service joined" in text` → `assert "service seen" in text`
+- `:2725` `assert "host joined" in text` → `assert "host seen" in text`
+
+No new tests needed for the i18n side — the existing tests
+exercise the formatter end-to-end.
+
+For finding #2, the audit recommends no new test — the prose
+itself is review-enforced (per TESTING.md row 362 for EN, 353
+for ZH: "HelpScreen content review-enforced"). Adding a
+string-pinning test would couple the test to specific phrasing
+that may drift later; not worth the maintenance cost.
+
+## What this change does NOT touch
+
+- The JSONL `type` field. Already locale-stable English.
+- The `tui-shell` filter-cycle requirement (unchanged — only
+  the prose-hint is stale, not the spec).
+- The `events` capability spec. Untouched.
+- The analyzer or any cross-session aggregation. Unaffected.
+- ZH catalog values. Already correct.

openspec/changes/align-events-vocabulary/proposal.md

@@ -0,0 +1,73 @@
+# align-events-vocabulary
+
+## Why
+
+A TUI audit on 2026-05-21 with `DITING_LANG=en` and
+`DITING_LANG=zh` flagged two A1-era post-ship issues:
+
+**1. EN UI says "joined" but the event is `*_seen`.** Every
+`ble_device_seen` / `bonjour_service_seen` / `lan_host_seen`
+event renders in EN as `device joined: ` / `service joined: ` /
+`host joined: `. ZH translates the same EN keys to `设备出现：`
+/ `服务出现：` / `主机出现：` — i.e. "appeared / seen". The
+JSONL `type` field, the BLEPoller's internal vocabulary, the
+spec's MODIFIED requirement landed in fix-ble-left-dedup all
+say "seen". "Joined" reads like *paired / associated* — but
+the event fires on the first passive observation, including
+random strangers' phones walking past. The EN wording is
+misleading and disagrees with ZH and the JSONL schema. EN and
+ZH agree on the sibling `*_left` events (`device left` /
+`设备消失`), so only the seen-side has drifted.
+
+**2. Events-filter docs claim 1/2/3/4/0; A1 added 5/6/7.**
+The EventsScreen filter cycle has eight buckets since A1 —
+`tui.py:782-784` binds `5` / `6` / `7` to `ble` / `bonjour` /
+`lan` and `action_set_filter` accepts them. The bindings work.
+But four user-facing strings still say "1/2/3/4/0":
+
+- `src/diting/tui.py:884` — events-modal footer hint
+- `src/diting/i18n.py:1248-1249` — that footer's ZH value
+- `src/diting/tui.py:612` — help-modal "Events modal (m)" paragraph
+- `src/diting/i18n.py:880, 886` — the help-modal paragraph EN + ZH
+
+The new BLE / Bonjour / LAN filters are undiscoverable without
+reading the source. (The HelpScreen test
+`test_events_screen_filter_cycle_has_eight_buckets` asserts the
+filter-bucket cycle has eight entries, but not that the key-list
+in the prose matches.)
+
+## What changes
+
+- Rename three EN i18n catalog keys to match the canonical event
+  vocabulary: `device joined: ` → `device seen: `,
+  `service joined: ` → `service seen: `, `host joined: ` →
+  `host seen: `. ZH values are unchanged (`设备出现` etc. already
+  mean "appeared / seen").
+- Update the call sites in `tui.py:1947`, `:1970`, `:1993`.
+- Extend the four "1/2/3/4/0" strings to "1/2/3/4/5/6/7/0" (or
+  a more compact phrasing — see design.md).
+- Update the `tui-shell` spec: the EventsPanel format bullets
+  for the seven A1-added types switch from `joined` to `seen`,
+  and the scenario example matches.
+- Update three existing tests in `test_tui_helpers.py` that
+  assert the old wording.
+
+## Impact
+
+- **EN UI** — three lines in the events panel and one events-modal
+  footer hint change wording. No layout / width change.
+- **JSONL log** — untouched; the canonical event type names
+  (`ble_device_seen` etc.) are already correct and remain
+  load-bearing identifiers.
+- **ZH UI** — no change. ZH already used "出现" / "appeared / seen"
+  for the seen events.
+- **Spec** — `tui-shell` MODIFIED requirement around EventsPanel
+  formatting. No new requirement, no removed requirement.
+- **Tests** — three string-assertion flips. No semantic change.
+
+## Affected code
+
+- `src/diting/i18n.py` — three i18n keys + filter-footer hints
+- `src/diting/tui.py:612, 884, 1947, 1970, 1993`
+- `tests/test_tui_helpers.py:2659, 2692, 2725`
+- `openspec/specs/tui-shell/spec.md:135-147` (delta target)

openspec/changes/align-events-vocabulary/specs/tui-shell/spec.md

@@ -0,0 +1,37 @@
+## MODIFIED Requirements
+
+### Requirement: EventsPanel SHALL format the twelve event types with type-prefix tags
+`EventsPanel.append_event` SHALL render each event with a leading bracket-tag identifying its type, followed by a short type-specific summary. The full tag set is:
+
+| Tag | Event type(s) |
+|---|---|
+| `[ROAM]` | `roam` |
+| `[STIR]` | `rf_stir` |
+| `[LATENCY]` | `latency_spike` |
+| `[LOSS]` | `loss_burst` |
+| `[LINK]` | `link_state` |
+| `[BLE]` | `ble_device_seen` / `ble_device_left` (NEW) |
+| `[BJ]` | `bonjour_service_seen` / `bonjour_service_left` (NEW) |
+| `[LAN]` | `lan_host_seen` / `lan_host_left` / `lan_host_dhcp_rotation` (NEW) |
+
+The seven new event types' rendered formats:
+
+- `[BLE] device seen: <vendor> · <name>` (or `(unknown)` / `(anonymous)` when blank)
+- `[BLE] device left: <vendor> · <name> · <duration>`
+- `[BJ] service seen: <category> · <host>` (or `(unknown)` when category blank)
+- `[BJ] service left: <category> · <host> · <duration>`
+- `[LAN] host seen: <vendor> · <name-or-ip>` (`name` = bonjour_name OR hostname OR IP)
+- `[LAN] host left: <vendor> · <name-or-ip> · <duration>`
+- `[LAN] <vendor> · <name-or-ip> moved <previous_ip> → <new_ip>`
+
+The verb "seen" — not "joined" — matches the canonical event type names (`ble_device_seen`, `bonjour_service_seen`, `lan_host_seen`) and the ZH translation (`出现` ≈ "appeared / seen"). These events fire on passive first observation (strangers' phones walking past, mDNS announces on the link, ARP cache entries appearing), NOT on a deliberate user-initiated association.
+
+Each rendered line SHALL be at most one terminal row even on narrow widths; rendering SHALL use `fit_cells` for the long-name segment.
+
+#### Scenario: BLE seen line
+- **WHEN** a `BLEDeviceSeenEvent` with `name="Magic Keyboard"`, `vendor="Apple, Inc."` flows through `append_event`
+- **THEN** the EventsPanel surfaces a line `[BLE] device seen: Apple, Inc. · Magic Keyboard`
+
+#### Scenario: LAN DHCP rotation line
+- **WHEN** a `LANHostDHCPRotationEvent` with `mac="de:ad:be:ef:00:01"`, `vendor="Apple, Inc."`, `bonjour_name="ccy-MBP24-M4-Office"`, `previous_ip="192.168.1.42"`, `new_ip="192.168.1.77"` flows through `append_event`
+- **THEN** the line is `[LAN] Apple, Inc. · ccy-MBP24-M4-Office moved 192.168.1.42 → 192.168.1.77`

openspec/changes/align-events-vocabulary/tasks.md

@@ -0,0 +1,44 @@
+# tasks — align-events-vocabulary
+
+## 1. Spec
+
+- [x] Draft proposal, design, tasks
+- [x] Spec delta in `specs/tui-shell/spec.md`
+      (MODIFIED requirement: EventsPanel format bullets + scenario example
+      flip from `joined` → `seen`)
+
+## 2. Implementation
+
+- [x] `src/diting/i18n.py:1199-1204` — rename three EN keys:
+      `device joined: ` → `device seen: `,
+      `service joined: ` → `service seen: `,
+      `host joined: ` → `host seen: `
+- [x] `src/diting/tui.py:1948, 1971, 1994` — update `t(...)` call sites
+- [x] `src/diting/tui.py:885` — extend events-modal footer:
+      `Press 1/2/3/4/0 to filter` → `Press 1/2/3/4/5/6/7/0 to filter`
+- [x] `src/diting/i18n.py:1248-1249` — ZH translation of the footer
+- [x] `src/diting/tui.py:612` — help-modal "Events modal (m)" paragraph
+- [x] `src/diting/i18n.py:880, 886` — that paragraph EN + ZH
+
+## 3. Tests
+
+- [x] `tests/test_tui_helpers.py:2659` — `"device joined"` → `"device seen"`
+- [x] `tests/test_tui_helpers.py:2692` — `"service joined"` → `"service seen"`
+- [x] `tests/test_tui_helpers.py:2725` — `"host joined"` → `"host seen"`
+
+## 4. Validation
+
+- [x] `uv run pytest` — 768 passed
+- [x] `uv run python scripts/tui_snapshot.py --mode regression` — green
+- [x] `openspec validate --specs --strict` — 21/21
+- [x] `openspec validate align-events-vocabulary --strict` — valid
+
+## 5. CHANGELOG
+
+- [ ] `CHANGELOG.md` — `## [Unreleased]` → `### Fixed`
+- [ ] `docs/zh/CHANGELOG.md` — mirror EN entry
+
+## 6. Merge + archive
+
+- [ ] PR open, reviewed, merged
+- [ ] `/opsx:archive align-events-vocabulary`

src/diting/i18n.py

@@ -877,14 +877,16 @@ def fit_cells(text: str, target: int) -> str:
     "  Filterable scroll of every event the dashboard has detected:\n"
     "  ROAM (AP switches), STIR (RF disturbance from σ baseline),\n"
     "  LATENCY / LOSS (link probe spikes), LINK (associate /\n"
-    "  disassociate). Use 1/2/3/4/0 to filter by category. Below\n"
-    "  the list: a per-AP σ table summarising which APs are stable\n"
-    "  vs stirring, plus a σ sparkline covering the trailing hour.\n":
+    "  disassociate), plus BLE / BJ / LAN seen-and-left transitions.\n"
+    "  Use 1/2/3/4/5/6/7/0 to filter by category. Below the list: a\n"
+    "  per-AP σ table summarising which APs are stable vs stirring,\n"
+    "  plus a σ sparkline covering the trailing hour.\n":
         "  仪表盘检测到的所有事件可过滤滚动列表：\n"
         "  ROAM（AP 切换）、STIR（基于 σ 基线的 RF 扰动）、\n"
-        "  LATENCY / LOSS（链路探测尖峰）、LINK（关联 / 断开）。\n"
-        "  按 1/2/3/4/0 切换过滤。列表下方：各 AP σ 表，标出哪些 AP\n"
-        "  稳定 / 哪些抖动，以及最近一小时 σ 走势图。\n",
+        "  LATENCY / LOSS（链路探测尖峰）、LINK（关联 / 断开），\n"
+        "  以及 BLE / BJ / LAN 的出现与消失。按 1/2/3/4/5/6/7/0\n"
+        "  切换过滤。列表下方：各 AP σ 表，标出哪些 AP 稳定 / 哪些\n"
+        "  抖动，以及最近一小时 σ 走势图。\n",
     "  Toggle with n. Two sections: Connected (system-paired\n"
     "  peripherals you're actively using — keyboards, AirPods, Magic\n"
     "  Trackpad) and Advertising (everything broadcasting nearby).\n"
@@ -1196,11 +1198,11 @@ def fit_cells(text: str, target: int) -> str:
     "[BLE]": "[BLE]",
     "[BJ]": "[BJ]",
     "[LAN]": "[LAN]",
-    "device joined: ": "设备出现：",
+    "device seen: ": "设备出现：",
     "device left: ": "设备消失：",
-    "service joined: ": "服务出现：",
+    "service seen: ": "服务出现：",
     "service left: ": "服务消失：",
-    "host joined: ": "主机出现：",
+    "host seen: ": "主机出现：",
     "host left: ": "主机消失：",
     " moved ": " 换地址 ",
     "(anonymous)": "(匿名)",
@@ -1245,8 +1247,8 @@ def fit_cells(text: str, target: int) -> str:
     "data ~{n}m": "数据 ~{n}m",
     "(σ history outside the last hour)":
         "(无最近一小时内的 σ 历史)",
-    "Press 1/2/3/4/0 to filter; m or Esc to close":
-        "按 1/2/3/4/0 切换过滤；m 或 Esc 关闭",
+    "Press 1/2/3/4/5/6/7/0 to filter; m or Esc to close":
+        "按 1/2/3/4/5/6/7/0 切换过滤；m 或 Esc 关闭",
 
     # ---- Calibration CLI ----
     "Calibrating environment baseline ({n}s remaining)...":

src/diting/tui.py

@@ -609,9 +609,10 @@ def line(label: str, desc: str) -> None:
         "  Filterable scroll of every event the dashboard has detected:\n"
         "  ROAM (AP switches), STIR (RF disturbance from σ baseline),\n"
         "  LATENCY / LOSS (link probe spikes), LINK (associate /\n"
-        "  disassociate). Use 1/2/3/4/0 to filter by category. Below\n"
-        "  the list: a per-AP σ table summarising which APs are stable\n"
-        "  vs stirring, plus a σ sparkline covering the trailing hour.\n"
+        "  disassociate), plus BLE / BJ / LAN seen-and-left transitions.\n"
+        "  Use 1/2/3/4/5/6/7/0 to filter by category. Below the list: a\n"
+        "  per-AP σ table summarising which APs are stable vs stirring,\n"
+        "  plus a σ sparkline covering the trailing hour.\n"
     ))
 
     section(t("BLE view"))
@@ -881,7 +882,7 @@ def _render_body(self) -> Group:
 
     def _render_footer(self) -> Text:
         line = Text()
-        line.append(t("Press 1/2/3/4/0 to filter; m or Esc to close"),
+        line.append(t("Press 1/2/3/4/5/6/7/0 to filter; m or Esc to close"),
                     style="dim italic")
         return line
 
@@ -1944,7 +1945,7 @@ def _format_ble_device_seen_event(event: BLEDeviceSeenEvent) -> Text:
     line = Text()
     line.append(f"{_ev_ts(event)}  ", style="dim")
     line.append(t("[BLE]") + "  ", style="bold blue")
-    line.append(t("device joined: "), style="white")
+    line.append(t("device seen: "), style="white")
     vendor = event.vendor or t("(unknown)")
     name = event.name or t("(anonymous)")
     line.append(f"{vendor}  ·  {name}", style="white")
@@ -1967,7 +1968,7 @@ def _format_bonjour_service_seen_event(event: BonjourServiceSeenEvent) -> Text:
     line = Text()
     line.append(f"{_ev_ts(event)}  ", style="dim")
     line.append(t("[BJ]") + "  ", style="bold green")
-    line.append(t("service joined: "), style="white")
+    line.append(t("service seen: "), style="white")
     cat = event.category or t("(unknown)")
     host = event.host or t("(anonymous)")
     line.append(f"{cat}  ·  {host}", style="white")
@@ -1990,7 +1991,7 @@ def _format_lan_host_seen_event(event: LANHostSeenEvent) -> Text:
     line = Text()
     line.append(f"{_ev_ts(event)}  ", style="dim")
     line.append(t("[LAN]") + "  ", style="bold cyan")
-    line.append(t("host joined: "), style="white")
+    line.append(t("host seen: "), style="white")
     vendor = event.vendor or (
         t("(random MAC)") if event.is_randomised_mac else t("(unknown)")
     )