fix(frozen): version metadata + mount-time Bonjour prewarm (#55)

Two bugs that surfaced only in the curl-installed v1.0.9 frozen
binary (uv run diting was fine).

1. `--version` printed `diting 0+unknown` and the TUI header
   rendered `diting v0+unknown`. v1.0.9 shipped without
   `--copy-metadata diting` in the PyInstaller invocation, so
   `importlib.metadata.version("diting")` raised
   `PackageNotFoundError` in the frozen build and `__version__`
   fell back to the sentinel. Fix: add `--copy-metadata diting`
   to `scripts/build_frozen.py`. Regression test in
   `tests/test_helper.py::test_frozen_build_copies_diting_metadata`.

2. Pressing `n` to switch to Bonjour hung >1.5 s. The
   "first wifi → BLE" prewarm trigger landed in 1.0.x worked
   on the source build because `.py` file reads release the GIL
   during the actual `open()` syscall. PyInstaller's
   `PyiFrozenImporter` decompresses each module from a PYZ
   archive while holding the GIL throughout, so
   `asyncio.to_thread(_import_bonjour_poller)` doesn't actually
   overlap with the event loop — the import is synchronous from
   the loop's perspective. Fix: move the prewarm trigger from
   `action_toggle_view` to `App.on_mount` so it has the entire
   wifi-view dwell time to amortise. The existing trigger stays
   as an idempotent safety net.

Tests / spec:
- `tests/test_tui_smoke.py`: renamed `test_app_constructs_bonjour_panel_lazily`
  to `test_bonjour_prewarms_at_mount`; replaced the
  prewarm-on-wifi-to-BLE test with one that asserts mount-time
  prewarm makes view switches idempotent.
- `_inject_bonjour_devices` now sets `app._paused = True` so the
  mount-time consumer task's first empty yield does not race with
  injected test devices.
- OpenSpec: `prewarm-bonjour-at-mount` modifies the mdns-scanning
  capability's prewarm trigger from "first wifi → BLE" to
  "TUI mount". Validates strict.

Version bumped to 1.0.10 with EN + ZH CHANGELOG entries.

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

Author: chenchaoyi

CHANGELOG.md

@@ -9,6 +9,41 @@ the project follows [Semantic Versioning](https://semver.org/) where
 practical. The leading `v0.x` line is allowed to break minor
 behaviours between releases.
 
+## [1.0.10] — 2026-05-14
+
+Two fixes that surface only in the curl-installed frozen binary
+(not in `uv run diting`).
+
+### Fixed
+- **Frozen binary's `--version` and TUI title now report the real
+  version.** v1.0.9 shipped without `--copy-metadata diting` in the
+  PyInstaller invocation, so `importlib.metadata.version("diting")`
+  raised `PackageNotFoundError` in the frozen build and
+  `__version__` fell back to `"0+unknown"`. Result: `diting
+  --version` printed `diting 0+unknown` and the TUI header rendered
+  `diting v0+unknown`. Adding `--copy-metadata diting` to
+  `scripts/build_frozen.py` packs the dist-info into the frozen
+  archive. Regression test in `tests/test_helper.py` guards against
+  the flag being removed again.
+- **Bonjour prewarm now starts at TUI mount, not on first
+  wifi → BLE.** The "first wifi → BLE" trigger landed in
+  1.0.x worked on the source build because `.py` file reads release
+  the GIL during the actual `open()` syscall, so the prewarm
+  worker overlapped with the BLE view's reading time. PyInstaller's
+  `PyiFrozenImporter` decompresses modules from a PYZ archive
+  inside pure-Python code that holds the GIL throughout — so
+  `asyncio.to_thread` doesn't help, and users on v1.0.9 saw the
+  second `n` press (BLE → mDNS) hang for >1.5 s. Moving the
+  trigger to `App.on_mount` gives the prewarm the entire wifi-view
+  dwell time to amortise, which is plenty.
+
+### Spec / breaking-ish note
+The `mdns-scanning` capability's "user who only uses Wi-Fi view
+never imports zeroconf" guarantee no longer holds — every TUI
+session now imports zeroconf at mount. The cost runs in a worker
+so there's no user-visible slowdown; the change is documented in
+the `prewarm-bonjour-at-mount` OpenSpec change.
+
 ## [1.0.9] — 2026-05-14
 
 Small, useful: a way to tell what version of diting you're running.

docs/zh/CHANGELOG.md

@@ -8,6 +8,35 @@
 [Semantic Versioning](https://semver.org/)。`v0.x` 阶段允许破坏性的次要
 行为变更。
 
+## [1.0.10] — 2026-05-14
+
+两个只在 curl 装的冻结 binary 里出现的 bug（`uv run diting` 都没有）。
+
+### 修复
+- **冻结 binary 的 `--version` 和 TUI 标题现在能正确显示版本号了。**
+  v1.0.9 漏了 PyInstaller 的 `--copy-metadata diting`，导致冻结
+  binary 里 `importlib.metadata.version("diting")` 抛
+  `PackageNotFoundError`，`__version__` 兜底到 `"0+unknown"`。
+  结果：`diting --version` 打印 `diting 0+unknown`，TUI 顶部也是
+  `diting v0+unknown`。在 `scripts/build_frozen.py` 里加上
+  `--copy-metadata diting` 就把 dist-info 打进了冻结归档。
+  `tests/test_helper.py` 里加了回归测试，避免再被移掉。
+- **Bonjour 预热改成在 TUI mount 时启动，不再等到第一次按
+  wifi → BLE。** 1.0.x 时落的「第一次离开 Wi-Fi 视图触发预热」对
+  源码安装路径有效，因为 `.py` 文件读 IO 时 CPython 会释放 GIL，
+  预热 worker 能和 BLE 视图的浏览时间重叠。但 PyInstaller 的
+  `PyiFrozenImporter` 从 PYZ 归档解压模块时全程持 GIL，
+  `asyncio.to_thread` 并帮不上忙——所以 v1.0.9 用户在按第二次
+  `n`（BLE → mDNS）时会卡 1.5 s 以上。把触发点改到
+  `App.on_mount`，预热就拿到了整个 Wi-Fi 视图浏览时间窗口，足够
+  把成本平摊掉。
+
+### Spec 说明
+`mdns-scanning` 能力之前保证「只看 Wi-Fi 视图的用户从不 import
+zeroconf」，这条不再成立——每次 TUI 启动都会在 mount 时 import
+zeroconf。这部分跑在 worker 上，用户看不到延迟；变更记录在
+OpenSpec change `prewarm-bonjour-at-mount`。
+
 ## [1.0.9] — 2026-05-14
 
 小但有用：一个查 diting 当前版本号的口子。

openspec/changes/prewarm-bonjour-at-mount/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14

openspec/changes/prewarm-bonjour-at-mount/proposal.md

@@ -0,0 +1,52 @@
+## Why
+
+The Bonjour prewarm trigger landed in v1.0.x was "first time the
+user leaves the Wi-Fi view" — i.e. the wifi → BLE step. That
+window is long enough on the source-installed `uv run diting` build
+(`asyncio.to_thread(import …)` actually overlaps with the BLE
+view's reading time because `.py` file reads release the GIL during
+`open()`).
+
+It's not enough for the **PyInstaller-frozen binary** (the curl-
+install path). PyInstaller's `PyiFrozenImporter` decompresses each
+imported module from a PYZ archive inside pure-Python code that
+holds the GIL the entire time. So `asyncio.to_thread` doesn't help
+— the import is effectively synchronous from the event loop's
+perspective. Users on the curl-installed v1.0.9 see the second `n`
+press (BLE → mDNS) hang for >1.5 s while zeroconf is still being
+unpacked.
+
+## What Changes
+
+- The Bonjour prewarm SHALL be triggered at TUI mount, not on the
+  first wifi → BLE step. `App.on_mount` calls
+  `_ensure_mdns_poller()` after scheduling the other pollers.
+- The existing wifi → BLE call from `action_toggle_view` stays as
+  a safety net (idempotent gate handles it).
+- **BREAKING (spec only)**: the previous requirement "user who
+  only uses Wi-Fi view never imports zeroconf" no longer holds.
+  Every TUI session imports zeroconf at mount. Acceptable: the
+  cost is amortised over the user's first ~5 s of reading the
+  wifi view, which is dominated by their cognitive load, not the
+  app's CPU.
+
+## Capabilities
+
+### New Capabilities
+<!-- none -->
+
+### Modified Capabilities
+- `mdns-scanning`: prewarm trigger moves from "first wifi → BLE"
+  to "TUI mount". Same underlying mechanism (idempotent
+  `_ensure_mdns_poller` + worker), just earlier.
+
+## Impact
+
+- `src/diting/tui.py`: one new call (`self._ensure_mdns_poller()`)
+  at the end of `App.on_mount`.
+- `tests/test_tui_smoke.py`: rename / rewrite the two
+  Bonjour-lazy tests to reflect mount-time prewarm; update the
+  `_inject_bonjour_devices` helper to pause polling so the
+  mount-time consumer task can't overwrite the injection.
+- Same applies for the source build but the wifi-only-user
+  optimisation it removes was always a minor savings.

openspec/changes/prewarm-bonjour-at-mount/specs/mdns-scanning/spec.md

@@ -0,0 +1,25 @@
+## MODIFIED Requirements
+
+### Requirement: `zeroconf` dependency SHALL be lazy-imported at the module boundary and pre-warmed at TUI mount
+`from zeroconf import ...` SHALL appear ONLY inside `src/diting/mdns.py` and SHALL be top-level inside that module (not function-local). `src/diting/tui.py` SHALL NOT `import diting.mdns` at module load.
+
+The TUI SHALL trigger the first import of `diting.mdns` (and the construction of a `BonjourPoller`) at TUI mount — `App.on_mount` SHALL call `_ensure_mdns_poller()` after scheduling the other pollers. The pre-warm SHALL run on a worker (`run_worker` + `asyncio.to_thread` for the slow stages) so the visible Wi-Fi view renders immediately and the user's first ~5 s of reading the wifi panel amortises the zeroconf import + multicast socket setup. The `action_toggle_view` call into `_ensure_mdns_poller()` SHALL remain as an idempotent safety net but is a no-op once the mount-time prewarm has fired.
+
+**Why mount-time instead of "first wifi → BLE"**: the PyInstaller-frozen binary's `PyiFrozenImporter` decompresses each imported module from a PYZ archive while holding the GIL throughout, so `asyncio.to_thread` cannot overlap the import with the event loop. The previous "first leaving Wi-Fi" trigger gave the frozen build only the ~2 s of BLE-view reading time to absorb a 1.5+ s import; with mount-time prewarm, the entire wifi-view dwell time is available. The source `uv run` build benefits too — the import overlaps with TUI initial paint instead of with a view switch.
+
+#### Scenario: TUI mount kicks off the Bonjour prewarm
+- **WHEN** the user launches the TUI
+- **THEN** `App.on_mount` schedules a worker that imports `diting.mdns`, constructs a `BonjourPoller`, and begins the consumer task — all off the asyncio event loop
+- **AND** the Wi-Fi panel renders immediately, with no perceptible pause attributable to Bonjour startup
+
+#### Scenario: User cycles wifi → BLE → mDNS for the first time
+- **WHEN** the user presses `n` once (wifi → BLE)
+- **THEN** the BLE view appears immediately; the mount-time prewarm is either complete or in flight
+- **WHEN** the user presses `n` a second time (BLE → mDNS)
+- **THEN** the mDNS panel is shown immediately (the poller is ready since it has had the entire wifi-view dwell time to initialise)
+- **AND** subsequent `n` cycles back to mDNS reuse the same poller (no re-instantiate)
+
+#### Scenario: User never leaves Wi-Fi view
+- **WHEN** the user runs `diting` and never presses `n`
+- **THEN** zeroconf is still imported at mount (background worker), but no user-visible cost is incurred — the work happens concurrently with the user reading the wifi view
+- **AND** no mDNS-related UI is shown

openspec/changes/prewarm-bonjour-at-mount/tasks.md

@@ -0,0 +1,21 @@
+## 1. Move the prewarm trigger
+
+- [x] 1.1 In `src/diting/tui.py` `App.on_mount`, add `self._ensure_mdns_poller()` after the LatencyPoller worker block. Keep the existing `action_toggle_view` call as an idempotent no-op fallback.
+
+## 2. PyInstaller version metadata (related fix that ships in same release)
+
+- [x] 2.1 Add `--copy-metadata diting` to the PyInstaller invocation in `scripts/build_frozen.py` so `importlib.metadata.version("diting")` resolves in the frozen binary (v1.0.9 shipped with this missing, producing `diting v0+unknown` in the TUI title).
+- [x] 2.2 Add a regression test in `tests/test_helper.py` asserting `scripts/build_frozen.py` still contains the `--copy-metadata diting` flag.
+
+## 3. Tests
+
+- [x] 3.1 Rename `test_app_constructs_bonjour_panel_lazily` → `test_bonjour_prewarms_at_mount` and assert `_mdns_starting` or `_mdns_poller` is set right after mount.
+- [x] 3.2 Rewrite `test_bonjour_prewarms_on_first_wifi_to_ble_switch` → `test_bonjour_view_switch_is_idempotent_after_mount_prewarm` to assert pressing `n` after the mount-time prewarm does not replace the poller.
+- [x] 3.3 Update `_inject_bonjour_devices` in `tests/test_tui_smoke.py` to set `app._paused = True` so the mount-time consumer task's first empty yield does not overwrite injected devices.
+
+## 4. Gates
+
+- [x] 4.1 `uv run pytest` passes.
+- [x] 4.2 `uv run python scripts/tui_snapshot.py --mode regression` passes.
+- [x] 4.3 `openspec validate --specs --strict` passes.
+- [x] 4.4 `openspec validate prewarm-bonjour-at-mount --strict` passes.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "diting"
-version = "1.0.9"
+version = "1.0.10"
 description = "macOS terminal listening post for Wi-Fi, BLE, link health, and the RF environment — your Mac hears more than it tells you"
 readme = "README.md"
 license = "MIT"

scripts/build_frozen.py

@@ -104,6 +104,15 @@ def main() -> None:
         # data files. They live under src/diting/data/ and are read
         # via importlib.resources at runtime.
         "--add-data", f"{REPO_ROOT / 'src' / 'diting' / 'data'}:diting/data",
+        # Ship the `diting` package's own dist-info so
+        # `importlib.metadata.version("diting")` can resolve at
+        # runtime. Without this, the frozen binary's __version__
+        # falls back to "0+unknown" (which is what v1.0.9 shipped:
+        # `diting --version` printed `diting 0+unknown` and the TUI
+        # title rendered `diting v0+unknown`). PyInstaller does not
+        # copy a package's metadata by default — only modules and
+        # data files referenced by static analysis.
+        "--copy-metadata", "diting",
         # PyInstaller needs to know where to find the `diting`
         # package since the entry stub imports it. Pointing
         # --paths at src/ lets the analyzer walk the package

src/diting/tui.py

@@ -4380,6 +4380,19 @@ async def on_mount(self) -> None:
                 exclusive=False,
                 name="latency",
             )
+        # Pre-warm Bonjour as soon as the TUI mounts. The earlier
+        # "first time leaving Wi-Fi" trigger gave the source build
+        # enough window to absorb the `from .mdns import ...` import
+        # in `asyncio.to_thread`, but the PyInstaller-frozen binary's
+        # PyiFrozenImporter holds the GIL for the entire 1-2 s of
+        # decompression — `asyncio.to_thread` doesn't help there
+        # because the worker thread isn't actually I/O-blocked. By
+        # kicking off the prewarm at mount, the wifi view's reading
+        # time amortises the cost across both builds. The gate in
+        # `_ensure_mdns_poller` stays idempotent, so the explicit
+        # call from `action_toggle_view` (kept for safety) is a
+        # no-op after this.
+        self._ensure_mdns_poller()
 
     def on_unmount(self) -> None:
         # Flush + close the JSONL log on TUI exit so the file is

tests/test_helper.py

@@ -546,3 +546,21 @@ def test_helper_bundle_declares_appicon_and_ships_iconset():
     present = {p.name for p in iconset.iterdir() if p.suffix == ".png"}
     missing = required - present
     assert not missing, f"AppIcon.iconset is missing sizes: {sorted(missing)}"
+
+
+def test_frozen_build_copies_diting_metadata():
+    """The PyInstaller-frozen binary MUST ship `diting`'s dist-info
+    so `importlib.metadata.version("diting")` resolves at runtime.
+    Without it, the frozen binary's __version__ falls back to
+    `0+unknown` — v1.0.9 shipped this way and the TUI title rendered
+    `diting v0+unknown`. Guard against regression by asserting the
+    build script still passes `--copy-metadata diting`."""
+    repo_root = Path(__file__).resolve().parent.parent
+    build_script = repo_root / "scripts" / "build_frozen.py"
+    assert build_script.exists()
+    text = build_script.read_text(encoding="utf-8")
+    assert '"--copy-metadata"' in text and '"diting"' in text, (
+        "scripts/build_frozen.py must pass `--copy-metadata diting` "
+        "to PyInstaller so the frozen binary can read its own version "
+        "via importlib.metadata. See the v1.0.9 -> v1.0.10 fix."
+    )