pgntui 0.2.2__tar.gz → 0.3.0__tar.gz

{pgntui-0.2.2 → pgntui-0.3.0}/.github/workflows/release.yml

@@ -6,8 +6,23 @@ on:
     tags: ["v*"]
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev,dist]"
+      - run: python -m ruff check src/ tests/
+      - run: python -m ruff format --check src/ tests/
+      - run: python -m mypy src/pgntui
+      - run: python -m pytest tests/ -v
+
   pypi:
+    needs: test
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       id-token: write
       contents: read
@@ -21,6 +36,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
 
   binaries:
+    needs: test
     strategy:
       fail-fast: false
       matrix:
@@ -38,6 +54,7 @@ jobs:
             arch: x86_64
             asset: pgntui-windows-x86_64.exe
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
     permissions:
       contents: write
     steps:
@@ -54,6 +71,7 @@ jobs:
   homebrew_winget:
     needs: [pypi, binaries]
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
       - name: Update homebrew tap stub (manual follow-up to phobicdotno/homebrew-tap)

pgntui-0.3.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-06-04
+
+Bedtime audit fix wave: concurrency, decoding, packaging, recording, platform paths,
+validation, and CI gating. Captures audits A/B/C/D from `docs/audits/2026-06-04-*`.
+
+### Added
+- Fast-packet reassembly for multi-frame PGNs (GNSS, AIS, wind, etc.).
+- Per-OS default workspace via `platformdirs` (Windows %APPDATA%, macOS Application Support, Linux XDG).
+- `--check` headless smoke flag and `--example` workspace scaffolder wiring.
+- `[project.urls]` (Homepage, Source, Bug Tracker, Changelog) so PyPI page is non-empty.
+- Expanded README and new `packaging/README.md` documenting manual homebrew/winget release steps.
+- Threshold field float coercion in signal loader.
+- Test: worker-cancel-on-quit lifecycle.
+- Test: `_writer` race / close-during-write.
+- Test: recording byte-perfect roundtrip incl. priority + destination.
+- Test: container loader rejects overlapping placements.
+- Test: theme loader validates gradient stops (empty / single / malformed hex).
+
+### Fixed
+- canboat `Offset` now applied (23 AC power PGN fields were 2 GW off).
+- Router no longer silently cross-contaminates when binding expects Instance but frame has none.
+- EMA smoothing direction documented (formula clarified vs. standard convention).
+- `_writer` race between worker write and main close.
+- NGT-1 and replay drivers now honor a stop event instead of looping forever.
+- SIGINT (Ctrl+C) closes the recording writer so the tail isn't lost.
+- Worker thread is cancelled on app quit instead of being orphaned.
+- Recording on Windows no longer emits CRLF (LF-only line endings).
+- TOML config syntax errors now surface a clean message instead of a raw traceback.
+- PyInstaller spec bundles `examples/` so `--example` works in the binary.
+- PyInstaller spec includes `copy_metadata` so `entry_points` (drivers) survive in the binary.
+
+### Changed
+- `textual>=8.0` (was `>=0.80`, too loose for actual API usage).
+- `Frame` now carries `priority` and `destination` for byte-perfect recording roundtrips.
+- Default workspace path moved per OS — see release notes for migration.
+
+### CI / Tooling
+- Release workflow now has `timeout-minutes` on every job (macOS-13 hangs no longer block release).
+- Release workflow gates PyPI publish behind CI green.
+- Replay timing assertion loosened to remove flake risk on loaded CI.
+
+## [0.2.2] — 2026-06-03
+
+### Added
+- Example scaffolder includes one of each widget kind (analog_out, digital_in, digital_out).
+
+### Fixed
+- `q` now quits immediately.
+- Welcome panel shown for empty workspace.
+- Visible bottom strips restored.
+
+## [0.2.0] — 2026-06-02
+
+### Added
+- Driver → decoder → router → widgets wiring end-to-end.
+- ContainerScreen tabs.
+- Record toggle.
+- `--example` scaffolder.
+
+### Fixed
+- Replay `iter_frames` honors paused flag with sliding resume.
+- Containers mount widgets before setting `column_span`; expose `widgets` dict.
+
+## [0.1.3] — 2026-06-01
+
+### Added
+- `--check` headless flag.
+- PgntuiApp wired into CLI.
+
+### Fixed
+- EMA smoothing previously stored output as raw, causing exponential lag.
+
+## [0.1.2] — 2026-05-31
+
+### Fixed
+- Per-file force-include for theme JSONs in wheel build.
+- `[dist]` extras installed for binary builds.
+
+## [0.1.1] — 2026-05-30
+
+Initial published release.
+
+[0.3.0]: https://github.com/phobicdotno/pgntui/releases/tag/v0.3.0
+[0.2.2]: https://github.com/phobicdotno/pgntui/releases/tag/v0.2.2
+[0.2.0]: https://github.com/phobicdotno/pgntui/releases/tag/v0.2.0
+[0.1.3]: https://github.com/phobicdotno/pgntui/releases/tag/v0.1.3
+[0.1.2]: https://github.com/phobicdotno/pgntui/releases/tag/v0.1.2
+[0.1.1]: https://github.com/phobicdotno/pgntui/releases/tag/v0.1.1

pgntui-0.3.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: pgntui
+Version: 0.3.0
+Summary: Cross-platform TUI for NMEA 2000 with canboat decoding and pluggable drivers
+Project-URL: Homepage, https://github.com/phobicdotno/pgntui
+Project-URL: Source, https://github.com/phobicdotno/pgntui
+Project-URL: Bug Tracker, https://github.com/phobicdotno/pgntui/issues
+Project-URL: Changelog, https://github.com/phobicdotno/pgntui/releases
+Author: phobicdotno
+License: MIT License
+        
+        Copyright (c) 2026 phobicdotno
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: canboat,marine,n2k,nmea2000,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: textual>=8.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: dist
+Requires-Dist: pyinstaller>=6.6; extra == 'dist'
+Description-Content-Type: text/markdown
+
+# pgntui
+
+Cross-platform TUI for NMEA 2000 with canboat decoding.
+
+Read live N2K frames through pluggable drivers, decode them with the
+canboat PGN database, and route values into JSON-defined dashboards. Record
+sessions to `.pgnlog` and replay them later — no boat required.
+
+## Install
+
+The easiest path is `pipx`:
+
+    pipx install pgntui
+
+If your system Python is older than 3.11, point pipx at a newer interpreter:
+
+    pipx install --python python3.12 pgntui
+
+Or run in a project venv:
+
+    python3 -m venv .venv && . .venv/bin/activate
+    pip install pgntui
+
+Standalone single-file binaries for macOS (arm64, x86_64), Linux (x86_64) and
+Windows (x86_64) are attached to each GitHub release.
+
+## Quickstart
+
+Scaffold the example workspace and launch:
+
+    pgntui --example      # writes the example workspace at the OS default location
+    pgntui                # opens the TUI; no driver yet, debug tab will be empty
+
+Replay a recording:
+
+    pgntui replay path/to/session.pgnlog
+
+Run with a real driver — pgntui picks the driver named in `config.toml`:
+
+    pgntui                # uses driver.name from <workspace>/config.toml
+
+## Workspace layout
+
+`pgntui` reads everything from a workspace directory. By default the location
+follows `platformdirs.user_config_dir("pgntui")`:
+
+| OS      | Default workspace                          |
+|---------|--------------------------------------------|
+| Linux   | `~/.config/pgntui`                         |
+| macOS   | `~/Library/Application Support/pgntui`     |
+| Windows | `%APPDATA%\pgntui`                         |
+
+Override with `--workspace <path>` on the command line.
+
+Layout:
+
+    <workspace>/
+      config.toml            # driver + theme + paths
+      signals/*.json         # signal definitions (PGN -> field -> widget)
+      containers/*.json      # dashboard layouts (tab -> grid of signals)
+      recordings/            # .pgnlog files written by the R hotkey
+      logs/                  # CSV exports
+
+Run `pgntui --example` to drop a working sample inside this directory.
+
+## Drivers
+
+Built-in driver entry points (`pgntui.drivers`):
+
+- `actisense-ngt1` — Actisense NGT-1 USB serial gateway (`pyserial`)
+- `file-replay` — replay an Actisense `.pgnlog` capture
+
+Pick one in `config.toml`:
+
+    [driver]
+    name = "actisense-ngt1"
+    port = "/dev/tty.usbserial-XXXX"   # macOS / Linux
+    # port = "COM4"                    # Windows
+    baud = 115200
+
+Third-party drivers can register additional entry points under the
+`pgntui.drivers` group.
+
+## Signal types
+
+Signal JSON files declare how each PGN field renders:
+
+- `analog_in` — gauge / numeric readout (RPM, speed, depth, temperature)
+- `digital_in` — boolean lamp (alarm, anchor light, bilge pump state)
+- `analog_out` — write-back analog control (sends an outbound frame)
+- `digital_out` — write-back toggle (sends an outbound frame)
+
+`analog_out` and `digital_out` need `--enable-write` on the CLI **and**
+`app.write_enabled = true` in `config.toml`; otherwise they render as
+read-only.
+
+## Themes
+
+Six builtins ship in the wheel:
+
+- `dark` (default)
+- `light`
+- `amber-crt`
+- `green-phosphor`
+- `mono-ascii`
+- `rainbow-disco`
+
+Custom themes are JSON files referenced from `config.toml`:
+
+    [app]
+    theme = "dark"
+
+## Replay
+
+Replay an Actisense-format `.pgnlog`:
+
+    pgntui replay capture.pgnlog
+
+The replay driver respects the original frame spacing. Press the `R` hotkey
+inside the TUI to start/stop recording the live stream to a new
+`.pgnlog` file under `<workspace>/recordings/`.
+
+## Hotkeys
+
+    Tab / Shift+Tab     next / previous container tab
+    D                   jump to Debug tab
+    R                   start / stop recording
+    Q / Ctrl+Q          quit immediately
+    ?                   show help line in status bar
+
+## Layout sketch
+
+```
++---------------------------------------------------+
+|  pgntui                                           |
++---------------------------------------------------+
+| [Main] [Engine] [Nav] [Debug]                     |
++---------------------------------------------------+
+|  RPM     1450    Speed   6.8 kn   Depth 12.3 m    |
+|  +----+         +----+           +----+           |
+|  |####|         |##  |           |#   |           |
+|  +----+         +----+           +----+           |
+|                                                   |
+|  Bilge OFF     Anchor Light ON                    |
++---------------------------------------------------+
+| [Tab] Next  [D] Debug  [R] Rec  [Q] Quit          |
+| status: idle                                      |
++---------------------------------------------------+
+```
+
+## Status
+
+Alpha. Reasonable to dogfood on a known-good boat or a bench rig.
+
+- Works: TUI shell, canboat decoder, signal routing, file replay,
+  Actisense NGT-1 driver (read), recording.
+- Partial: NGT-1 write-back is wired but field-tested only against a tiny
+  PGN subset.
+- Not yet: TwoCAN / Yacht Devices native drivers, more layout primitives,
+  per-signal alarm thresholds in the UI.
+
+Bug reports and patches welcome — file an issue at
+<https://github.com/phobicdotno/pgntui/issues>.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Source: <https://github.com/phobicdotno/pgntui>
+- Issues: <https://github.com/phobicdotno/pgntui/issues>
+- Releases: <https://github.com/phobicdotno/pgntui/releases>

pgntui-0.3.0/README.md

@@ -0,0 +1,173 @@
+# pgntui
+
+Cross-platform TUI for NMEA 2000 with canboat decoding.
+
+Read live N2K frames through pluggable drivers, decode them with the
+canboat PGN database, and route values into JSON-defined dashboards. Record
+sessions to `.pgnlog` and replay them later — no boat required.
+
+## Install
+
+The easiest path is `pipx`:
+
+    pipx install pgntui
+
+If your system Python is older than 3.11, point pipx at a newer interpreter:
+
+    pipx install --python python3.12 pgntui
+
+Or run in a project venv:
+
+    python3 -m venv .venv && . .venv/bin/activate
+    pip install pgntui
+
+Standalone single-file binaries for macOS (arm64, x86_64), Linux (x86_64) and
+Windows (x86_64) are attached to each GitHub release.
+
+## Quickstart
+
+Scaffold the example workspace and launch:
+
+    pgntui --example      # writes the example workspace at the OS default location
+    pgntui                # opens the TUI; no driver yet, debug tab will be empty
+
+Replay a recording:
+
+    pgntui replay path/to/session.pgnlog
+
+Run with a real driver — pgntui picks the driver named in `config.toml`:
+
+    pgntui                # uses driver.name from <workspace>/config.toml
+
+## Workspace layout
+
+`pgntui` reads everything from a workspace directory. By default the location
+follows `platformdirs.user_config_dir("pgntui")`:
+
+| OS      | Default workspace                          |
+|---------|--------------------------------------------|
+| Linux   | `~/.config/pgntui`                         |
+| macOS   | `~/Library/Application Support/pgntui`     |
+| Windows | `%APPDATA%\pgntui`                         |
+
+Override with `--workspace <path>` on the command line.
+
+Layout:
+
+    <workspace>/
+      config.toml            # driver + theme + paths
+      signals/*.json         # signal definitions (PGN -> field -> widget)
+      containers/*.json      # dashboard layouts (tab -> grid of signals)
+      recordings/            # .pgnlog files written by the R hotkey
+      logs/                  # CSV exports
+
+Run `pgntui --example` to drop a working sample inside this directory.
+
+## Drivers
+
+Built-in driver entry points (`pgntui.drivers`):
+
+- `actisense-ngt1` — Actisense NGT-1 USB serial gateway (`pyserial`)
+- `file-replay` — replay an Actisense `.pgnlog` capture
+
+Pick one in `config.toml`:
+
+    [driver]
+    name = "actisense-ngt1"
+    port = "/dev/tty.usbserial-XXXX"   # macOS / Linux
+    # port = "COM4"                    # Windows
+    baud = 115200
+
+Third-party drivers can register additional entry points under the
+`pgntui.drivers` group.
+
+## Signal types
+
+Signal JSON files declare how each PGN field renders:
+
+- `analog_in` — gauge / numeric readout (RPM, speed, depth, temperature)
+- `digital_in` — boolean lamp (alarm, anchor light, bilge pump state)
+- `analog_out` — write-back analog control (sends an outbound frame)
+- `digital_out` — write-back toggle (sends an outbound frame)
+
+`analog_out` and `digital_out` need `--enable-write` on the CLI **and**
+`app.write_enabled = true` in `config.toml`; otherwise they render as
+read-only.
+
+## Themes
+
+Six builtins ship in the wheel:
+
+- `dark` (default)
+- `light`
+- `amber-crt`
+- `green-phosphor`
+- `mono-ascii`
+- `rainbow-disco`
+
+Custom themes are JSON files referenced from `config.toml`:
+
+    [app]
+    theme = "dark"
+
+## Replay
+
+Replay an Actisense-format `.pgnlog`:
+
+    pgntui replay capture.pgnlog
+
+The replay driver respects the original frame spacing. Press the `R` hotkey
+inside the TUI to start/stop recording the live stream to a new
+`.pgnlog` file under `<workspace>/recordings/`.
+
+## Hotkeys
+
+    Tab / Shift+Tab     next / previous container tab
+    D                   jump to Debug tab
+    R                   start / stop recording
+    Q / Ctrl+Q          quit immediately
+    ?                   show help line in status bar
+
+## Layout sketch
+
+```
++---------------------------------------------------+
+|  pgntui                                           |
++---------------------------------------------------+
+| [Main] [Engine] [Nav] [Debug]                     |
++---------------------------------------------------+
+|  RPM     1450    Speed   6.8 kn   Depth 12.3 m    |
+|  +----+         +----+           +----+           |
+|  |####|         |##  |           |#   |           |
+|  +----+         +----+           +----+           |
+|                                                   |
+|  Bilge OFF     Anchor Light ON                    |
++---------------------------------------------------+
+| [Tab] Next  [D] Debug  [R] Rec  [Q] Quit          |
+| status: idle                                      |
++---------------------------------------------------+
+```
+
+## Status
+
+Alpha. Reasonable to dogfood on a known-good boat or a bench rig.
+
+- Works: TUI shell, canboat decoder, signal routing, file replay,
+  Actisense NGT-1 driver (read), recording.
+- Partial: NGT-1 write-back is wired but field-tested only against a tiny
+  PGN subset.
+- Not yet: TwoCAN / Yacht Devices native drivers, more layout primitives,
+  per-signal alarm thresholds in the UI.
+
+Bug reports and patches welcome — file an issue at
+<https://github.com/phobicdotno/pgntui/issues>.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Source: <https://github.com/phobicdotno/pgntui>
+- Issues: <https://github.com/phobicdotno/pgntui/issues>
+- Releases: <https://github.com/phobicdotno/pgntui/releases>

pgntui-0.3.0/docs/audits/2026-06-04-audit-A-concurrency.md

@@ -0,0 +1,64 @@
+# Audit A: Concurrency + Lifecycle (2026-06-04)
+Branch: main @ 1f3795d (v0.2.1)
+Auditor: feature-dev:code-reviewer
+
+## Findings
+
+### Finding A-1: Worker thread not cancelled before `self.exit()` — orphaned blocking thread on quit
+- **File:** `src/pgntui/app.py:315-323`
+- **Severity:** P1
+- **What's wrong:** `action_force_quit` calls `self.exit()` without cancelling the `frame_loop` worker first. After the Textual event loop shuts down, the worker thread is still alive blocked inside `NGT1Driver.read_frames()` (loops `while True: byte = self._serial.read(1)` with 0.1s timeout) or inside `_interruptible_sleep` for replay. `call_from_thread` posted by the still-running worker can fire into a dead event loop and raise `RuntimeError`.
+- **Repro:** Press Q during active NGT-1 streaming.
+- **Fix:** `self.get_worker("frame_loop").cancel()` before `self.exit()`; close the driver via existing `finally` block.
+
+### Finding A-2: `_writer` written by main thread, read by worker thread — unsynchronised access
+- **File:** `src/pgntui/app.py:183` (worker reads), `app.py:297-309` (main writes)
+- **Severity:** P1
+- **What's wrong:** Worker `_handle_frame` reads `self._writer`; `action_toggle_record` writes it from event loop. `_stop_recording` calls `close()` and then sets `_writer=None`. Worker can read non-None, enter `writer.write(frame)`, while main closes the file handle mid-write — produces `ValueError: I/O operation on closed file` swallowed by `except Exception: pass`. Data integrity loss.
+- **Repro:** Press R to stop recording while frames arrive rapidly.
+- **Fix:** Add `threading.Lock` protecting `_writer`, OR swap order in `_stop_recording`: null `self._writer` first, then close the local reference.
+
+### Finding A-3: `NGT1Driver.read_frames()` infinite loop — no exit mechanism
+- **File:** `src/pgntui/drivers/actisense.py:102-117`
+- **Severity:** P1
+- **What's wrong:** `while True` with `self._serial.read(1)` timeout-and-continue. Textual `Worker.cancel()` on a `thread=True` worker only sets state and joins with timeout — does NOT inject an exception. Loop only exits when `serial.close()` raises `SerialException`. Timing window between `app.run()` returning and `driver.close()` being called can leak serial port on crash.
+- **Fix:** Add `_stop: threading.Event` to `NGT1Driver`, check inside loop, set in `close()`.
+
+### Finding A-4: `FileReplayDriver.close()` only nulls `_path`; open file handle untracked
+- **File:** `src/pgntui/drivers/replay.py:41-42`
+- **Severity:** P2
+- **What's wrong:** `read_log` opens via `with` (correct), but if `close()` is called mid-iteration, only `_path = None` runs. Generator file handle stays open until GC. No deterministic flush/close.
+- **Fix:** Store generator/handle, explicitly close in `close()`, or add `_stop` event in `_interruptible_sleep`.
+
+### Finding A-5: `ActisenseLogWriter` not closed on Ctrl+C (SIGINT)
+- **File:** `src/pgntui/app.py:315-323`, `src/pgntui/__main__.py:239-246`
+- **Severity:** P2
+- **What's wrong:** `action_force_quit` flushes the writer. Ctrl+C raises `KeyboardInterrupt` past `app.run()`; `main()` `finally` only closes the driver. Recording tail in Python text buffer is lost.
+- **Fix:** In `main()` finally OR via `PgntuiApp.shutdown()`, close `app._writer` if non-None.
+
+### Finding A-6: `AnalogInWidget.update_value` — no documented thread-safety contract
+- **File:** `src/pgntui/signals/widgets.py:20-28`
+- **Severity:** P2 (future-proofing)
+- **What's wrong:** Today only called via `call_from_thread`. No assertion or docstring enforces this. A future direct call from a non-UI thread would race the renderer (two STORE_ATTR for `displayed_value` and `state_class`).
+- **Fix:** Add docstring requiring UI thread, optional `assert` guard.
+
+### Finding A-7: `_interruptible_sleep` — pause leftover_delay analysis
+- **File:** `src/pgntui/drivers/replay.py:52-70`
+- **Severity:** P3 — **no fix required**
+- **Notes:** `remaining` is preserved correctly across pause cycles; `_paused` is a single bool (GIL-atomic). Worst case: 50ms latency on resume.
+
+## Clean
+- `call_from_thread` used correctly for every widget mutation from worker (debug log, widget updates, status)
+- `SignalRouter.route` returns frozen `SignalUpdate`; no shared mutable state
+- `Signal` subclasses frozen+slots — read-only after construction
+- `CSVSignalLogger.log` flushes on every write
+- `ActisenseLogWriter.write` only called from worker (single producer)
+- `NGT1Driver.close()` / `FileReplayDriver.close()` guard `is not None`
+- `_stop_recording` uses try/finally
+- `frame_loop` decorated `exclusive=True` — prevents double-open races
+- Day-boundary rotation closes stale handles synchronously
+
+## Notes
+- `driver.close()` in `main()` finally is the primary backstop; works for normal exit but not `os._exit()`, SIGKILL, hard crash. Acceptable.
+- `_set_status` called from both threads — works because event loop calls direct, worker uses `call_from_thread`. Easy to misread during future edits.
+- `_make_analog_write` / `_make_digital_write` callbacks invoke `_set_status` directly — fine today since Textual widget callbacks fire on event loop, but unsafe if ever invoked from non-UI context.

pgntui-0.3.0/docs/audits/2026-06-04-audit-B-decoding.md

@@ -0,0 +1,72 @@
+# Audit B: Decoding + Routing + Signal Math + Themes + Recording (2026-06-04)
+Branch: main @ 1f3795d (v0.2.1)
+Auditor: feature-dev:code-reviewer
+
+## P1 — wrong output
+
+### B-1: canboat `Offset` never applied — 23 fields silently wrong
+- **File:** `src/pgntui/decode/canboat.py:65-93`
+- **What's wrong:** `_decode_fields` reads `Resolution` but never `Offset`. Canboat schema is `raw * resolution + offset`. 23 fields in pgns.json carry `"Offset": -2000000000` (AC power PGNs 65007/65008/65009 Real Power, Apparent Power, etc.). Without offset, those decode 2 GW too high.
+- **Fix:** `offset_val = float(f.get("Offset") or 0); value = raw * resolution + offset_val`
+
+### B-2: No fast-packet reassembly — multi-frame PGNs silently truncate
+- **File:** `src/pgntui/decode/canboat.py:51-63`; no reassembly layer
+- **What's wrong:** N2K fast-packet PGNs (129029 GNSS, 129025 Position Rapid, 129026 COG/SOG, 129038/129039 AIS, 130306 Wind Data) arrive as a sequence of 8-byte CAN frames with a sequence counter in byte 0. The decoder parses each 8-byte frame independently. For 43-byte PGN 129029, lat/lon/alt all decode to zero or garbage. No `FastPacketReassembler` exists.
+- **Fix:** Add `FastPacketReassembler` keyed by `(source_addr, pgn, sequence_counter)`, strip header bytes, concatenate payload, call `decode()` only when complete.
+
+## P2 — design / semantic flips
+
+### B-3: EMA formula direction inverted relative to standard
+- **File:** `src/pgntui/signals/widgets.py:21-23`
+- **What's wrong:** Code: `displayed = a * self._raw + (1 - a) * value` where `a = smoothing`. Standard EMA: `ema = alpha * new + (1 - alpha) * old`. With `smoothing=0.9` the display weights 90% old / 10% new — heavily smoothed, but opposite direction from standard `alpha`. The Wave 1 fix test `test_smoothing_ema_uses_raw_not_blended` documents this as intentional (works at alpha=0.5 symmetry point).
+- **Fix:** Either rename parameter (`history_weight`?) and document, OR flip the formula to standard EMA. Latter is breaking change. Recommend: document clearly and add a docstring noting the semantic.
+
+### B-4: Router missing-instance allows cross-contamination
+- **File:** `src/pgntui/decode/router.py:41`
+- **What's wrong:** `if key.instance is not None and instance is not None and key.instance != instance: continue` — short-circuits when frame has no Instance field. A signal keyed to instance 2 receives updates from single-engine PGNs with no instance. Port engine bound to instance 0 gets cross-fire.
+- **Fix:** `if key.instance is not None and key.instance != instance: continue` — let None != 2 mismatch.
+
+### B-5: `_FIELD_ALIASES` documentation gap
+- **File:** `src/pgntui/decode/canboat.py:24-28`
+- **What's wrong:** Alias entries are correct for PGN 127488. But users binding `field: "Speed"` thinking it means PGN 128259 "Speed Water Referenced" will see no match (decoder emits the raw canboat name). Documentation/discoverability problem, not a decoder bug.
+- **Fix:** Document the alias table's purpose + how to list canonical field names.
+
+### B-6: Recording priority+destination lossy
+- **File:** `src/pgntui/recording/writer.py:31-43`; `src/pgntui/drivers/base.py`
+- **What's wrong:** `Frame` has no `priority` or `destination`. Writer hardcodes priority "3", destination "255". No roundtrip test verifies byte-perfect fidelity. Future addressed-PGN routing silently breaks.
+- **Fix:** Add optional `priority` + `destination` to Frame dataclass. Update writer/reader. Add roundtrip test.
+
+## P3 — quality
+
+### B-7: Duplicate placement silently passes
+- **File:** `src/pgntui/containers/loader.py:43-55`
+- **What's wrong:** Two `SignalPlacement` entries with overlapping `(row, col, w)` not detected. UI renders one on top of the other silently.
+- **Fix:** Track occupied cells in the validator, raise `ContainerLoadError` on overlap.
+
+### B-8: Theme gradient stops not validated
+- **File:** `src/pgntui/themes/loader.py:61-63`
+- **What's wrong:** No validation of stop count (0/1) or hex format. Degenerate theme produces render failure at runtime instead of load-time error.
+- **Fix:** Validate len(stops) >= 2 and each stop matches `#[0-9a-fA-F]{6}`.
+
+## Clean
+- `_read_bits` LSB-first; truncated payload graceful break
+- Unknown PGN returns None cleanly
+- Signed two's complement correct for any field size
+- Resolution=0 guard with 1.0 fallback
+- Router source=None wildcard correct; source=0 treated as explicit (correct)
+- Router multi-signal routes: `setdefault().append()` accumulates correctly
+- AnalogInWidget smoothing=0 path: bypasses EMA correctly
+- AnalogInWidget first sample bypasses EMA
+- `compute_state` boundary uses `>=` consistently
+- DigitalIn/Out truthy cast via `bool(value)` handles 2/-1/"yes"
+- `read_log` truncated file: parse returns None, generator skips
+- Timestamp precision: microseconds preserved
+- Container cols<=0 / neg coords / grid overflow rejected (tested)
+- 14 required theme colors validated; all 6 builtin themes complete
+- Widget glyphs hardcoded (●─├┤) — missing theme glyph table doesn't break runtime
+
+## Notes
+- B-2 (fast-packet) is the biggest production impact — anyone running GNSS/AIS/wind sees broken decodes silently
+- B-1 (Offset) only hits AC power; most marine TUI users won't notice
+- AnalogInWidget NaN/inf input crashes at `int(NaN * 17)` in `_bar()` — extremely unlikely in real PGN data but worth noting
+- `test_recording_writer.py` has no write→read→compare roundtrip — adding one would surface B-6