Fix multisource and demod lifecycle issues

.agents/AGENTS.md

@@ -3,20 +3,40 @@
 Guidance for AI coding agents working on the N-APT RF spectrum analyzer. Keep
 feature notes and implementation summaries in `.agents/`.
 
+For signal-processing, IQ-capture, FFT, demodulation, `/learn`, or signals CLI
+work, load `.agents/signals/SKILL.md`. It defines the project's plain-language
+terminology, current demod modes, evidence standards, and RX-only safety rules.
+
 ## Working Rules
 
 - The user normally has the dev server running. Do not start or restart it for
   ordinary changes; Vite and Rust hot reload are enabled.
-- Do not run `npm run build`; run `npm run build:markdown` only for markdown
+- Keep changes scoped, avoid scratch files, and keep the workspace clean.
+- Keep changes as device/source agnostic as possible.
+- Do not add unrequested design changes or features.
+- Ensure to update checklists, tasks, etc., as you complete tasks.
+- Do not run `npm run build`; run `npm run build:article` only for markdown
   article changes.
 - Do not use browser automation for testing. If frontend testing is necessary,
   use `http://localhost:5173`; `127.0.0.1` is blocked.
+- Do not preserve backwards compatibility.
 - Prefer inspecting code and focused tests over repeating broad verification.
 - Use the Act MCP tool for repository searches.
-- Do not add unrequested design changes or features.
 - Add regression tests for bugs and run `npm run typecheck` after TypeScript
   changes. Run `cargo check` after Rust changes.
-- Keep changes scoped, avoid scratch files, and keep the workspace clean.
+
+## Real-Time Device I/O
+
+- Do not log from device I/O paths. This includes RTL-SDR/HackRF callbacks,
+  sample reads and writes, acquisition hot paths, reader startup/restart,
+  cancellation, cleanup/drop, and Tx monitor or transmission callbacks.
+- Logger formatting and logger locks can delay USB/libusb work and make the
+  hardware unstable. Use comments to document these constraints, and use
+  returned errors, state, counters, or deferred control-plane diagnostics to
+  surface failures after the I/O operation completes.
+- Keep the global Tx log disabled; do not re-enable it or add logging around
+  physical Tx operations without explicit authorization and device-safety
+  evidence.
 
 ## Mock APT SDR Rules
 
@@ -29,12 +49,12 @@ feature notes and implementation summaries in `.agents/`.
 
 ## I/Q Captures and Privacy
 
-- Never add I/Q capture data to Git. This includes `.napt`, `.wav`, `.iq`, and
-  related extensions such as `.iq.u8` and `.c64`. Keep captures local or in
+- Never add I/Q capture data to Git. This includes `.napt, .iq, .wav`, and
+  related extensions such as `.c64`. Keep captures local or in
   external storage; version only metadata, manifests, and synthetic fixtures.
 - Treat every I/Q capture as potentially sensitive: it may reveal information
   about the recording environment, and some signals may contain exceptionally
-  sensitive or otherwise unparalleled information.
+  sensitive or otherwise private information.
 - Treat N-APT captures as the greatest privacy risk in this project. Minimize
   copying and exposure, and never share, upload, or commit them without the
   user's explicit authorization.
@@ -87,6 +107,7 @@ build merely to validate a local edit.
 ### TypeScript and React
 
 - Use strict TypeScript; prefer `unknown` over `any`.
+- In tests, import `act` from `@testing-library/react`; do not use `react-dom/test-utils`.
 - Use `camelCase` for variables/functions, `PascalCase` for types/components,
   and `UPPER_SNAKE_CASE` for constants.
 - Keep hook dependency arrays correct and use `useCallback` when passing stable
@@ -108,10 +129,31 @@ build merely to validate a local edit.
 - The main app runs on port 5173. The markdown preview runs on port 5174.
 - The login password is `UNSAFE_LOCAL_USER_PASSWORD` in `.env.local`; do not
   print or commit secrets.
-- Rust logs are in `/tmp/rust_log.txt`; Tx logs are in `/tmp/n-apt/tx_log.txt`.
+- Rust logs, both output and errors, are in `/tmp/rust_log.txt`; Tx logs are in `/tmp/n-apt/tx_log.txt`.
 
 ## Repository Conventions
 
 - Use `@n-apt/*` for scoped imports.
 - When adding Vite aliases for static assets, update Jest `moduleNameMapper` so
   tests resolve them through the shared file mock instead of parsing raw assets.
+
+## Learned User Preferences
+
+- Prefer frontend DSP for demodulation so audio/processing changes can be inspected and listened to in real time on the demod route.
+- Treat `liveSourceLifecycle` and `sourcePresentationController` as the source of truth for live placeholder and stream lifecycle; FFT/waterfall canvases should only render those states. Paused Rx keeps the last live Rx frame; Tx standby accepts `request_next_frame` previews; transmitting must unfreeze and follow live Tx frames.
+- When the backend is down or killed, show Server Down / unavailable — not an indefinite Loading FFT state or optimistic Loading flashes from polling.
+- Do not auto-start Tx when opening a Tx device into standby; standby is announce-only until the user explicitly starts transmit.
+- Keep VFO and FrequencyRangeSlider scroll/pan responsive; avoid debounce, timer coalescing, or paint gates that stall live spectrum during hardware retune.
+- Keep mirror I/Q baseband behavior explicit in `test/ts/basebandMirror.test.ts`; the mirror path should stay GPU-resample focused with performance close to mirror-off.
+- Keep build/hot-reload orchestration under `scripts/build`; leave in-app hot-reload notifications in the app code.
+
+## Learned Workspace Facts
+
+- Never lower the hardware sample rate below 3.2 MHz (N-APT Nyquist needs that width); narrower modes such as FM use a bandwidth slice/window inside that sample rate.
+- Span bandwidth is a selected slice within the sample-rate window, not the same thing as sample rate.
+- The available spectrum display range is 0 Hz to 30 GHz; center/span padding and clamps must respect those bounds (including sample_rate/2 from center). With "Mirror I/Q baseband below 0 Hz" enabled, negative-frequency presentation is allowed without changing what the radio is tuned to.
+- Mirror I/Q below 0 Hz is presentation-only: reflect acquired positive baseband across DC via `basebandMirror.ts` and the WebGPU resample path; it must not retune hardware on every pan tick.
+- During VFO/slider retune, paint live IQ on each frame's acquisition axis (`center_frequency_hz ± sample_rate/2`) when the requested viewport and frame center diverge; mapping bins onto the scrolled Redux viewport causes channel-island flatlining.
+- Agent guidance and related docs live under `.agents/` (including `.agents/AGENTS.md`).
+- HackRF One needs LNA/VGA/AMP gain plus baseband bandwidth-filter control, with persistence/control parity similar to other radio gain settings.
+- Avoid eagerly loading heavy `/transformers` / transformers.js paths on app startup; they can hang localhost load and should stay excluded or lazy-loaded.

.agents/ONBOARDING_PROMPT.md

@@ -0,0 +1,94 @@
+# Partial n-apt Onboarding Prompt
+
+Copy this prompt into a new coding-agent session when the agent needs a fast,
+partial understanding of this repository before making a scoped change.
+
+```text
+You are onboarding to the n-apt repository, an SDR spectrum-analyzer and
+signal-visualization application. Build a partial mental model first; do not
+modify files during onboarding unless the user separately asks for a change.
+
+## Start here
+
+1. Read `.agents/AGENTS.md` and `.agents/SECURITY.md`.
+2. Read `README.md` only for the product vocabulary and broad feature scope;
+   do not treat its narrative claims as implementation evidence.
+3. Inspect `package.json`, `Cargo.toml`, `vite.config.js`, `tsconfig.json`,
+   `scripts/build/`, and the current Git status.
+4. Follow this reading order:
+
+   - `src/ts/root.tsx` and the route/app-shell files under `src/ts/app/`
+   - `src/ts/redux/store.ts`, the Redux slices, and
+     `src/ts/redux/middleware/websocketMiddleware.ts`
+   - `src/ts/validation/schemas.ts` and
+     `src/ts/consts/schemas/websocket.ts`
+   - `src/ts/app/routes/pages/SpectrumRoute.tsx`,
+     `src/ts/features/spectrum/FFTCanvas.tsx`, and the waterfall components
+   - `src/rs/server/main_bin.rs`, `src/rs/server/main.rs`,
+     `src/rs/app/bootstrap.rs`, and `src/rs/app/router.rs`
+   - `src/rs/server/types.rs`, `src/rs/server/websocket_server/`,
+     `src/rs/server/stream_manager.rs`, and `src/rs/streaming/`
+   - `src/rs/sdr/`, `src/rs/acquisition/`, and `src/rs/s/fft/`
+   - `src/rs/lib.rs`, `scripts/build/build_wasm.sh`, and
+     `packages/n_apt_canvas/` only when the task involves WASM or WebGPU
+
+## Trace one vertical path
+
+Explain the actual lifecycle, with file and symbol references, for:
+
+`process startup → frontend authentication → `/ws` and `/ws/streams` →
+`source_info` inventory/active-source handoff → source selection → I/Q or
+spectrum frame transport → Redux state → FFT/waterfall presentation`.
+
+Also identify where the following are owned:
+
+- source selection intent versus backend-confirmed active source;
+- WebSocket message validation and protocol/version ordering;
+- live/paused/standby/transmitting presentation state;
+- hardware acquisition versus display-rate frame dropping;
+- FFT, resampling, mirroring, and WebGPU/WASM work;
+- authentication, sessions, Redis readiness, and HTTP routes.
+
+## Produce a short onboarding memo
+
+Return:
+
+1. a five-to-eight-step guided reading order;
+2. the key runtime boundaries and data contracts;
+3. the smallest relevant test locations for a future change;
+4. three to five risks or invariants an implementer must preserve;
+5. open questions and areas not inspected.
+
+Label each statement as one of `verified in code`, `verified by focused test`,
+or `inference`. Do not claim browser, live-backend, physical-device, or
+hardware validation unless it was actually performed and recorded separately.
+
+## Project guardrails
+
+- Preserve unrelated dirty-worktree changes. Inspect `git status` and diffs
+  before proposing edits.
+- Do not start or restart the development server for ordinary code changes.
+- Do not run `npm run build`; use focused checks. Run `npm run typecheck` after
+  TypeScript changes and `cargo check` after Rust changes.
+- Do not add logging to RTL-SDR/HackRF callbacks, sample I/O, acquisition,
+  restart/cleanup/drop, or Tx paths. Keep global Tx logging disabled.
+- Never commit, upload, decrypt, or expose I/Q captures, credentials, or
+  private environment values. Prefer synthetic fixtures.
+- Treat `source_info` as the authoritative active-source/inventory boundary;
+  `/ws` and `/ws/streams` have distinct responsibilities.
+- If the task concerns signal processing, IQ capture, FFT, demodulation,
+  `/learn`, or the signals CLI, read `.agents/signals/SKILL.md` before going
+  deeper.
+
+## Deliberate partial scope
+
+Do not deeply inspect `src/app-article/`, `src/app-game/`, legal pages, tower
+data/Redis tooling, encrypted modules, or unrelated scripts unless the task
+reaches one of those areas. Say explicitly when the onboarding stops at one of
+those boundaries.
+```
+
+This is intentionally a partial onboarding prompt, not a complete architecture
+catalog. It prioritizes the live application path and the contracts most likely
+to matter for frontend, backend, transport, spectrum, and device-lifecycle
+work.