rosight 0.1.0__tar.gz

rosight-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+.eggs/
+pip-wheel-metadata/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.python-version
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.hypothesis/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*~
+.DS_Store
+
+# Site
+site/
+
+# Logs / runtime
+*.log
+.rosight/
+*.bag
+*.db3
+*.mcap
+
+# OS
+Thumbs.db

rosight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deyu Fu
+
+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.

rosight-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: rosight
+Version: 0.1.0
+Summary: A lazygit-inspired terminal UI for ROS 2: topics, nodes, services, params, live message inspection and plotting.
+Project-URL: Homepage, https://github.com/deyuf/rosight
+Project-URL: Documentation, https://github.com/deyuf/rosight#readme
+Project-URL: Repository, https://github.com/deyuf/rosight
+Project-URL: Issues, https://github.com/deyuf/rosight/issues
+Author: deyuf
+License-File: LICENSE
+Keywords: monitoring,plotting,robotics,ros2,textual,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: plotext>=5.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.79
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Rosight
+
+[![CI](https://github.com/deyuf/rosight/actions/workflows/ci.yml/badge.svg)](https://github.com/deyuf/rosight/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Rosight** = ROS + sight. A keyboard-driven terminal cockpit for ROS 2.
+
+Browse the live ROS 2 graph — messages, nodes, services, actions, parameters,
+TF, bags, interfaces — and live-plot any numeric field, all from one screen
+without a mouse. Built for SSH, tmux, robot consoles.
+
+![Messages tab](docs/screenshots/01-messages.svg)
+
+## What's inside
+
+Nine tabs, keyboard-driven, all on one screen:
+
+| `#` | Tab | What you can do |
+|---|---|---|
+| `1` | **Messages** | Filter the topic table, `Enter` to subscribe, the right pane shows live hz / bw / jitter and the message tree. Press `i` for static topic info (types, publishers, QoS). |
+| `2` | **Nodes** | Discover every node, drill into its publishers, subscribers, service servers/clients, action servers/clients. |
+| `3` | **Services** | List services with types. `c` opens a call form *(planned)*. |
+| `4` | **Actions** | List action servers with types. Goal monitor *(planned)*. |
+| `5` | **Params** | Browse parameters per node, get / set with type awareness. |
+| `6` | **Plot** | Multi-series live plot of any numeric field — pick a field in the message tree and press `p`. Pause / window-scale / CSV export. |
+| `7` | **TF** | Auto-built frame tree from `/tf` and `/tf_static`. |
+| `8` | **Bags** | `ros2 bag record` / `play` / `info`. The header tells you which key stops the recording while it's running. |
+| `9` | **Interfaces** | Browse `msg` / `srv` / `action` definitions of every interface package on the system. |
+
+### Screenshots
+
+![Nodes tab](docs/screenshots/02-nodes.svg)
+*Nodes (`2`)*
+
+![Services tab](docs/screenshots/03-services.svg)
+*Services (`3`)*
+
+![Actions tab](docs/screenshots/04-actions.svg)
+*Actions (`4`)*
+
+![Bags tab](docs/screenshots/06-bags.svg)
+*Bags (`8`) — recording state*
+
+Cross-cutting features:
+
+- **Auto-QoS** — subscriber profile is negotiated to match every publisher of a topic (BEST_EFFORT vs RELIABLE, TRANSIENT_LOCAL, etc.), so sensor topics "just work".
+- **Theme persistence** — pick a theme via `Ctrl+P → Change theme`; it survives restarts (stored next to your config in a small `state.toml`).
+- **Runtime domain switch** — `:domain 5` reconnects the rclpy backend on a new `ROS_DOMAIN_ID` without restarting the app.
+- **Live notifications** — important actions (subscribed, started recording, switched domain) show as toasts; nothing important hides in a covered status bar.
+- **No ROS required for the UI** — the package imports cleanly without `rclpy`, so you can dev / unit-test on cloud machines. Run with `--no-ros` to stay offline.
+
+## Install
+
+Rosight is not yet on PyPI; install from source:
+
+```bash
+git clone https://github.com/deyuf/rosight
+cd rosight
+pip install -e .
+```
+
+Then, in any terminal where you want to use it:
+
+```bash
+source /opt/ros/<distro>/setup.bash
+rosight
+```
+
+If you maintain multiple distros, source the one whose `rclpy` should drive
+discovery before launching. See [`docs/installation.md`](docs/installation.md)
+for the recommended `--system-site-packages` venv layout that keeps the system
+`rclpy` reachable while pip manages everything else.
+
+## Quick start
+
+```bash
+# launch (inherits ROS_DOMAIN_ID from env)
+rosight
+
+# pick a domain explicitly + log to file
+rosight --domain-id 5 --log-file /tmp/rosight.log
+
+# UI-only mode, no rclpy needed (great for theme / layout dev)
+rosight --no-ros
+```
+
+Inside the app:
+
+- `?` — keyboard reference overlay
+- `:` — command palette (`topic <filter>`, `plot <topic> <path>`, `record`, `domain <N>`, `quit`)
+- `1`–`9` — jump to a tab
+- `q` or `Ctrl+C` — quit
+- `r` — manual refresh
+
+Plotting workflow (the question new users ask most):
+
+1. **Messages tab**, cursor over a topic, **Enter** to subscribe (focus auto-jumps to the message tree)
+2. Use arrow keys / Space to expand fields in the tree
+3. Cursor on a *numeric* leaf (int / float), press **p** — series is added and the Plot tab opens
+
+## Documentation
+
+| Topic | File |
+|-------|------|
+| Installation per distro | [docs/installation.md](docs/installation.md) |
+| Daily usage | [docs/usage.md](docs/usage.md) |
+| Keybindings | [docs/keybindings.md](docs/keybindings.md) |
+| Configuration | [docs/configuration.md](docs/configuration.md) |
+| Plotting deep-dive | [docs/plotting.md](docs/plotting.md) |
+| Architecture | [docs/architecture.md](docs/architecture.md) |
+| Contributing | [docs/development.md](docs/development.md) |
+| FAQ | [docs/faq.md](docs/faq.md) |
+
+## Project layout
+
+```
+src/rosight/
+├── app.py             # Textual App, panel registry, global key bindings
+├── cli.py             # argparse entry point
+├── config.py          # TOML config loader + state.toml persistence
+├── ros/
+│   ├── backend.py     # central rclpy facade (lifecycle, sub mgmt, domain switch)
+│   ├── introspection.py  # dynamic message-type resolution
+│   ├── qos.py         # plain-data QoS + auto-negotiation
+│   └── stats.py       # hz / bw monitors
+├── utils/
+│   ├── datatable.py   # row-cursor preservation + last-column auto-fit
+│   ├── ringbuffer.py  # thread-safe bounded buffers
+│   ├── path.py        # message field-path parser
+│   └── formatting.py  # human-readable display helpers
+└── widgets/           # one file per panel + status bar / help / palette
+```
+
+## Tech stack & rationale — short version
+
+- **Python 3.10+** + **rclpy** (first-class ROS 2 client, dynamic message introspection via `rosidl_runtime_py`)
+- **Textual ≥ 0.79** (modern async TUI, CSS-like styling, headless pilot tests — that's how the 80-test suite stays meaningful for a TUI)
+- **plotext** for ANSI plotting in the Plot tab
+- **hatch + ruff + mypy + pytest-asyncio** for the dev loop
+- **MkDocs Material** for the docs site
+- rclpy runs on its own `MultiThreadedExecutor` daemon thread so DDS spinning never blocks the Textual main loop. See [`DESIGN.md`](DESIGN.md) for the full reasoning.
+
+## Status
+
+Beta. Discovery, subscription, plotting, TF, bag record/play, theme persistence,
+runtime domain switch — all working. Auto-forms for service call and action
+goal are on the roadmap.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

rosight-0.1.0/README.md

@@ -0,0 +1,151 @@
+# Rosight
+
+[![CI](https://github.com/deyuf/rosight/actions/workflows/ci.yml/badge.svg)](https://github.com/deyuf/rosight/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Rosight** = ROS + sight. A keyboard-driven terminal cockpit for ROS 2.
+
+Browse the live ROS 2 graph — messages, nodes, services, actions, parameters,
+TF, bags, interfaces — and live-plot any numeric field, all from one screen
+without a mouse. Built for SSH, tmux, robot consoles.
+
+![Messages tab](docs/screenshots/01-messages.svg)
+
+## What's inside
+
+Nine tabs, keyboard-driven, all on one screen:
+
+| `#` | Tab | What you can do |
+|---|---|---|
+| `1` | **Messages** | Filter the topic table, `Enter` to subscribe, the right pane shows live hz / bw / jitter and the message tree. Press `i` for static topic info (types, publishers, QoS). |
+| `2` | **Nodes** | Discover every node, drill into its publishers, subscribers, service servers/clients, action servers/clients. |
+| `3` | **Services** | List services with types. `c` opens a call form *(planned)*. |
+| `4` | **Actions** | List action servers with types. Goal monitor *(planned)*. |
+| `5` | **Params** | Browse parameters per node, get / set with type awareness. |
+| `6` | **Plot** | Multi-series live plot of any numeric field — pick a field in the message tree and press `p`. Pause / window-scale / CSV export. |
+| `7` | **TF** | Auto-built frame tree from `/tf` and `/tf_static`. |
+| `8` | **Bags** | `ros2 bag record` / `play` / `info`. The header tells you which key stops the recording while it's running. |
+| `9` | **Interfaces** | Browse `msg` / `srv` / `action` definitions of every interface package on the system. |
+
+### Screenshots
+
+![Nodes tab](docs/screenshots/02-nodes.svg)
+*Nodes (`2`)*
+
+![Services tab](docs/screenshots/03-services.svg)
+*Services (`3`)*
+
+![Actions tab](docs/screenshots/04-actions.svg)
+*Actions (`4`)*
+
+![Bags tab](docs/screenshots/06-bags.svg)
+*Bags (`8`) — recording state*
+
+Cross-cutting features:
+
+- **Auto-QoS** — subscriber profile is negotiated to match every publisher of a topic (BEST_EFFORT vs RELIABLE, TRANSIENT_LOCAL, etc.), so sensor topics "just work".
+- **Theme persistence** — pick a theme via `Ctrl+P → Change theme`; it survives restarts (stored next to your config in a small `state.toml`).
+- **Runtime domain switch** — `:domain 5` reconnects the rclpy backend on a new `ROS_DOMAIN_ID` without restarting the app.
+- **Live notifications** — important actions (subscribed, started recording, switched domain) show as toasts; nothing important hides in a covered status bar.
+- **No ROS required for the UI** — the package imports cleanly without `rclpy`, so you can dev / unit-test on cloud machines. Run with `--no-ros` to stay offline.
+
+## Install
+
+Rosight is not yet on PyPI; install from source:
+
+```bash
+git clone https://github.com/deyuf/rosight
+cd rosight
+pip install -e .
+```
+
+Then, in any terminal where you want to use it:
+
+```bash
+source /opt/ros/<distro>/setup.bash
+rosight
+```
+
+If you maintain multiple distros, source the one whose `rclpy` should drive
+discovery before launching. See [`docs/installation.md`](docs/installation.md)
+for the recommended `--system-site-packages` venv layout that keeps the system
+`rclpy` reachable while pip manages everything else.
+
+## Quick start
+
+```bash
+# launch (inherits ROS_DOMAIN_ID from env)
+rosight
+
+# pick a domain explicitly + log to file
+rosight --domain-id 5 --log-file /tmp/rosight.log
+
+# UI-only mode, no rclpy needed (great for theme / layout dev)
+rosight --no-ros
+```
+
+Inside the app:
+
+- `?` — keyboard reference overlay
+- `:` — command palette (`topic <filter>`, `plot <topic> <path>`, `record`, `domain <N>`, `quit`)
+- `1`–`9` — jump to a tab
+- `q` or `Ctrl+C` — quit
+- `r` — manual refresh
+
+Plotting workflow (the question new users ask most):
+
+1. **Messages tab**, cursor over a topic, **Enter** to subscribe (focus auto-jumps to the message tree)
+2. Use arrow keys / Space to expand fields in the tree
+3. Cursor on a *numeric* leaf (int / float), press **p** — series is added and the Plot tab opens
+
+## Documentation
+
+| Topic | File |
+|-------|------|
+| Installation per distro | [docs/installation.md](docs/installation.md) |
+| Daily usage | [docs/usage.md](docs/usage.md) |
+| Keybindings | [docs/keybindings.md](docs/keybindings.md) |
+| Configuration | [docs/configuration.md](docs/configuration.md) |
+| Plotting deep-dive | [docs/plotting.md](docs/plotting.md) |
+| Architecture | [docs/architecture.md](docs/architecture.md) |
+| Contributing | [docs/development.md](docs/development.md) |
+| FAQ | [docs/faq.md](docs/faq.md) |
+
+## Project layout
+
+```
+src/rosight/
+├── app.py             # Textual App, panel registry, global key bindings
+├── cli.py             # argparse entry point
+├── config.py          # TOML config loader + state.toml persistence
+├── ros/
+│   ├── backend.py     # central rclpy facade (lifecycle, sub mgmt, domain switch)
+│   ├── introspection.py  # dynamic message-type resolution
+│   ├── qos.py         # plain-data QoS + auto-negotiation
+│   └── stats.py       # hz / bw monitors
+├── utils/
+│   ├── datatable.py   # row-cursor preservation + last-column auto-fit
+│   ├── ringbuffer.py  # thread-safe bounded buffers
+│   ├── path.py        # message field-path parser
+│   └── formatting.py  # human-readable display helpers
+└── widgets/           # one file per panel + status bar / help / palette
+```
+
+## Tech stack & rationale — short version
+
+- **Python 3.10+** + **rclpy** (first-class ROS 2 client, dynamic message introspection via `rosidl_runtime_py`)
+- **Textual ≥ 0.79** (modern async TUI, CSS-like styling, headless pilot tests — that's how the 80-test suite stays meaningful for a TUI)
+- **plotext** for ANSI plotting in the Plot tab
+- **hatch + ruff + mypy + pytest-asyncio** for the dev loop
+- **MkDocs Material** for the docs site
+- rclpy runs on its own `MultiThreadedExecutor` daemon thread so DDS spinning never blocks the Textual main loop. See [`DESIGN.md`](DESIGN.md) for the full reasoning.
+
+## Status
+
+Beta. Discovery, subscription, plotting, TF, bag record/play, theme persistence,
+runtime domain switch — all working. Auto-forms for service call and action
+goal are on the roadmap.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

rosight-0.1.0/docs/architecture.md

@@ -0,0 +1,121 @@
+# Architecture
+
+This page is a tour of the codebase, in the order you'd encounter the
+layers when tracing a single keystroke from the user to a ROS message.
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  Keyboard                                                     │
+│     │                                                         │
+│     ▼                                                         │
+│  Textual main loop (asyncio)                                  │
+│     │                                                         │
+│     ▼                                                         │
+│  Widgets ────► panels (TopicsPanel, PlotPanel, ...)           │
+│     │                                                         │
+│     ▼                                                         │
+│  RosBackend (thread-safe facade)                              │
+│     │                                                         │
+│     ▼                                                         │
+│  rclpy MultiThreadedExecutor (background thread)              │
+│     │                                                         │
+│     ▼                                                         │
+│  DDS / wire                                                   │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Why the two-thread split
+
+Textual's event loop is single-threaded asyncio. Spinning rclpy from the
+same loop blocks the UI on every callback. `RosBackend` therefore owns a
+`MultiThreadedExecutor` running on a daemon thread; subscriber callbacks
+never touch widgets directly. Instead they:
+
+1. Update the `Subscription` record (rate / bandwidth / last_msg)
+2. Notify any registered Python callbacks under a lock
+
+The Textual side polls these records on cheap timers (`set_interval`) and
+re-renders.
+
+## ROS layer
+
+The `rosight.ros` package is intentionally importable without `rclpy`:
+
+| Module | Purpose |
+|--------|---------|
+| `qos.py` | Plain-data `QoSSpec` + `negotiate()` to derive a subscriber QoS that matches every publisher. |
+| `stats.py` | `RateMonitor` and `BandwidthMonitor` — sliding-window accumulators with thread-safe `tick`/`sample`. |
+| `introspection.py` | `iter_fields(msg)` walks any ROS message (or duck-typed dict) and yields `FieldEntry(path, value, type, is_numeric)`. |
+| `backend.py` | `RosBackend` — owns the rclpy node and executor; the only place rclpy is imported. |
+
+Because the heavy imports are deferred to `RosBackend.start()`, the
+package can be unit-tested on cloud CI runners without ROS 2 installed.
+
+## Utilities
+
+- `utils/ringbuffer.py` — `RingBuffer` (capacity-bounded) and
+  `TimedRingBuffer` (window-bounded) used by stats and plot panel.
+  Both lock-protected.
+- `utils/path.py` — parses dotted/bracketed field paths and resolves them
+  against any object (message, dict, list).
+- `utils/formatting.py` — display helpers: `format_bytes`, `format_rate`,
+  `format_value`, etc.
+
+## Widgets
+
+Each panel is a self-contained Textual `Vertical` with its own
+`compose()`, `BINDINGS`, and CSS in `DEFAULT_CSS`. Cross-panel
+communication goes through `RosightApp` (e.g. the message tree posts a
+`FieldSelected` event that `TopicsPanel` forwards to
+`app.add_plot_series`).
+
+A few widgets are reusable:
+
+- `MessageTree` renders any ROS message as a navigable tree and exposes
+  `FieldSelected`.
+- `PlotView` wraps `plotext` and turns a dict of `PlotSeries` into a
+  rendered chart on a 15 Hz tick.
+
+## Configuration
+
+`config.py` defines a strict dataclass schema, loaded from TOML. Unknown
+keys are dropped silently to preserve forward compatibility. The CLI can
+override `domain_id` per run.
+
+## Lifecycle
+
+```
+RosightApp.__init__
+  └── on_mount
+       ├── ros.start()        → executor thread starts
+       └── set_interval(...)  → status bar tickers
+RosightApp.on_unmount
+  └── ros.stop()              → shuts down node, joins thread
+```
+
+If `ros.start()` raises `RosUnavailable`, the app stays up in degraded
+mode and shows a notification — useful for offline UI work.
+
+## Testing strategy
+
+- **Pure-python tests** cover utilities, QoS logic, stats, introspection,
+  config, and parsers. They run without rclpy.
+- **Mocked-backend tests** verify the ROS facade without a real node.
+- **Headless smoke tests** boot the Textual app via `App.run_test`
+  (Textual's pilot harness) and exercise key bindings.
+- **ROS integration job** (CI) runs the suite inside official `ros:humble`
+  / `ros:jazzy` containers with a sourced workspace.
+
+## Extending Rosight
+
+To add a new panel:
+
+1. Create `src/rosight/widgets/foo_panel.py` that subclasses `Vertical`
+   (or another Textual container).
+2. Register it in `RosightApp.compose` inside the `TabbedContent` block
+   and add a number-key binding.
+3. If the panel needs ROS data, prefer adding methods to `RosBackend`
+   over reaching into rclpy from the widget.
+4. Add a test under `tests/`.
+
+See [development.md](development.md) for the full dev loop.

rosight-0.1.0/docs/configuration.md

@@ -0,0 +1,88 @@
+# Configuration
+
+`rosight` reads a TOML config from `$XDG_CONFIG_HOME/rosight/config.toml`
+(typically `~/.config/rosight/config.toml`). All keys are optional;
+defaults are listed below.
+
+```toml
+[ui]
+theme = "rosight-dark"     # ui theme name
+refresh_hz = 10            # how often the status bar updates
+discovery_period = 1.0     # seconds between topic/node list refreshes
+vim_keys = true
+
+[plot]
+window_seconds = 30.0      # default sliding-window length
+max_points = 5000          # per-series sample cap
+refresh_hz = 15.0          # plot redraw rate
+show_legend = true
+
+[stats]
+window_seconds = 5.0       # hz / bandwidth window
+max_samples = 4096
+
+[ros]
+domain_id = 0              # leave unset to inherit ROS_DOMAIN_ID
+qos_profile = "auto"       # auto | sensor_data | reliable | best_effort
+queue_depth = 10           # default subscriber queue depth
+```
+
+## Overriding via CLI
+
+```bash
+rosight --config /path/to/alt.toml
+rosight --domain-id 7
+```
+
+The CLI also accepts `ROSIGHT_CONFIG=path` as an env override.
+
+## Where each setting goes
+
+- **`ui.discovery_period`** controls how often `list_topics` etc. are
+  called. Increase if you have a very busy graph and discovery becomes
+  expensive.
+- **`plot.window_seconds`** is the initial window; `+` and `-` scale it
+  interactively at runtime.
+- **`stats.window_seconds`** governs the smoothing on hz / bandwidth.
+  Smaller values are more responsive but noisier on bursty topics.
+- **`ros.qos_profile`** is a forward-looking knob. The default `auto`
+  derives QoS from publisher endpoints (recommended); the others force a
+  single profile for every subscription.
+
+## Schema
+
+Defined as plain dataclasses in `src/rosight/config.py`. Unknown keys are
+silently ignored to keep older configs compatible.
+
+## Persisted runtime state
+
+Things you change inside the app (currently just the **theme** picked from
+`Ctrl+P → Change theme`) are written to a separate small file next to your
+config so Rosight never rewrites your hand-edited `config.toml`:
+
+```
+$XDG_CONFIG_HOME/rosight/state.toml
+```
+
+Example content after picking a theme:
+
+```toml
+theme = "textual-light"
+```
+
+Delete the file to fall back to whatever `[ui] theme` is set in your config
+(or the built-in default if neither exists).
+
+## Runtime domain switch
+
+You can change `ROS_DOMAIN_ID` *while the app is running* without losing the
+session:
+
+```
+:           # open the command palette
+domain 5    # rclpy is reinitialised on domain 5
+```
+
+The rclpy context, executor, and every active subscription are torn down and
+recreated on the new domain. The status bar's `DOMAIN_ID=` field updates
+immediately to reflect the live value (not the env var).