Initial commit

.gitignore

@@ -0,0 +1 @@
+build/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "deps/plotter"]
+	path = deps/plotter
+	url = https://git.ferrarinas.it/martino/plotter.git

CLAUDE.md

@@ -0,0 +1,245 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and run
+
+```sh
+git submodule update --init --recursive          # deps/plotter is a submodule
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build build
+
+./build/udpscope --server 127.0.0.1 --port 8000
+./build/udpscope --server 10.0.0.5 --port 8000 --multicast 239.1.2.3 --interface 10.0.0.9
+```
+
+Options: `--server`, `--port`, `--multicast`, `--interface`, `--buffer-mb` (per
+buffer, default 200), `--max-window`, `--holdoff`, `--recv-buffer`, `--plots` (1..4).
+
+`deps/plotter` is built from source with only the GTK4 adapter enabled
+(`PLOT_BUILD_GTK4`); its tests and examples are forced off. `deps/udpsclient` is a
+vendored C99 source pair compiled into a static lib.
+
+`deps/plotter` is upstream's own repository and this app's figure support was added
+there rather than worked around here: `Figure::set_min_y_gutter()` (a floor under the
+common left gutter), and in the GTK4 adapter `PlotArea`'s **figure mode** —
+`set_figure()`, one `input::Controller` per row, nearest-row event routing, a
+figure-wide crosshair — plus `PlotArea::row_at()` for naming the row a pointer is over.
+Changing those means committing in the submodule and moving its pin.
+
+## Verification
+
+There is no unit test suite. The only automated check is the app's own headless
+self-check, driven by env vars and run under a display (`xvfb-run`, llvmpipe) against
+a live UDPStreamer source:
+
+```sh
+xvfb-run -a env UDPSCOPE_EXIT_AFTER_MS=8000 UDPSCOPE_ENABLE_ALL_MS=1000 \
+  ./build/udpscope --server 127.0.0.1 --port 8000
+```
+
+- `UDPSCOPE_EXIT_AFTER_MS` — run the trigger-on → go-live probe, close the window,
+  then dump the whole pipeline state to stdout (frame/sample counts, per-plot painted
+  frames, trace bindings, panel sizes, status line in both states).
+- `UDPSCOPE_ENABLE_ALL_MS`, `UDPSCOPE_ARM_TRIGGER_MS`, `UDPSCOPE_PROBE_DISARM_MS`,
+  `UDPSCOPE_TRIG_TRACE_MS` — schedule individual probes.
+- `UDPSCOPE_PROBE_PAUSE_MS` — pause acquisition mid-run so layout numbers are
+  measured on a still picture.
+
+**Run one self-check at a time.** Two concurrent `xvfb-run -a` instances end up on the
+same display and the second gets no GL context — it dumps `layout over 0 frames` and
+`valid=-1`, which looks like a pipeline failure and is not one. `tools/mock_udpstreamer.py`
+also outlives its `--duration`, so kill it after each run or the leftovers pile up and
+hold ports.
+
+Two lines of the self-check output are assertions in disguise:
+
+- `layout over N frames: axes.x A..B, ...` — **`viewport.w` must collapse to a single
+  value and `axes.x`, `axes.w` and `y-gutter` must *settle*.** `note_y_gutter()` is
+  monotone (`plot_host.cpp`), its one-shot widest-label reservation can land a frame or
+  two after the first measured frame, and the figure serves its floor out of the label
+  strip (`y_width = max(measured, floor - y_title_w)`, `plot.cpp`) so the reservation
+  converges over two layouts rather than one. A `y-gutter 44..74` dragging
+  `axes.x 67..80`/`axes.w 546..559` with it is that settle, not a twitch — confirm it
+  with the `changes` line below. A range that keeps moving is the "twitching axis" bug:
+  the plot being re-measured every frame. **`x-desync` must read 0**: it counts frames
+  in which any row's x range differed from row 0's by more than a pixel of data, i.e.
+  frames the x link group did not reach. `x-ticks` is content, not layout, and
+  legitimately varies by one as a live
+  window slides over a round number. The companion `axes.w changes: N (last at frame F,
+  side panel up=S)` line separates the two readings: `0`, or a handful near the start,
+  is a settled layout; a count near the frame count is the twitch. Runs far longer than
+  the documented probes have shown one ~320 px step — the side panel's width — that
+  reverts; it is intermittent and unexplained, so read `changes` before calling a range
+  the twitch bug.
+- `[trig-probe] ... trigger=on ... display=...` (stderr, `UDPSCOPE_TRIG_TRACE_MS`) —
+  with `trigger=on`, `display` must read `event(frozen)` or `nothing`, **never**
+  `live`, except for the single interval that contains the toggle itself — recognise
+  it by `latches=0` *and* the next probe reading `nothing` with the same frozen
+  `axis=`. And `snap=[a..b]` must equal `axis=[a..b]`, with `b` positive by roughly
+  the post-trigger share: that is the "post window is empty" defect's observable.
+  **`drawn=[a..b]` must equal `data=[a..b]`** in both modes: `data` is `x_at()` (what
+  the crosshair reads) and `drawn` is `x0() + gather()` (what the renderer maps), so a
+  series that breaks the "gather emits x relative to `x0()`" contract shows up here as
+  the two disagreeing by exactly `x0()` — a trace drawn a whole pre-trigger window left
+  of its axis, invisible once the view is narrower than the shift, while the crosshair
+  keeps reporting correct values.
+- `[trig-probe/idx] n=.. bounds=[..] dx=.. dx_real=.. dx_ratio=R got=[a..b) want=[c..d)`
+  (stderr, same probe) — **`got` must contain `want`** (`a <= c` and `b >= d`), and
+  `dx_ratio` must stay within about a percent of `1.0`. `got` is the index window
+  `Renderer::draw_traces` gathers, recomputed here from its own `(x - x0()) / dx()`
+  *uniform grid* formula; `want` is the same window found by binary search over the real
+  time ring, which is what `x_at()`/`neighbours()` — and so the crosshair — use. A
+  `dx_ratio` above 1 scales every index up, `a` lands past the first visible sample, and
+  the samples in between sit in the buffer, readable by the crosshair, and are never
+  drawn: the live view's older part goes blank while its newest part looks fine. Also
+  read `axis=` in the companion line against the `window dropdown:` line in the dump —
+  a live axis narrower than the requested window is the same symptom from the other
+  cause (see the `clamp_to_data()` invariant below). Both need a *saturated* ring to
+  show up, so run them under `--buffer-mb 1`, which wraps in a few seconds.
+- `trigger: edge at X ... want [-a..b] got [-c..d] n=N` (stderr) — `got` must equal
+  `want` and `N` must be exactly the window times the stream's real rate, plus one
+  (2 s at 10 kS/s is `n=20001`, not 19999). `got` shorter than `want` on the *left*
+  means the edge was accepted before the history reached back a full pre window (the
+  gate in `TriggerEngine::process()`); shorter on the *right* means the engine latched
+  early or the cut lost the newest samples. An `N` one or two short of the exact count
+  is the same class of bug, not rounding: `publish_event()` clamps the slice to every
+  value ring's `produced()`, so publishing before each channel of the latching sample
+  has been pushed silently drops it.
+
+The probes are the regression net — when changing UI or plot-host behaviour, extend
+the probe/dump in `src/ui.cpp` rather than adding a separate harness.
+
+## Architecture
+
+`SPECS.md` is the requirement document. `README.md` documents what was actually built,
+including deliberate deviations from the spec and known limitations — read it before
+concluding something is a bug.
+
+### Threads
+
+Exactly two: a producer thread in `Acquisition` owns `udps_client_t` and calls
+`udps_client_poll()`; the GTK main thread owns every widget and GL context. They share
+`ScopeModel` under `ScopeModel::mutex()`, taken once per DATA frame by the producer and
+once per frame by the UI (`tick()` in `src/ui.cpp`) around `RowSet::bind()`/`acquire()`.
+Samples themselves cross via `plot::data::RingBuffer` (single producer, single
+consumer) and never through the lock. Cross-thread scalars are atomics on `ScopeModel`
+(`trigger_enabled_`, `trigger_armed_`, `trigger_latches_`, `trigger_time_`,
+`event_`, `generation_`).
+
+### Data path
+
+`ScopeModel` holds **one `BufferStore`** (`live()`): one shared time-base ring plus one
+value ring per channel, sized by `plan_partition()` to cover `--max-window` seconds
+within the byte budget. The producer always writes it, whatever the trigger is doing —
+that is what guarantees a full pre-trigger history on the *first* latch after arming.
+The spec's second buffer (item 1) is the latched `EventSnapshot`, which is already an
+immutable copy of the captured window; see README for why two live rings were dropped.
+
+In trigger mode `RowSet::bind()` binds each trace to the snapshot and to nothing else
+(the last event, or nothing before the first). **Never the live ring**, not even while
+the post window is filling — SPECS:37 says the view must not refresh until the next
+event, and `trigger_pending()` is informational only, for the status line's wording.
+
+Layers to keep straight:
+
+- `SignalInfo` — one signal as the CONFIG described it. The unit of enable/disable.
+- `ChannelInfo` / `ChannelBuffer` — the unit of acquisition and plotting. A
+  `ChannelBuffer` is a `plot::data::Series` over a (value, time) ring pair.
+- `SlotSeries` (`src/channel.hpp`) — a trace's stable series object, rebound each frame
+  to either a `ChannelBuffer` or an `EventSeries`.
+- `RowSet` (`src/plot_host.hpp`) — **one `plot::Figure`** of up to 4 rows, each a
+  borrowed `plot::Plot*` with `kSlotsPerRow` fixed trace slots. The figure owns
+  everything the rows have to agree on: the x window (one x link group every row joins),
+  the live follow (the *group's* — a member's own axis must be `XFollow::Off`, since
+  `Figure::link_x()` refuses a `Live` member), the left gutter and the crosshair.
+
+`src/ui.cpp` is the GTK4 window (toolbar, trigger panel, signal panel, plot box) plus
+the `tick()` frame function that binds, updates the trigger state and rewrites the
+status line. One `plot::gtk4::PlotArea` in figure mode draws the whole figure. It is by
+far the largest file.
+
+### Invariants worth knowing before editing
+
+- **`plot::Plot` cannot remove or retarget a trace.** Hence fixed trace slots created
+  up front and rebinding via `SlotSeries`; a *name* change (legend text) is the one
+  thing that forces a rebuild. Cursors are parked outside the axis range instead of
+  removed.
+- **A `Figure`'s row count is fixed at construction**, so `RowSet::rebuild_all()` builds
+  a *new* figure and the area is handed it (`PlotArea::set_figure()`); it costs no GL
+  state. That makes one path for "a row's traces changed" and "the row count changed",
+  and it is why `rebuild_all()` restates a pinned event window (`pinned_pre_`/
+  `pinned_post_`) instead of re-framing on the live edge — a drop during trigger mode
+  would otherwise throw the frozen view onto the stream, where nothing moves it off
+  again until the next latch. `PlotArea::create()` is handed `App::placeholder_plot`,
+  never a row: the area keeps a reference to the plot it was created with, and a rebuild
+  destroys every row.
+- **Trace slots are identified by signal name, not channel index.** Enabling a signal
+  or a new CONFIG renumbers the channel list, so an index would silently re-point a
+  trace at another signal.
+- **Any structural change rebuilds the buffer and drops history**: a CONFIG, an
+  enable/disable, or a calibration change. Calibration is applied at ingest, which is
+  why it re-partitions.
+- **The `Series` grid contract does not hold for `ChannelBuffer`.** x is a streamed
+  timestamp, so `dx()`/`x0()` report a nominal grid (LOD level, coarse snap) while
+  `gather()`, `x_at()`, `neighbours()` and `x_bounds()` use the real time ring.
+  `gather()` emits x relative to `x0()` because absolute epoch seconds do not survive
+  `f32`.
+- **`gather()` emits x relative to `x0()` in *every* series here**, `EventSeries`
+  included, and the renderer adds `x0()` back. An event's stamps are small (edge
+  relative, `[-pre, +post]`), so emitting them absolute does not overflow anything and
+  does not look like a bug — it just draws the whole capture `x0()` = one pre-trigger
+  window to the left of the axis. That was the "half the plot is empty / the marker sits
+  at the end of the data / nothing is drawn but the crosshair reads values" defect: the
+  crosshair reads `x_at()`, which was right all along. The probe's `data=` vs `drawn=`
+  is the guard.
+- **A dropped time slot is clamped, never answered with a sentinel.** `acquire()` pins
+  the published window to the value ring's base and both rings keep sliding afterwards —
+  their capacities are equal, so there is no slack — which means the oldest few samples
+  of a saturated window routinely point at time slots the producer has already
+  overwritten. `ChannelBuffer::time_of()` therefore clamps to the oldest *readable*
+  slot: a stamp of `0` would reach `x_bounds()`, and from there `dx()` and `x0()`, which
+  is the renderer's whole index mapping — one unreadable slot inflated `dx()` by the
+  ratio of elapsed stream time to the retained window and clipped the older part of
+  every live view. The library's `StreamSeries` is immune for a reason worth copying:
+  its x is `x0 + i*dx`, a function of the absolute index, so an overwritten slot costs a
+  *y* value, never the geometry. Clamping buys the same bargain here.
+- **`clamp_to_data()` may not shrink the view below the requested window.** It runs
+  every frame and cannot distinguish "the user zoomed out past the data" from "the ring
+  has only just started filling", so it clamps against `max(retained, window_s_)`: a
+  partly filled window is left empty on its left, which is what a scope that just
+  started should look like. Clamping to `retained` alone turned a requested 2 s window
+  into the ~0.02 s the first frames held, permanently — nothing there grows a span back.
+  Its pan clamping is likewise gated on the data being wider than the view, or the empty
+  left-hand side drags the live edge off the right-hand edge.
+- **Layout must not depend on content.** The y gutter is reserved at the widest label
+  `TickFormat::Si` can produce and only ever grows; the status label is ellipsized so
+  its text cannot drive the paned divider. Both exist to stop per-frame relayout.
+  The reservation goes on the **figure** (`Figure::set_min_y_gutter()`, added to the
+  plotter for this), not on the rows: `Figure::layout()` clears every row's
+  `set_min_y_gutter()` to measure what its own labels need, so a floor written onto the
+  rows survives exactly until the next layout.
+- **Signals start disabled** — enabling is what starts acquisition. A trigger on a
+  signal nobody acquires can never fire, so selecting/arming enables it.
+- **The trigger's event window is separate from the display window**, and
+  `pretrigger_pct` is a share of the *event* span, not of the ring.
+- **The event window is counted in stream seconds end to end; nothing converts it to
+  a sample count.** `TriggerEngine` latches once the stamps it is fed have advanced
+  past the post window, and `ScopeModel::publish_event()` cuts the snapshot by binary
+  search over the time ring. There used to be a measured samples-per-second estimate
+  in `Acquisition` doing that conversion, and it is precisely why the post window came
+  out empty: any stream whose time signal advances in large steps drove it to its
+  1 S/s floor, the count came out as 1, and the engine latched on the edge sample
+  itself. **Do not reintroduce a rate estimate on this path.**
+- **The event axis is pinned from the snapshot's own stamps, not from the request.** A
+  capture may legitimately be shorter than asked for — the ring need not reach back a
+  full pre-trigger share on the first latch after arming, so `snap=[-0.339..1.000]`
+  for a ±1 s request is correct there rather than a defect.
+- **`publish_event()` cuts one absolute index range and uses it for the time ring and
+  every value ring.** That is what makes `stamps` and each `values[c]` equal-length
+  and index-aligned by construction instead of by two truncations that can disagree —
+  `EventSeries::gather()` indexes both at the same `i`.
+- **The header bar's buttons are icon-only**, so headless probes must reach them
+  through the `App` pointers (`trigger_toggle`, `pause_button`, …), not via
+  `find_labelled_button()`. The Arm/Disarm button in the trigger panel still has text.
+- Every source file carries an SPDX MIT header; match it in new files.

CMakeLists.txt

@@ -0,0 +1,49 @@
+cmake_minimum_required(VERSION 3.24)
+project(udpscope LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
+endif()
+
+find_package(Threads REQUIRED)
+
+# --- deps/plotter: built from the submodule, GTK4 adapter only ----------------
+set(PLOT_BUILD_TESTS     OFF CACHE BOOL "" FORCE)
+set(PLOT_BUILD_EXAMPLES  OFF CACHE BOOL "" FORCE)
+set(PLOT_BUILD_GLFW      OFF CACHE BOOL "" FORCE)
+set(PLOT_BUILD_IMGUI     OFF CACHE BOOL "" FORCE)
+set(PLOT_BUILD_QT6       OFF CACHE BOOL "" FORCE)
+set(PLOT_BUILD_GTK4      ON  CACHE BOOL "" FORCE)
+set(PLOT_INSTALL         OFF CACHE BOOL "" FORCE)
+add_subdirectory(deps/plotter EXCLUDE_FROM_ALL)
+
+# --- deps/udpsclient: vendored C99 receiver ----------------------------------
+add_library(udpsclient STATIC deps/udpsclient/udps_client.c)
+target_include_directories(udpsclient PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/deps/udpsclient)
+set_target_properties(udpsclient PROPERTIES C_STANDARD 99 C_STANDARD_REQUIRED ON)
+if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+  target_compile_options(udpsclient PRIVATE -Wall -Wextra)
+endif()
+
+# --- the application ----------------------------------------------------------
+add_executable(udpscope
+  src/main.cpp
+  src/config.cpp
+  src/channel.cpp
+  src/model.cpp
+  src/trigger.cpp
+  src/acquisition.cpp
+  src/plot_host.cpp
+  src/ui.cpp
+)
+
+target_include_directories(udpscope PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+target_link_libraries(udpscope PRIVATE plot::gtk4 udpsclient Threads::Threads)
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+  target_compile_options(udpscope PRIVATE -Wall -Wextra -Wpedantic)
+endif()

README.md

@@ -0,0 +1,402 @@
+# udpscope
+
+A GTK4 oscilloscope-style viewer for a UDPStreamer source: it receives one stream
+with [`deps/udpsclient`](deps/udpsclient), buffers it in two identical large
+circular buffers, and draws it with [`deps/plotter`](deps/plotter).
+
+`SPECS.md` is the requirement document; this file describes what was built.
+
+## Build and run
+
+```sh
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build build
+
+./build/udpscope --server 127.0.0.1 --port 8000            # unicast
+./build/udpscope --server 10.0.0.5 --port 8000 \
+                 --multicast 239.1.2.3 --interface 10.0.0.9  # multicast
+```
+
+Options: `--server`, `--port`, `--multicast`, `--interface`, `--buffer-mb`
+(size of the sample buffer, default 200), `--max-window` (largest time
+window the toolbar offers, default 600), `--holdoff` (default trigger hold-off),
+`--recv-buffer`, `--plots` (initial number of stacked plots, 1..4).
+
+Every CONFIG is dumped to stderr once -- publish mode and, per signal, its name,
+element count, rate, time mode and time-signal index -- because a signal that
+refuses to plot is almost always a signal the stream described in an unexpected
+way. The status line carries the same story live: `plot 1: 2 trace(s), 1400
+samples`, and `time x3` when the shared clock is decimated.
+
+Headless self-check (used by the smoke tests): `UDPSCOPE_EXIT_AFTER_MS=<ms>`
+switches trigger mode on, waits for an event, then leaves trigger mode the way the
+"Go live" button does, closes the window, and prints on stdout the status line in
+both states, the frame and per-channel sample counts, each plot's painted-frame
+count, which channel each trace slot holds, and the allocated size and reveal
+state of both side panels.
+
+## Layout
+
+```
+src/config.*       command line
+src/model.*        the sample buffer, the partition plan, the signal/channel lists
+src/channel.*      ChannelBuffer (a ring pair as a plot::data::Series) and SlotSeries
+src/acquisition.*  the UDPStreamer client, the producer thread, frame decoding
+src/trigger.*      the trigger configuration and the producer-side state machine
+src/plot_host.*    the one plot::Figure, its rows' traces and cursors, the x link group
+src/ui.*           the GTK4 window: toolbar, trigger panel, signal panel, plot box
+```
+
+Threading: one producer thread owns the `udps_client_t` and calls
+`udps_client_poll()`; the GTK main thread owns every widget and the GL contexts.
+They share `ScopeModel` under one mutex, which the producer takes once per DATA
+frame and the GUI thread takes once per frame around binding the traces.
+Samples cross the boundary through `plot::data::RingBuffer` (single producer,
+single consumer), never through the lock.
+
+## How the spec maps onto the code
+
+**One buffer of `N+1` slices, plus frozen event snapshots.** `ScopeModel`
+allocates one `BufferStore` per CONFIG: one shared time-base ring plus one value
+ring per channel (N enabled signals -- see the limitation on multi-element signals
+below). The spec's second buffer is the latched `EventSnapshot`, which is already
+an immutable copy of the captured window (see "Trigger" below); a second live ring
+bought nothing and cost half the memory budget, so `--buffer-mb 200` really is
+200 MB.
+`plan_partition()` sizes the rings to cover `--max-window` seconds and then grows
+them with the rest of the budget. When a channel's declared sample rate is lower
+than the fastest channel's, it is decimated by the integer ratio
+(`Partition::stride`); when even the target window does not fit the budget, the
+shared clock is decimated too (`Partition::time_stride`). Because the split is by
+*time span* rather than by bytes, every channel and the time base retain the same
+history -- which is what makes one shared time slice meaningful. With no
+decimation the two rules coincide and every slice is the same size.
+
+The ring is always filling, whatever the trigger is doing. The pre-trigger history
+has to already be there when an edge arrives; while acquisition followed the
+trigger state, the first latch after arming opened on however little had
+accumulated since.
+
+**Circular, time from the streamed data.** Each ring overwrites its oldest
+sample. Timestamps come from the stream's time signal when the CONFIG names one
+(`UDPS_TIME_FULL_ARRAY` / `FIRST_SAMPLE` / `LAST_SAMPLE`), and otherwise from an
+arrival-anchored estimate that accounts for `udps_frame_t::lost` by dividing the
+elapsed wall time over the cycles the gap covers. `recv_time` is used only as the
+fallback when the stream provides no usable time signal (it is then the sample's x,
+via the arrival estimate); it is never used when the stream's own time signal
+carries a span.
+
+**Trigger: what freezes is the view, not acquisition.** `TriggerEngine` runs the
+edge/hold-off/normal-single state machine on the selected channel, and once the
+requested post-trigger share of the *event span* (the event-window control, not the
+whole ring) has been collected, `ScopeModel::publish_event()` copies that window out
+of the live ring into an immutable `EventSnapshot` and publishes it atomically.
+Pre-trigger history is what the ring already holds, so the percentage is a share of
+the event window and not of the buffer.
+
+In trigger mode a trace is bound to the snapshot and to nothing else: the last
+event latched, or nothing at all before the first one. Never the live ring, not
+even while the post window is filling — a picture that changes only on an event is
+the whole point of trigger mode (SPECS: "data visualisation should not be refreshed
+till next event"), and binding the live ring mid-capture made the plot scroll for
+most of every event cycle.
+
+**The whole trigger path measures the window in stream seconds, and never in
+samples.** `TriggerEngine` is fed each sample's timestamp and latches once that clock
+has advanced past the post window; `publish_event()` then finds the slice covering
+`[edge - pre, edge + post]` by binary search over the time ring. The two are the same
+clock the x axis reads, so a capture covers the span that was asked for by
+construction.
+
+It did not used to. The engine took a post-trigger window in *samples*, converted
+from seconds by a measured estimate of the trigger channel's cadence, and that
+estimate is what made captures wrong — most visibly as the reported defect *"only the
+pre window is filled, the post window is completely empty"*. Any stream whose time
+signal advances in large steps (one sample per stream second, say) drove the estimate
+to its 1 S/s floor; the sample count then came out as 1, which the engine read as "no
+post window requested" and latched on the edge sample itself. The event held a single
+sample, its span was zero, and the UI fell back to pinning a round `[-1, +1]` axis
+that nothing filled past x = 0 — an axis that looked right, which is why the defect
+read as a drawing bug rather than a capture bug. Removing the conversion removes the
+whole failure class: there is no longer a rate estimate to be wrong.
+
+An edge is refused until the buffer reaches back a full pre-trigger window behind it,
+so a capture cannot open on a half-filled pre window. The gate compares the oldest
+buffered stamp against the edge rather than timing how long the trigger has been
+armed: the ring fills whether or not the trigger is on, so the history is normally
+already there and waiting would delay the first event for nothing. It only bites just
+after a rebuild — a CONFIG, enabling the signal, or a calibration change all drop the
+history — which is exactly when the first event used to latch on an almost empty pre
+window and draw half a plot.
+
+The event is published on the sample that latched it, but only after every channel of
+that sample has reached its ring: the cut is clamped to the shortest value ring, so
+publishing from the middle of the channel loop dropped the newest sample — the very one
+the post window had been waiting for. That cost one sample of twenty thousand on a
+10 kS/s stream, and the whole post side on a one-sample-per-second one.
+
+The axis is still pinned to what the snapshot actually captured, read off its own
+stamps rather than off the request: the two can differ by a sample at each end, and
+pinning the request would claim coverage the data does not have. The window's bounds
+are rounded to the time ring's own `f32` before being compared against it, so a sample
+sitting exactly on a bound is kept whatever the stream's absolute time happens to be —
+in f64 that decision fell to how the stamp rounded, which cost a sample at 10 kS/s and
+a third of the capture at 1 S/s.
+
+**Where the capture is drawn was a separate bug from what it contained**, and it
+outlived the fixes above. The plotting library's `gather()` emits x *relative to*
+`x0()` and the renderer adds `x0()` back; the event series emitted absolute stamps, so
+the renderer added `x0()` twice and drew the whole capture one pre-trigger window to the
+left of the axis it had just been pinned to. Nothing about the numbers looked wrong —
+the snapshot held the right samples over the right span, and the crosshair (which reads
+`x_at()`, never `gather()`) reported correct values — but with a 50/50 split the right
+half of the plot was empty, zooming out showed the trace ending at the x = 0 marker, and
+zooming in past the shift showed nothing at all. The self-check now prints `data=` and
+`drawn=` side by side for the bound trace so the contract is checked rather than
+assumed.
+
+**The live view had two clipping bugs of its own**, both wearing the same face as that
+one: the older part of the trace blank, the newest part fine, and the crosshair still
+reading values in the blank part. Neither is a data bug — the samples were always there.
+
+The first is the requested time window being quietly redefined. `clamp_to_data()` stops a
+zoom-out from running off the end of the ring, but it runs every frame and cannot tell
+that apart from a ring that has only just started filling: the first frames after a
+signal is enabled hold a couple of hundred samples, a 2 s window was clamped to the
+~0.02 s they covered, and nothing there ever grows a span back. The view then stayed
+pinned to the newest 20 ms of a 6.5 s buffer for the rest of the session. It now clamps
+against the larger of the retained span and the requested window, so a partly filled
+window simply has an empty left-hand side.
+
+The second is subtler and needs a saturated ring. A `ChannelBuffer` sample is a (value,
+stamp) pair split across two rings of equal capacity, and the published window is pinned
+by `acquire()` while both rings keep sliding under it — so the oldest samples of the
+window point at time slots the producer has since overwritten. Those used to read back as
+`0`, a perfectly plausible coordinate, which landed in `x_bounds()` and from there in
+`dx()` and `x0()`. That is the renderer's entire index mapping: it converts the visible x
+range into indices with `(x - x0()) / dx()`, so *one* unreadable slot inflated `dx()` by
+the ratio of elapsed stream time to the retained window, scaled every index up with it,
+and the gather began well inside the visible range. The stamp is now clamped to the oldest
+readable slot, which costs at most a short plateau of equal stamps at the very left edge
+— the same bargain the library's own `StreamSeries` documents, where an overwritten slot
+costs a y value and never the geometry. The self-check prints `dx_ratio` and the
+renderer's index window beside the binary-searched one, so both are checked rather than
+assumed.
+
+**The panels and the toolbar.** The header bar carries only what you reach for
+*while watching a signal*: the time window, the plot layout (1..4 rows),
+pause/resume, the trigger toggle, the side-panel toggle and an overflow menu. Those
+four buttons are icons with tooltips; nine text buttons was a wall of words to read
+past every time you wanted the one you needed. The overflow menu holds **Fit to
+data**, **Cursors**, **Reset cursors** and the **Signal list** toggle — the things
+you set up once. The side column and the two panel toggles stay hidden until a
+CONFIG arrives — there is nothing to configure before the stream describes itself —
+and the first CONFIG reveals the signal panel (the trigger panel stays behind its
+own toggle).
+
+The trigger panel selects the **signal** (every signal the CONFIG described, not
+only the acquired ones, so the list is never empty while a stream is known), the
+edge, level, pre-trigger percentage, hold-off and mode, and arms the trigger.
+
+**The event window is its own control**, separate from the display window: it is
+how much of the stream one captured event covers, and the pre-trigger percentage
+is a share of *that*. Tying it to the display window was a mistake — with the
+600 s default a latch took 300 s (half of it) to fill, so the view sat frozen for
+minutes and the trigger looked dead. With the default 50 ms event window a latch
+completes 25 ms after the edge. When an event latches and the plot is zoomed out
+wider than the event window, the display zooms to the event so the captured
+waveform fills the plot; the window dropdown follows.
+
+**Hold-off is the quiet time after an event has been captured** — measured from
+the end of the capture, not from the edge, because the capture itself already
+blocks re-arming.
+Choosing a signal, switching trigger mode on, or arming the trigger all enable
+that signal's acquisition — a trigger on a signal nobody acquires could never
+fire.
+
+**Trigger mode is the switch between streaming and triggering**, and the status
+line always names the state it is in:
+
+| status line | meaning |
+|---|---|
+| `[live]` | trigger mode off: the view follows the stream continuously |
+| `[trigger: armed, waiting for an event]` | watching for an edge; the view shows the previous state |
+| `[trigger: EVENT HELD …]` | an event was latched; the view is frozen on it |
+| `[trigger: disarmed (view frozen)]` | armed and waiting are not the same thing — nothing will arrive until it is armed again |
+
+While an event is on screen a **red vertical line marks the trigger instant** on
+every row, at the edge's own stream time — the latch may complete a post-window
+later, but the line marks the edge, so the pre/post split can be read straight off
+the plot. It is not one of the user's cursors: it has its own colour, ignores the
+cursor show/hide toggle, and is parked (invisible) when no event is held.
+
+Switching the header bar's **trigger** button off returns to `[live]` and resumes
+drawing the stream; the trigger panel carries the same action as a
+**Go live (trigger off)** button, so the way out is inside the panel that froze
+the view. Switching trigger mode on arms it immediately (arming is what "wait for
+an event" means), and in single-shot mode the trigger disarms itself after a
+latch, which the status line reports.
+
+The signal panel is one line per signal: a colour chip naming the trace it is drawn
+as, a checkbox that acquires it, its name, its unit, and a `⋯` menu holding the
+information popup and the gain/offset calibration popup. A `GtkSwitch` and two
+always-visible buttons made a row about twice as tall (46 px against 26 px now),
+which is what turned a four-signal stream into a panel you have to scroll; Adwaita's
+button and list-row minimums, not the widgets themselves, set that height, so the
+row carries a `.udpscope-compact` style class that relaxes them.
+
+**Signals start disabled**, because enabling one is what starts acquiring it.
+Enable a signal with its checkbox, or drag it onto a plot: the drop enables the
+signal if needed, binds it to that row's first free trace slot, and rebuilds the
+figure so the legend name is right (there is one widget, so the row a drop lands
+on is `PlotArea::row_at()`). The status line reports the outcome of a drop
+(`plotting 'sine' on plot 1`, `plot 1 already holds four signals`), so an action
+that changes nothing still says why. Each plot's y axis has a right-click menu
+with auto scale, a fixed range, and one **Remove '<signal>' from plot N** entry per
+occupied trace slot (a plot with nothing on it says so instead).
+
+**The plot does not twitch.** Two independent causes were fixed, both of which
+showed up as the x axis moving a few pixels every frame — including while paused,
+which is how the second one was found:
+
+1. *The gutter followed the y tick labels.* `TickFormat::Si` changes their width
+   as the auto-fitted range moves (`1.5` → `15` → `150` → `1.5k`), and
+   `set_min_y_gutter()` is only a floor — the library still takes the larger of
+   measurement and floor. `RowSet` therefore reserves the width of the widest
+   label the formatter can produce, measured once with the plot's own monospaced
+   font, and hands it to the *figure* (`Figure::set_min_y_gutter()`, added for
+   this): `Figure::layout()` clears every row's own floor each frame to measure
+   what its labels need, so a floor written onto the rows would survive exactly
+   until the next layout. The figure seeds its common gutter — the maximum over
+   the rows, which is also what aligns their axes — with that reservation.
+2. *The status line drove the pane width.* A `GtkLabel`'s minimum width is its
+   text, and the status line is rewritten every frame; as its counters and
+   messages changed width they moved the paned divider, which resized the plot,
+   which re-laid out the axes and their ticks. The label is now ellipsized, so its
+   minimum is “…”; the plot keeps the width it was given.
+
+The self-check reports both. `viewport.w` must collapse to a single value, and
+`axes.x`, `axes.w` and `y-gutter` must settle: the one-shot label reservation
+lands a few frames after the first measured frame, and because the figure serves
+its floor out of the label strip the reservation converges over two layouts, so
+their ranges show that settle and nothing after it. The companion `axes.w
+changes: N (last at frame F)` line is what separates a settle from the twitch — a
+handful of changes near the start is settled, a count near the frame count is the
+bug. `x-ticks` is content, and varies by one as a live window slides over a round
+number:
+
+```
+layout over 952 frames: axes.x 67..80, axes.w 546..559, viewport.w 627..627,
+                        y-gutter 44..74, x-ticks 20..21, x-desync 0
+axes.w changes: 2 (last at frame 35, side panel up=1)
+```
+
+Set `UDPSCOPE_PROBE_PAUSE_MS=<ms>` to pause the acquisition part-way through a
+headless run, so the numbers are measured on a still picture.
+
+The app also logs, once per second, one line per acquired channel with the number
+of samples stored and the rate that implies, next to the rate the CONFIG declared:
+
+```
+[udpscope] ch 1 'ch2_2kHz' stored=8500 (+4603 kS/s, declared 0 S/s) stride=1 clock=1 y=[-0.98, 0.98]
+```
+
+The app no longer decimates (`stride=1 clock=1`), so a stored rate far below the
+declared one is the datasource's own wire rate, not something the viewer did.
+
+**Cursors start hidden** and are switched on from the overflow menu; **Reset cursors**
+switches them on as well, because a reset nobody can see reads as a dead button.
+The two panels collapse vertically (`SLIDE_DOWN`), so hiding one gives its space
+back instead of leaving an invisible gap in the column.
+
+The window dropdown offers the standard ladder up to `--max-window`, capped to
+what one buffer actually holds (the cap is recomputed when a CONFIG changes the
+partition, and never on a mere enable or calibration change). A span that is not
+on the ladder — `Fit` frames whatever the ring holds, which is rarely a round
+number — gets its own entry rather than being rounded to a neighbour, so the
+dropdown reads what is on screen instead of approximating it.
+
+**Fit to data** (overflow menu) does what the plot's own `f` key does: auto-scales every row's y
+axis and re-frames the x window on the data the ring holds, propagated to every
+row. The status line acknowledges it (`fitted to the buffered data (1.25 s)`).
+
+**Shared x axis.** The rows are the rows of **one `plot::Figure`**, drawn by one
+`plot::gtk4::PlotArea` in figure mode, and they all join a single x link group.
+A gesture changes the row it landed on; `Figure::layout()` adopts that change
+into the group and pushes it to the others, so panning or zooming any row moves
+them all with nothing to propagate by hand. The live follow is the *group's*
+(`set_x_link_follow`), not each row's — `Figure::link_x()` refuses a member whose
+own axis still follows, because a following axis would reinterpret the pushed
+range as its own span and offset behind its own edge, which is per-row drift by
+construction. The figure also owns the left gutter and the crosshair, so a
+vertical feature lands in the same pixel column in every row.
+
+The self-check's layout line carries `x-desync N`, the number of frames in which
+any row's x range differed from row 0's by more than a pixel of data. **It must
+read 0.**
+
+`Figure`'s row count is fixed at construction, so there is one structural path:
+a changed row count, or a changed legend name (the one thing a `Plot` cannot
+express), builds a new figure and the area is handed it. That costs no GL state —
+the widget keeps its context. A displayed event survives the rebuild because the
+pinned `[-pre, +post]` window is restated rather than re-derived from the live
+edge.
+
+## Review findings not (yet) implemented
+
+These are known deviations, found by a spec/code review, that are deliberate for
+now — they are listed so they are not mistaken for anything else:
+
+- **There is one live buffer, not two.** The spec's second buffer is served by the
+  latched `EventSnapshot` — an immutable copy of the captured window, which is
+  exactly what "the buffer the view is frozen on" needs to be. Two live rings would
+  also mean acquisition had to follow the trigger state, which is what left the first
+  latch after arming with no pre-trigger history.
+- **The buffer is allocated at the first CONFIG, not at initialisation.**
+  The spec's "N+1 split" needs N, which only a CONFIG gives; `--buffer-mb` is the
+  *budget*, and the power-of-two ring rounding means the final
+  allocation lands in `(budget/2, budget]` rather than exactly on it. Every CONFIG,
+  enable/disable and calibration re-partitions (and drops the history) because the
+  buffer layout *is* the channel list.
+- **Channels are not decimated at ingest.** The spec's `window * rate > buffer`
+  rule was implemented as `stride = round(rate_fastest / rate_channel)`, which for
+  a 2 kHz sine on a 1 MHz clock is exactly one sample per period: every kept
+  sample sat at the same phase and the channel plotted as a flat line. Channels
+  are now stored at the shared clock's rate and the LOD min/max pyramid preserves
+  the extremes at draw time. When the requested window does not fit the budget the
+  *shared clock* is decimated instead (the status line's `time xN`).
+- **Pre-trigger % is a share of the *event* window**, not of the retained history —
+  see the trigger section above for why (the spec's sentence predates the event
+  window being a separate control).
+- **A plot holds at most four signals** (`RowSet::kSlotsPerRow`), because a `Plot`
+  cannot give up a trace and the slots are therefore created up front.
+- **One toggle drives both cursor orientations.** The vertical markers and the
+  horizontal ruler exist separately but share one show/hide and one reset.
+- **The time reference is the first *enabled* channel's signal.** A CONFIG whose
+  time signal belongs to a signal that is disabled contributes no stream time, and
+  the app falls back to arrival-based timing (with a warning on stderr).
+
+## Limitations
+
+- **Multi-element (vector/matrix) signals are acquired with a zero-order hold.**
+  `udps_client` decodes exactly one *sample* of `num_rows x num_cols` values per
+  DATA packet for such a signal, regardless of the publish mode, so it cannot be
+  decimated on its declared rate. Each element becomes one channel sampled on the
+  shared clock's own cadence with the packet's value held until the next packet —
+  exactly faithful in `strict` mode, and the only reading of the wire that does
+  not invent samples in `accumulate` mode. The info popup and the CONFIG dump on
+  stderr report the element counts.
+- **The event window can be shorter than the buffer.** The trigger latches a window
+  of the event-span selection; the ring holds far more, so with trigger mode off the
+  rest is scrollable history.
+- **Calibration is applied at ingest**, so changing gain or offset rebuilds the
+  buffers (and drops the history). Applying it at read time would need the LOD
+  pyramid to be gain-aware.
+- **Cursors are per row** and not synchronised with each other; show/hide parks
+  them outside the axis range rather than removing them, because `Plot` has no
+  `remove_cursor`. The trigger marker is the one exception: it has its own cursor
+  and is independent of the cursor toggle.
+- **Verified headless only.** Acquisition, partitioning, the trigger state
+  machine and its integration with the buffers, and rendering under Xvfb
+  (llvmpipe) were exercised; the interactive paths (drag and drop, the dialogs,
+  the right-click menu) were not driven by an automated test.

SPECS.md

@@ -0,0 +1,38 @@
+- Initialize 2 identical large buffer at initialization (default 200MB each, configurable as cli argument) to use as sample buffer for the rest of the application
+- Uses `deps/plotter` for plotting
+- Uses `deps/udpsclient/udps_client.h` to connect to one stream source
+- the application should be composed of:
+  1. main toolbar that contain:
+     - time window selection
+     - plot layout selection
+     - pause/resume button
+     - enable/disable trigger mode
+     - show/hide and reset cursors [horizontal and or vertical]
+  2. when in trigger mode a collapsable right panel to configure trigger logic:
+     - select signal to use as trigger
+     - select edge detection type (rising, falling, both)
+     - select trigger level
+     - select pre trigger window size (in %)
+     - select trigger hold off time (default 10ms)
+     - select trigger mode [normal], [single]
+     - arm/disarm trigger button
+  3. a collapsable signal panel:
+     - list with all available signals
+     - enable/disable signal to acquire
+     - calibrate signal: popup to select offset and gain for signal
+     - drag and drop signal on plot to start plotting it
+     - button to show signal info in a popup (unit, range, rate, type, quantisation etc)
+  4. main view with plot:
+     - multiples plots depending from selected layout
+     - each plot have it x-axis sync
+     - each plot can have y-axis with [right click menu]:
+       1. auto scale (default)
+       2. fixed range (user definable)
+     - each plot can show one or more signals
+- signal acqusition:
+  - the memory buffer should be split in N+1 (where N is the number of enabled signals) and +1 is for the shared time base
+  - only if the time window \* signal sample rate is greater than size of signal buffer decimate input signal
+  - the buffer should be used as circular buffer
+  - the time should be computed from the time associated with the signal (not from the client but from the streamed data)
+  - in trigger mode data visualisation should not be refreshed till next event, that's why 2 identical buffer, one is the currently
+    viewed event, the other used to acquire live data for next event

deps/udpsclient/Makefile

@@ -0,0 +1,46 @@
+# UDPS C client library — standalone, no MARTe2, no external dependencies.
+#
+#   make           build libudpsclient.a and the example
+#   make example   build only the example
+#   make cxxcheck  verify the header is usable from C++
+#   make clean
+
+CC      ?= cc
+CXX     ?= c++
+AR      ?= ar
+CFLAGS  ?= -O2 -g
+WARN     = -Wall -Wextra -Wpedantic
+STD      = -std=c99
+CPPFLAGS += -I.
+
+# Old glibc (< 2.17) keeps clock_gettime in librt; harmless to add there.
+LDLIBS ?=
+
+LIB     = libudpsclient.a
+OBJ     = udps_client.o
+EXAMPLE = udps_dump
+
+.PHONY: all example cxxcheck clean
+
+all: $(LIB) $(EXAMPLE) 
+
+$(LIB): $(OBJ)
+	$(AR) rcs $@ $^
+
+udps_client.o: udps_client.c udps_client.h
+	$(CC) $(STD) $(WARN) $(CFLAGS) $(CPPFLAGS) -c -o $@ $<
+
+example: $(EXAMPLE)
+
+$(EXAMPLE): example/udps_dump.c $(LIB)
+	$(CC) $(STD) $(WARN) $(CFLAGS) $(CPPFLAGS) -o $@ $< $(LIB) $(LDLIBS)
+
+# The header is C++-safe; this target keeps it that way.
+cxxcheck: udps_client.h
+	echo '#include "udps_client.h"' > .cxxcheck.cpp
+	echo 'int main() { udps_client_config_t c; udps_client_config_init(&c); return 0; }' >> .cxxcheck.cpp
+	$(CXX) -std=c++11 -Wall -Wextra $(CPPFLAGS) -o .cxxcheck .cxxcheck.cpp $(LIB) $(LDLIBS)
+	./.cxxcheck && rm -f .cxxcheck .cxxcheck.cpp
+
+clean:
+	rm -f $(LIB) $(OBJ) $(EXAMPLE) .cxxcheck .cxxcheck.cpp

deps/udpsclient/udps_client.h

@@ -0,0 +1,340 @@
+#ifndef UDPS_CLIENT_H
+#define UDPS_CLIENT_H
+
+/**
+ * @file udps_client.h
+ * @brief Standalone UDPS (UDPStreamer) receiver library — C99, no MARTe2.
+ *
+ * Depends only on libc and BSD sockets, so it can be dropped into any C or C++
+ * program that needs to consume a UDPStreamer / DebugService stream.  The wire
+ * format is specified in Docs/Protocol.md; the library reference (and a worked
+ * example) is Docs/UDPS-C-Client.md.
+ *
+ * Usage in one paragraph: fill a udps_client_config_t, create a client, install
+ * callbacks, then call udps_client_poll() in a loop.  The client owns the
+ * connection state machine — it sends CONNECT, reassembles fragmented packets,
+ * decodes CONFIG and DATA, sends keepalives, and reconnects when the server
+ * goes silent.  Nothing is done behind your back: no threads are created and
+ * every callback runs inside your call to udps_client_poll().
+ *
+ * Threading: a udps_client_t must be used from one thread at a time.
+ */
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*---------------------------------------------------------------------------*/
+/*                             Protocol constants                            */
+/*---------------------------------------------------------------------------*/
+
+/** Magic number: ASCII 'UDPS' stored little-endian. */
+#define UDPS_MAGIC 0x53504455u
+
+/** Size of the packed packet header on the wire. */
+#define UDPS_HEADER_SIZE 17u
+
+/** Size of one serialised signal descriptor in a CONFIG payload. */
+#define UDPS_SIGNAL_DESC_SIZE 136u
+
+/** Value of udps_signal_t::time_signal_idx when the signal has no time reference. */
+#define UDPS_NO_TIME_SIGNAL 0xFFFFFFFFu
+
+/** Upper bound on elements per signal; larger descriptors are rejected. */
+#define UDPS_MAX_ELEMENTS (1u << 20)
+
+/** Packet types (udps_header_t::type). */
+enum {
+    UDPS_PKT_DATA       = 0, /**< Server -> client: signal samples. */
+    UDPS_PKT_CONFIG     = 1, /**< Server -> client: signal metadata. */
+    UDPS_PKT_ACK        = 2, /**< Client -> server: keepalive. */
+    UDPS_PKT_CONNECT    = 3, /**< Client -> server: open a session. */
+    UDPS_PKT_DISCONNECT = 4  /**< Either direction: close a session. */
+};
+
+/** Sample type codes (udps_signal_t::type_code). */
+enum {
+    UDPS_T_UINT8   = 0,
+    UDPS_T_INT8    = 1,
+    UDPS_T_UINT16  = 2,
+    UDPS_T_INT16   = 3,
+    UDPS_T_UINT32  = 4,
+    UDPS_T_INT32   = 5,
+    UDPS_T_UINT64  = 6,
+    UDPS_T_INT64   = 7,
+    UDPS_T_FLOAT32 = 8,
+    UDPS_T_FLOAT64 = 9,
+    UDPS_T_UNKNOWN = 255
+};
+
+/** Quantisation codes (udps_signal_t::quant_type). */
+enum {
+    UDPS_QUANT_NONE   = 0, /**< Raw values in the signal's own type. */
+    UDPS_QUANT_UINT8  = 1, /**< [range_min, range_max] mapped onto uint8. */
+    UDPS_QUANT_INT8   = 2,
+    UDPS_QUANT_UINT16 = 3,
+    UDPS_QUANT_INT16  = 4
+};
+
+/** Time-reference modes (udps_signal_t::time_mode). */
+enum {
+    UDPS_TIME_PACKET       = 0, /**< No per-element time; use packet arrival. */
+    UDPS_TIME_FULL_ARRAY   = 1, /**< The time signal carries one stamp per element. */
+    UDPS_TIME_FIRST_SAMPLE = 2, /**< Time signal (scalar) stamps element 0. */
+    UDPS_TIME_LAST_SAMPLE  = 3  /**< Time signal (scalar) stamps element N-1. */
+};
+
+/** Publishing modes (udps_frame_t::publish_mode). */
+enum {
+    UDPS_PUBLISH_STRICT     = 0, /**< One packet per RT cycle. */
+    UDPS_PUBLISH_ACCUMULATE = 1, /**< A batch of cycles per packet. */
+    UDPS_PUBLISH_DECIMATE   = 2  /**< One packet every N cycles. */
+};
+
+/*---------------------------------------------------------------------------*/
+/*                                Data model                                 */
+/*---------------------------------------------------------------------------*/
+
+/** Decoded 17-byte packet header. */
+typedef struct {
+    uint32_t magic;
+    uint8_t  type;
+    uint32_t counter;         /**< Same for every fragment of one update. */
+    uint16_t fragment_idx;
+    uint16_t total_fragments; /**< 1 when the update fits in one datagram. */
+    uint32_t payload_bytes;
+} udps_header_t;
+
+/** Metadata for one streamed signal, as carried by the CONFIG payload. */
+typedef struct {
+    char     name[65];       /**< NUL-terminated. */
+    uint8_t  type_code;      /**< UDPS_T_*. */
+    uint8_t  quant_type;     /**< UDPS_QUANT_*. */
+    uint8_t  num_dimensions; /**< 0 scalar, 1 vector, 2 matrix. */
+    uint32_t num_rows;
+    uint32_t num_cols;
+    double   range_min;      /**< Physical range, used to dequantise. */
+    double   range_max;
+    uint8_t  time_mode;      /**< UDPS_TIME_*. */
+    double   sampling_rate;  /**< Hz; 0 when unknown. */
+    uint32_t time_signal_idx;/**< Index into the signal list, or UDPS_NO_TIME_SIGNAL. */
+    char     unit[33];       /**< NUL-terminated. */
+} udps_signal_t;
+
+/**
+ * @brief Decoded values of one signal within a frame.
+ *
+ * Values are always physical doubles: quantised signals are already expanded
+ * back onto [range_min, range_max].  @c count is @c num_samples for a scalar
+ * signal in Accumulate mode (one value per batched cycle) and the signal's
+ * element count in every other case.
+ */
+typedef struct {
+    const double *values;
+    uint32_t      count;
+} udps_signal_values_t;
+
+/** One fully decoded DATA packet. */
+typedef struct {
+    uint32_t counter;      /**< Packet counter; gaps mean lost datagrams. */
+    /**
+     * DATA packets missing immediately before this one, from the counter.
+     *
+     * Needed to space samples correctly: the elapsed time since the previous
+     * frame covers the lost packets' cycles too, so dividing it by this
+     * frame's sample count alone gives a period too long by exactly
+     * @c lost + 1, which walks the samples past their own end and into the
+     * range the next frame claims.
+     */
+    uint32_t lost;
+    uint64_t hrt;          /**< Producer's high-resolution timer at send. */
+    double   recv_time;    /**< Wall-clock seconds (CLOCK_REALTIME) at arrival. */
+    uint8_t  publish_mode; /**< UDPS_PUBLISH_*. */
+    uint32_t num_samples;  /**< Batched cycles; 1 unless Accumulate. */
+    uint32_t num_signals;
+    const udps_signal_t        *signals; /**< num_signals entries, CONFIG order. */
+    const udps_signal_values_t *values;  /**< num_signals entries, same order. */
+} udps_frame_t;
+
+/** Connection lifecycle events reported through udps_event_cb. */
+typedef enum {
+    UDPS_EVENT_CONNECTED,    /**< Sockets are up and CONNECT was sent. */
+    UDPS_EVENT_DISCONNECTED, /**< Session dropped; the client will retry. */
+    UDPS_EVENT_ERROR         /**< Recoverable problem; detail says what. */
+} udps_event_t;
+
+/** Cumulative counters, never reset. */
+typedef struct {
+    uint64_t packets_received;  /**< Datagrams (and TCP frames) accepted. */
+    uint64_t bytes_received;
+    uint64_t frames_delivered;  /**< DATA packets decoded and handed to you. */
+    uint64_t config_updates;
+    uint64_t fragments_dropped; /**< Duplicate, stale or unplaceable fragments. */
+    uint64_t counter_gaps;      /**< DATA packets missing from the sequence. */
+    /**
+     * DATA packets dropped for not advancing the counter: reordered or
+     * duplicated on the wire. Delivering one would stamp its values with a
+     * time base older than data already handed over.
+     */
+    uint64_t stale_packets;
+    uint64_t reconnects;
+} udps_stats_t;
+
+/*---------------------------------------------------------------------------*/
+/*                                  Client                                   */
+/*---------------------------------------------------------------------------*/
+
+typedef struct udps_client udps_client_t;
+
+/** Called whenever a CONFIG packet redefines the signal set. */
+typedef void (*udps_config_cb)(const udps_signal_t *signals,
+                               uint32_t             num_signals,
+                               uint8_t              publish_mode,
+                               void                *user);
+
+/**
+ * @brief Called for every decoded DATA packet.
+ *
+ * The frame and everything it points at are owned by the client and are only
+ * valid until the callback returns — copy anything you need to keep.
+ */
+typedef void (*udps_data_cb)(const udps_frame_t *frame, void *user);
+
+/** Called on connection state changes and on recoverable errors. */
+typedef void (*udps_event_cb)(udps_event_t event, const char *detail, void *user);
+
+/**
+ * @brief Transport configuration.
+ *
+ * Zero-initialise with udps_client_config_init(), then override what you need.
+ * Set @c multicast_group to switch from unicast to multicast: in unicast the
+ * client sends CONNECT over UDP and receives everything on its ephemeral port;
+ * in multicast it joins the group for DATA and opens a TCP control connection
+ * to @c server_port for CONNECT and CONFIG.
+ */
+typedef struct {
+    const char *server_addr;    /**< IPv4 dotted quad. Required. */
+    uint16_t    server_port;    /**< UDP port (unicast) or TCP port (multicast). Required. */
+    const char *multicast_group;/**< IPv4 group; NULL selects unicast. */
+    const char *interface_addr; /**< Local IPv4 of the interface to join on. NULL = default route. */
+    uint16_t    data_port;      /**< Multicast data port; 0 means server_port + 1. */
+    double      silence_timeout_s;   /**< Reconnect after this long without data. 0 disables. */
+    double      reconnect_delay_s;   /**< Wait between reconnect attempts. */
+    double      keepalive_interval_s;/**< Unicast ACK period. 0 disables. */
+    uint32_t    recv_buffer_bytes;   /**< SO_RCVBUF; large bursts need a large value. */
+    uint32_t    max_packet_bytes;    /**< Ceiling on one reassembled payload. */
+} udps_client_config_t;
+
+/** Fills @p cfg with the defaults documented in Docs/UDPS-C-Client.md. */
+void udps_client_config_init(udps_client_config_t *cfg);
+
+/**
+ * @brief Creates a client. No socket is opened until the first poll.
+ * @return NULL if @p cfg is invalid or memory ran out.
+ */
+udps_client_t *udps_client_create(const udps_client_config_t *cfg);
+
+/** Closes the session (sending DISCONNECT if connected) and frees the client. */
+void udps_client_destroy(udps_client_t *client);
+
+/** Installs the callbacks. Any of them may be NULL. */
+void udps_client_set_callbacks(udps_client_t *client,
+                               udps_config_cb on_config,
+                               udps_data_cb   on_data,
+                               udps_event_cb  on_event,
+                               void          *user);
+
+/**
+ * @brief Drives the client: connects if needed, then waits for and processes
+ *        packets for at most @p timeout_ms milliseconds.
+ *
+ * Callbacks fire from inside this call. A negative @p timeout_ms blocks until
+ * something happens. Call it in a loop; it is the only function that does work.
+ *
+ * @return the number of packets processed (0 on timeout), or -1 if the session
+ *         broke. -1 is not fatal: the next call retries after reconnect_delay_s.
+ */
+int udps_client_poll(udps_client_t *client, int timeout_ms);
+
+/** Non-zero once the sockets are up (which does not yet imply CONFIG arrived). */
+int udps_client_is_connected(const udps_client_t *client);
+
+/**
+ * @brief The current signal set, or NULL before the first CONFIG.
+ * @param num_signals Out; may be NULL.
+ */
+const udps_signal_t *udps_client_signals(const udps_client_t *client,
+                                         uint32_t            *num_signals);
+
+/** The publishing mode from the last CONFIG (UDPS_PUBLISH_*). */
+uint8_t udps_client_publish_mode(const udps_client_t *client);
+
+/** Copies the counters into @p out. */
+void udps_client_stats(const udps_client_t *client, udps_stats_t *out);
+
+/** Human-readable description of the last failure. Never NULL. */
+const char *udps_client_last_error(const udps_client_t *client);
+
+/*---------------------------------------------------------------------------*/
+/*                          Stateless helpers                                */
+/*---------------------------------------------------------------------------*/
+
+/** Elements in one sample of @p signal (rows x cols, at least 1). */
+uint32_t udps_signal_num_elements(const udps_signal_t *signal);
+
+/** Short name of a type code, e.g. "float32". Never NULL. */
+const char *udps_type_name(uint8_t type_code);
+
+/**
+ * @brief Decodes a packet header.
+ * @return 0 on success, -1 if @p len is too small or the magic is wrong.
+ */
+int udps_parse_header(const void *buf, size_t len, udps_header_t *out);
+
+/**
+ * @brief Decodes a reassembled CONFIG payload.
+ * @param signals      Out array of at most @p max_signals entries.
+ * @param num_signals  Out; the number actually written.
+ * @param publish_mode Out; may be NULL.
+ * @return 0 on success, -1 if the payload is malformed or does not fit.
+ */
+int udps_parse_config(const void    *payload,
+                      size_t         len,
+                      udps_signal_t *signals,
+                      uint32_t       max_signals,
+                      uint32_t      *num_signals,
+                      uint8_t       *publish_mode);
+
+/**
+ * @brief One value out of a frame.
+ * @param sample Accumulate batch slot; ignored for non-scalar signals.
+ * @param elem   Element within the sample; ignored for accumulated scalars.
+ * @return the value, or 0.0 if any index is out of range.
+ */
+double udps_frame_value(const udps_frame_t *frame,
+                        uint32_t            signal_idx,
+                        uint32_t            sample,
+                        uint32_t            elem);
+
+/**
+ * @brief Arrival-anchored estimate of the wall-clock time of one element.
+ *
+ * Exact only for streams that declare a sampling rate: the packet is assumed to
+ * have arrived as its last element was produced, and earlier elements are dated
+ * backwards by 1/sampling_rate. Signals with UDPS_TIME_PACKET, or without a
+ * sampling rate, all report the arrival time. When the stream carries a time
+ * signal (time_signal_idx != UDPS_NO_TIME_SIGNAL) that signal is the accurate
+ * source — read it like any other signal instead of using this helper.
+ */
+double udps_frame_element_time(const udps_frame_t *frame,
+                               uint32_t            signal_idx,
+                               uint32_t            elem);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* UDPS_CLIENT_H */

src/acquisition.cpp

@@ -0,0 +1,476 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "acquisition.hpp"
+
+#include <udps_client.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+#include <stdexcept>
+#include <string>
+
+namespace udpscope {
+namespace {
+
+SignalInfo to_info(const udps_signal_t& s) {
+  SignalInfo info;
+  info.name = s.name;
+  info.unit = s.unit;
+  info.type_code = s.type_code;
+  info.quant_type = s.quant_type;
+  info.rows = s.num_rows;
+  info.cols = s.num_cols;
+  info.range_min = s.range_min;
+  info.range_max = s.range_max;
+  info.time_mode = s.time_mode;
+  info.sampling_rate = s.sampling_rate;
+  info.time_signal_idx = s.time_signal_idx;
+  return info;
+}
+
+}  // namespace
+
+Acquisition::Acquisition(ScopeModel& model, const Config& cfg) : model_(model), cfg_(cfg) {}
+
+Acquisition::~Acquisition() { stop(); }
+
+void Acquisition::start() {
+  udps_client_config_t c;
+  udps_client_config_init(&c);
+  c.server_addr = cfg_.server.c_str();
+  c.server_port = cfg_.port;
+  c.multicast_group = cfg_.multicast.empty() ? nullptr : cfg_.multicast.c_str();
+  c.interface_addr = cfg_.interface_addr.empty() ? nullptr : cfg_.interface_addr.c_str();
+  c.recv_buffer_bytes = static_cast<std::uint32_t>(cfg_.recv_buffer_bytes);
+  c.silence_timeout_s = 2.0;
+  c.reconnect_delay_s = 0.5;
+  c.keepalive_interval_s = 1.0;
+
+  client_ = udps_client_create(&c);
+  if (client_ == nullptr) {
+    throw std::runtime_error("could not create the UDPS client for " + cfg_.server + ":" +
+                             std::to_string(cfg_.port));
+  }
+  udps_client_set_callbacks(client_, &Acquisition::config_trampoline, &Acquisition::data_trampoline,
+                            &Acquisition::event_trampoline, this);
+
+  started_ = std::chrono::steady_clock::now();
+  running_.store(true, std::memory_order_release);
+  thread_ = std::thread([this] { run(); });
+}
+
+void Acquisition::stop() {
+  if (!running_.exchange(false, std::memory_order_acq_rel)) {
+    if (client_ != nullptr) {
+      udps_client_destroy(client_);
+      client_ = nullptr;
+    }
+    return;
+  }
+  if (thread_.joinable()) thread_.join();
+  if (client_ != nullptr) {
+    udps_client_destroy(client_);
+    client_ = nullptr;
+  }
+}
+
+void Acquisition::run() {
+  while (running_.load(std::memory_order_acquire)) {
+    udps_client_poll(client_, 50);
+    udps_stats_t s;
+    udps_client_stats(client_, &s);
+    StreamStats& out = model_.stats();
+    out.packets.store(s.packets_received, std::memory_order_relaxed);
+    out.frames.store(s.frames_delivered, std::memory_order_relaxed);
+    out.gaps.store(s.counter_gaps, std::memory_order_relaxed);
+    out.reconnects.store(s.reconnects, std::memory_order_relaxed);
+    out.connected.store(udps_client_is_connected(client_) != 0, std::memory_order_relaxed);
+  }
+}
+
+void Acquisition::on_config(const udps_signal_t* signals, std::uint32_t count,
+                            std::uint8_t publish_mode) {
+  std::vector<SignalInfo> info;
+  info.reserve(count);
+  for (std::uint32_t i = 0; i < count; ++i) info.push_back(to_info(signals[i]));
+
+  // One line per CONFIG on stderr: what the stream says it is. This is the first
+  // thing to look at when a signal refuses to plot.
+  static const char* const kModes[] = {"strict", "accumulate", "decimate"};
+  std::fprintf(stderr, "[udpscope] CONFIG: %u signals, publish=%s\n", count,
+               publish_mode < 3 ? kModes[publish_mode] : "?");
+  for (const SignalInfo& sig : info) {
+    std::fprintf(stderr,
+                 "[udpscope]   '%s' %ux%u (%u elem) rate=%g Hz time=%s idx=%u unit='%s'\n",
+                 sig.name.c_str(), sig.rows, sig.cols, sig.elements(), sig.sampling_rate,
+                 sig.time_mode == UDPS_TIME_PACKET       ? "packet"
+                 : sig.time_mode == UDPS_TIME_FULL_ARRAY ? "full-array"
+                 : sig.time_mode == UDPS_TIME_FIRST_SAMPLE ? "first-sample"
+                                                           : "last-sample",
+                 sig.time_signal_idx, sig.unit.c_str());
+  }
+  std::fflush(stderr);
+  model_.stats().have_config.store(true, std::memory_order_relaxed);
+  model_.set_signals(std::move(info));
+}
+
+void Acquisition::on_event(int event, const char* detail) {
+  (void)detail;
+  if (event == UDPS_EVENT_CONNECTED) {
+    model_.stats().connected.store(true, std::memory_order_relaxed);
+  } else if (event == UDPS_EVENT_DISCONNECTED) {
+    model_.stats().connected.store(false, std::memory_order_relaxed);
+  }
+}
+
+std::uint32_t Acquisition::build_stamps(const udps_frame_t* frame, int time_signal) {
+  // The frame's span in base ticks: a scalar signal carries `num_samples` values
+  // (one per batched cycle), a block signal (rows*cols > 1) carries its whole
+  // element block. The largest of those is how many base ticks this frame spans --
+  // in `strict` mode `num_samples` is 1 while a 1x1000 block carries 1000 samples.
+  std::uint32_t n = frame->num_samples;
+  for (std::uint32_t i = 0; i < frame->num_signals; ++i) {
+    n = std::max(n, udps_signal_num_elements(&frame->signals[i]));
+  }
+  stamps_.assign(n, 0.0);
+
+  double period = model_.partition().base_dt;
+  if (!(period > 0.0)) period = 1.0e-3;
+
+  bool used_stream_time = false;
+  if (time_signal >= 0 && time_signal < static_cast<int>(frame->num_signals)) {
+    const udps_signal_t& ts = frame->signals[time_signal];
+    // How the client indexes a signal's values depends on its shape
+    // (`udps_frame_value`): a scalar carries one value per batched cycle, so the
+    // stamp of sample k is (sample=k, elem=0); a multi-element signal carries one
+    // *sample* of `elements` values per packet, so the stamp of sample k is
+    // (sample=0, elem=k). Passing the scalar form for both is why FULL_ARRAY time
+    // signals -- the only mode that carries a stamp per element -- read as
+    // element 0 for every sample and were then judged degenerate.
+    const bool scalar_time = udps_signal_num_elements(&ts) == 1;
+    auto value_of = [&](std::uint32_t k) {
+      return scalar_time
+                 ? udps_frame_value(frame, static_cast<std::uint32_t>(time_signal), k, 0)
+                 : udps_frame_value(frame, static_cast<std::uint32_t>(time_signal), 0, k);
+    };
+    switch (ts.time_mode) {
+      case UDPS_TIME_FULL_ARRAY:
+        for (std::uint32_t k = 0; k < n; ++k) stamps_[k] = value_of(k);
+        used_stream_time = true;
+        break;
+      case UDPS_TIME_FIRST_SAMPLE: {
+        const double anchor = value_of(0);
+        const double step = n > 1 ? (value_of(n - 1) - anchor) / double(n - 1) : period;
+        for (std::uint32_t k = 0; k < n; ++k) stamps_[k] = anchor + double(k) * step;
+        used_stream_time = true;
+        break;
+      }
+      case UDPS_TIME_LAST_SAMPLE: {
+        const double anchor = value_of(n > 0 ? n - 1 : 0);
+        for (std::uint32_t k = 0; k < n; ++k)
+          stamps_[k] = anchor - double(n - 1 - k) * period;
+        used_stream_time = true;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  if (used_stream_time && n > 0) {
+    // A time signal that does not actually vary -- a vector time signal, whose
+    // values the client reads one element at a time, or a producer that leaves it
+    // zero -- would put every sample at one x and collapse the axis to a point.
+    // The arrival estimate is a worse clock but a usable one; a degenerate one is
+    // not a time base at all.
+    bool usable = std::isfinite(stamps_[0]);
+    double lo = stamps_[0];
+    double hi = stamps_[0];
+    for (std::uint32_t k = 1; usable && k < n; ++k) {
+      if (!std::isfinite(stamps_[k])) {
+        usable = false;
+        break;
+      }
+      lo = std::min(lo, stamps_[k]);
+      hi = std::max(hi, stamps_[k]);
+    }
+    if (usable && hi > lo) {
+      // The stamps must also ADVANCE across packets. A producer that restarts its
+      // stamps every packet (or a signal mislabelled as time) keeps handing back
+      // the same values; the max-clamp would then pin every sample at one x, and
+      // the trigger's hold-off clock with it -- the engine waited forever and no
+      // second event ever fired.
+      if (have_stream_anchor_ && !(stamps_[n - 1] > last_stream_anchor_)) {
+        usable = false;
+      } else {
+        last_stream_anchor_ = stamps_[n - 1];
+        have_stream_anchor_ = true;
+      }
+    }
+    if (!usable || !(hi > lo)) {
+      used_stream_time = false;  // no span to time with; fall back to arrival
+      static bool warned = false;
+      if (!warned) {
+        warned = true;
+        std::fprintf(stderr,
+                     "[udpscope] warning: the stream's time signal carries no usable span "
+                     "(%g..%g) or does not advance across packets; timing samples by "
+                     "arrival instead. Check the time signal's mode and index in the "
+                     "CONFIG dump above.\n",
+                     lo, hi);
+      }
+    }
+  }
+
+  if (!used_stream_time) {
+    // Arrival-anchored: the packet is assumed to have arrived as its last element
+    // was produced, and the earlier ones are dated backwards. A gap (`lost`)
+    // shows up as extra elapsed time between arrivals, which is exactly the
+    // spacing the samples had.
+    const double end = frame->recv_time;
+    if (!have_arrival_epoch_) {
+      arrival_epoch_ = end;
+      have_arrival_epoch_ = true;
+    }
+    const double base = end - arrival_epoch_;
+    double step = period;
+    if (have_recv_ && n > 0) {
+      const double elapsed = end - last_recv_;
+      const double cycles = double(n) * double(frame->lost + 1);
+      if (elapsed > 0.0 && cycles > 0.0) step = elapsed / cycles;
+    }
+    for (std::uint32_t k = 0; k < n; ++k) stamps_[k] = base - double(n - 1 - k) * step;
+  }
+
+  // A stream-time signal may be declared in a time unit rather than seconds
+  // ('ns' is the common one): scale it to seconds so the x axis is in seconds
+  // either way. The scale applies ONLY to stream time: the arrival fallback
+  // already produces seconds off the socket clock -- scaling those by the time
+  // signal's unit shrank the whole time base by 1e9 on 'ns' streams, which
+  // froze the trigger's hold-off clock and pinned the axis at ~0.
+  if (used_stream_time && time_signal >= 0 &&
+      time_signal < static_cast<int>(model_.signals().size())) {
+    double unit_scale = 1.0;
+    const std::string& unit = model_.signals()[static_cast<std::size_t>(time_signal)].unit;
+    if (unit == "ns") unit_scale = 1e-9;
+    else if (unit == "us" || unit == "\u00b5s" || unit == "\xce\xbc" "s") unit_scale = 1e-6;
+    else if (unit == "ms") unit_scale = 1e-3;
+    if (unit_scale != 1.0) {
+      for (std::uint32_t k = 0; k < n; ++k) stamps_[k] *= unit_scale;
+    }
+  }
+
+  last_recv_ = frame->recv_time;
+  have_recv_ = true;
+  return n;
+}
+
+void Acquisition::on_data(const udps_frame_t* frame) {
+  if (paused_.load(std::memory_order_relaxed)) return;
+
+  std::lock_guard<std::mutex> lock(model_.mutex());
+  if (!running_.load(std::memory_order_relaxed)) return;
+
+  const Partition& part = model_.partition();
+  const std::vector<ChannelInfo>& channels = model_.channels();
+  if (part.time_capacity == 0 || channels.empty()) return;
+
+  // The time reference, in order of preference: the signal the first channel's
+  // CONFIG entry names via `time_signal_idx`, or -- when the stream instead
+  // carries its time base as an explicit full-array signal -- that signal.
+  int time_signal = -1;
+  {
+    const SignalInfo& sig = model_.signals()[channels[0].signal];
+    if (sig.time_signal_idx != 0xFFFFFFFFu && sig.time_signal_idx < model_.signals().size()) {
+      time_signal = static_cast<int>(sig.time_signal_idx);
+    }
+  }
+  if (time_signal < 0) {
+    // No channel names a time signal: look for the standalone timestamp signal
+    // (full-array, more than one element, no declared rate).
+    for (std::size_t i = 0; i < model_.signals().size(); ++i) {
+      const SignalInfo& sig = model_.signals()[i];
+      if (sig.time_mode == UDPS_TIME_FULL_ARRAY && sig.elements() > 1 &&
+          sig.sampling_rate == 0.0) {
+        time_signal = static_cast<int>(i);
+        break;
+      }
+    }
+  }
+  const std::uint32_t n = build_stamps(frame, time_signal);
+  if (n == 0) return;
+
+  if (model_.epoch() == 0.0) {
+    model_.set_epoch_if_unset(stamps_[0]);
+    std::fprintf(stderr, "[udpscope] time base: epoch=%.3f, first frame recv=%.3f, n=%u\n",
+                 model_.epoch(), frame->recv_time, n);
+    std::fflush(stderr);
+  }
+  const double epoch = model_.epoch();
+
+  TriggerConfig& tc = model_.trigger();
+  // One ring, always filling, whatever the trigger is doing: the pre-trigger
+  // history has to already be there when an edge arrives, and the first latch after
+  // arming would otherwise open on however little had accumulated since. What
+  // freezes in trigger mode is the *view*, not acquisition -- the latch copies the
+  // event window out into an immutable `EventSnapshot`.
+  BufferStore& store = model_.live();
+  const u64 g = part.time_stride;
+
+  // Calibration is read per frame; it only changes under the same lock.
+  TriggerEngine& engine = engine_;
+  const int trig_channel = tc.channel;
+  // The post-trigger window straight through in seconds. There used to be a measured,
+  // smoothed samples-per-second estimate here, converting the window into a sample
+  // count for the engine; the estimate is what sized captures wrong. Its floor
+  // (`inst >= 1.0`) turned any stream whose time signal advances in large steps into
+  // 1 S/s, the count came out as 1, and the engine latched on the edge sample itself
+  // -- an event with no post-trigger data, which is exactly the "post window is
+  // empty" defect. The engine is fed stream time per sample anyway, so it can count
+  // the window itself and no conversion has to exist.
+  //
+  // The oldest buffered stamp goes with it, so the engine can refuse an edge the
+  // history does not reach back far enough behind. Read from the ring rather than
+  // timed from the arm: the ring fills with the trigger off too, so the pre window is
+  // usually already there and a timer would delay the first event for nothing.
+  const double event_span = model_.event_span();
+  const double post_want = tc.post_span_s(event_span);
+  const double oldest_s =
+      store.time().size() > 0 ? double(store.time()[0]) : last_stamp_;
+  engine.configure(tc, post_want, event_span - post_want, oldest_s);
+  // The engine's armed state follows the panel's, both ways: without the disarm
+  // half, Disarm left the engine firing (its own `armed_` was only ever set), and
+  // re-entering trigger mode kept the stale prev/edge/hold-off state.
+  if (tc.enabled && tc.armed) {
+    if (!engine.armed()) {
+      engine.arm(last_stamp_);
+      model_.trigger_armed().store(true, std::memory_order_relaxed);
+    }
+  } else if (engine.armed()) {
+    engine.disarm();
+    model_.trigger_armed().store(false, std::memory_order_relaxed);
+  }
+
+  double last_stamp_used = last_stamp_;
+
+  // The latch is handled on the sample it happens on, and with the edge the engine
+  // latched *on* -- after that sample's channels have all been pushed (see the loop).
+  //
+  // It used to set a flag and publish once after the loop, reading the edge back from
+  // the engine. But the loop keeps feeding the engine after a latch, so any further
+  // edge in the rest of the packet -- the hold-off is 10 ms and a packet can be a long
+  // block of samples -- overwrote that edge before it was read. The capture was then
+  // cut around an edge whose post window had not been collected yet, so the event came
+  // out all pre-trigger with the marker and x = 0 at the right-hand end of the data.
+  // Publishing here also means the ring provably holds the post window: the latch
+  // condition is that stream time has passed `edge + post`, and every sample up to
+  // this one has already been pushed.
+  const double span = std::max(1.0e-9, model_.event_span());
+  const double post_s = tc.post_span_s(span);
+  const auto latch = [&](double edge) {
+    model_.publish_event(span - post_s, post_s, edge);
+    model_.trigger_latches().fetch_add(1, std::memory_order_relaxed);
+    model_.trigger_time().store(edge, std::memory_order_relaxed);
+    model_.trigger_time_valid().store(true, std::memory_order_relaxed);
+    // The captured window is reported from the snapshot itself, not from the request:
+    // `want` versus `got` is what distinguishes "the engine did not wait" from "the
+    // cut lost the data", which is otherwise guesswork from the picture alone.
+    auto snap = model_.event();
+    std::fprintf(stderr,
+                 "[udpscope] trigger: edge at %.3f s, latched at %.3f s of stream time "
+                 "(want [-%.4f..%.4f] got [-%.4f..%.4f] n=%llu, frame recv=%.3f, "
+                 "ticks_so_far=%llu, wall=%.3f s)\n",
+                 edge, last_stamp_, span - post_s, post_s, snap ? snap->pre_s : 0.0,
+                 snap ? snap->post_s : 0.0,
+                 static_cast<unsigned long long>(snap ? snap->stamps.size() : 0),
+                 frame->recv_time, static_cast<unsigned long long>(tick_),
+                 std::chrono::duration<double>(std::chrono::steady_clock::now() - started_)
+                     .count());
+    std::fflush(stderr);
+    if (tc.mode == TriggerMode::Single) tc.armed = false;
+  };
+
+  for (std::uint32_t k = 0; k < n; ++k) {
+    const u64 tick = tick_++;
+    const double rel = std::max(stamps_[k] - epoch, last_stamp_);
+    last_stamp_used = rel;
+    last_stamp_ = rel;
+
+    if (tick % g == g - 1) store.time().push(static_cast<f32>(rel));
+
+    // The latch belongs to this sample, but it cannot be published from inside the
+    // channel loop: `publish_event()` clamps the slice to every value ring's
+    // `produced()`, and the channels *after* the trigger channel have not pushed this
+    // sample yet, so the newest sample -- the one the post window was waiting for --
+    // would be clamped away. One sample is invisible in a 20 000-sample capture (it is
+    // the `n=19999` and the `0.9999` instead of `1.0000` in the probe's output), and at
+    // one sample per second it is the entire post side: `got [-0.9997..0.0000]`, which
+    // reads exactly like the "post window is empty" defect.
+    bool latch_here = false;
+    double latch_edge = 0.0;
+
+    for (std::size_t i = 0; i < channels.size(); ++i) {
+      const u64 period = g * part.stride[i];
+      if (tick % period != period - 1) continue;
+      const ChannelInfo& ch = channels[i];
+      // A signal's columns are consecutive samples of the same channel: a scalar
+      // (one element) carries one value per batched cycle, a block signal carries
+      // the cycle's sample at element `k`. Either way element 0 is the channel.
+      const double raw =
+          ch.elements > 1
+              ? udps_frame_value(frame, static_cast<std::uint32_t>(ch.signal), 0,
+                                 std::min<std::uint32_t>(k, ch.elements - 1))
+              : udps_frame_value(frame, static_cast<std::uint32_t>(ch.signal), k, 0);
+      const f32 value = static_cast<f32>(raw * ch.gain + ch.offset);
+      store.values(i).push(value);
+      if (static_cast<int>(i) == trig_channel) {
+        if (engine.process(value, rel)) {
+          latch_here = true;
+          latch_edge = engine.last_trigger_time();
+        }
+      }
+    }
+    if (latch_here) latch(latch_edge);
+  }
+  last_stamp_ = last_stamp_used;
+
+  model_.trigger_armed().store(engine.armed(), std::memory_order_relaxed);
+  model_.set_trigger_pending(engine.pending());
+  static std::int64_t next_engine_log = 0;
+  const std::int64_t now_e = static_cast<std::int64_t>(frame->recv_time * 1.0e6);
+  if (now_e >= next_engine_log) {
+    next_engine_log = now_e + 1000000;
+    // `elapsed/post_want` is the capture's progress in the only unit that matters now
+    // (stream seconds); `accum` is how many samples that window has collected, which
+    // is what says whether a capture is thin because the window is short or because
+    // the stream is slow.
+    std::fprintf(stderr,
+                 "[udpscope] trig engine: ch=%d armed=%d pending=%d elapsed=%.4f/%.4f s "
+                 "accum=%llu history=%.4f/%.4f s pre_pct=%.0f v=%.4g now_t=%.3f "
+                 "holdoff_until=%.3f\n",
+                 trig_channel, int(engine.armed()), int(engine.pending()),
+                 engine.post_elapsed(), engine.post_seconds(),
+                 static_cast<unsigned long long>(engine.post_accum()), engine.history(),
+                 engine.pre_seconds(), tc.pretrigger_pct, engine.last_value(),
+                 engine.last_t(), engine.holdoff_until());
+    std::fflush(stderr);
+  }
+}
+
+// Static trampolines: the client's C ABI cannot call a member function directly.
+void Acquisition::config_trampoline(const udps_signal_t* signals, std::uint32_t count,
+                                    std::uint8_t publish_mode, void* user) {
+  static_cast<Acquisition*>(user)->on_config(signals, count, publish_mode);
+}
+
+void Acquisition::data_trampoline(const udps_frame_t* frame, void* user) {
+  static_cast<Acquisition*>(user)->on_data(frame);
+}
+
+void Acquisition::event_trampoline(udps_event_t event, const char* detail, void* user) {
+  static_cast<Acquisition*>(user)->on_event(static_cast<int>(event), detail);
+}
+
+}  // namespace udpscope

src/acquisition.hpp

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include "config.hpp"
+#include "model.hpp"
+#include "trigger.hpp"
+
+#include <udps_client.h>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <thread>
+#include <vector>
+
+namespace udpscope {
+
+/// Owns the UDPStreamer client and the producer thread that feeds the model's
+/// acquisition buffer. Everything it touches from the thread is serialised on
+/// `ScopeModel::mutex()`, so a UI-side structural change cannot race a frame.
+class Acquisition {
+ public:
+  Acquisition(ScopeModel& model, const Config& cfg);
+  ~Acquisition();
+
+  Acquisition(const Acquisition&) = delete;
+  Acquisition& operator=(const Acquisition&) = delete;
+
+  /// Opens the client (no socket until the first poll) and starts the thread.
+  /// Throws std::runtime_error when the client cannot be created.
+  void start();
+  /// Stops the thread and destroys the client. Idempotent.
+  void stop();
+
+  void set_paused(bool paused) noexcept { paused_.store(paused, std::memory_order_relaxed); }
+  bool paused() const noexcept { return paused_.load(std::memory_order_relaxed); }
+
+ private:
+  void run();
+  void on_config(const udps_signal_t* signals, std::uint32_t count, std::uint8_t publish_mode);
+  void on_data(const udps_frame_t* frame);
+  void on_event(int event, const char* detail);
+
+  static void config_trampoline(const udps_signal_t* signals, std::uint32_t count,
+                                std::uint8_t publish_mode, void* user);
+  static void data_trampoline(const udps_frame_t* frame, void* user);
+  static void event_trampoline(udps_event_t event, const char* detail, void* user);
+
+  /// Fills `stamps_` with this frame's base-tick timestamps, in stream seconds,
+  /// and returns how many were written (`frame->num_samples` unless the frame is
+  /// malformed).
+  std::uint32_t build_stamps(const udps_frame_t* frame, int time_signal);
+
+  ScopeModel& model_;
+  Config cfg_;
+  udps_client* client_ = nullptr;
+  std::thread thread_;
+  std::atomic<bool> running_{false};
+  std::atomic<bool> paused_{false};
+  TriggerEngine engine_;
+
+  std::uint64_t tick_ = 0;        ///< base ticks consumed since the epoch
+  std::uint64_t last_tick_ = ~std::uint64_t{0};
+  double last_stamp_ = 0.0;       ///< last relative time written (monotonic guard)
+  double last_recv_ = 0.0;
+  bool have_recv_ = false;
+  /// Last accepted stream-time stamp: a "time signal" whose values do not advance
+  /// across packets (a producer that restarts them per packet, or a mislabelled
+  /// signal) would freeze the whole time base -- the trigger's hold-off clock
+  /// included -- so the stream source is dropped in favour of arrival time.
+  double last_stream_anchor_ = 0.0;
+  bool have_stream_anchor_ = false;
+  /// Arrival-clock origin: the first packet's receive time, so arrival stamps are
+  /// small seconds (the time ring stores f32, which cannot hold Unix epochs).
+  double arrival_epoch_ = 0.0;
+  bool have_arrival_epoch_ = false;
+  std::vector<double> stamps_;
+  std::chrono::steady_clock::time_point started_{};
+};
+
+}  // namespace udpscope

src/channel.cpp

@@ -0,0 +1,317 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "channel.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace udpscope {
+namespace {
+
+/// Raw samples read per chunk on the gather path, so it never allocates.
+constexpr u64 kChunk = 256;
+
+/// The pyramid handed out for a slot with nothing bound to it. The renderer never
+/// asks an empty series a bucket question, but the reference must be valid.
+const plot::data::MinMaxPyramid& null_pyramid() {
+  static const plot::data::MinMaxPyramid empty;
+  return empty;
+}
+
+}  // namespace
+
+// --- ChannelBuffer ----------------------------------------------------------
+
+ChannelBuffer::ChannelBuffer(std::shared_ptr<const plot::data::RingBuffer<f32>> values,
+                             std::shared_ptr<const plot::data::RingBuffer<f32>> times, u64 stride,
+                             f64 epoch, f64 nominal_dt)
+    : values_(std::move(values)), times_(std::move(times)), stride_(stride < 1 ? 1 : stride),
+      epoch_(epoch), dt_(nominal_dt) {}
+
+void ChannelBuffer::acquire() noexcept {
+  const u64 produced = values_->produced();
+  if (produced <= published_) {
+    // Nothing new; still allow the window to slide if another reader dropped it.
+    return;
+  }
+  // A producer that lapped this ring -- a long trigger wait, or a store that was
+  // not being published for a while -- makes the incremental append meaningless:
+  // the samples between `published_` and `produced_` are no longer in the ring.
+  // Rebuilding from the retained window is O(capacity) once, and it is the only
+  // way the published window stays coherent (an empty or garbled window is what
+  // "the trace disappeared" looks like from outside).
+  if (produced - published_ > values_->capacity()) {
+    published_ = 0;
+    pyramid_.clear();
+  }
+  f32 chunk[kChunk];
+  for (u64 i = published_; i < produced;) {
+    const u64 take = std::min<u64>(kChunk, produced - i);
+    values_->copy_from(i, take, chunk);
+    for (u64 k = 0; k < take; ++k) pyramid_.append(chunk[k]);
+    i += take;
+  }
+  published_ = produced;
+  // The pyramid's window follows the ring's: sample index `base` is the oldest
+  // one still retained. drop_before() is monotonic and cheap.
+  pyramid_.drop_before(values_->base());
+}
+
+void ChannelBuffer::invalidate() noexcept {
+  published_ = 0;
+  pyramid_.clear();
+}
+
+f32 ChannelBuffer::time_of(u64 absolute_index) const noexcept {
+  // Channel sample `j` is produced on the tick that also pushes time slot
+  // `j*stride + stride - 1` (see `Acquisition::on_data`): the producer stamps the
+  // time ring every `time_stride` ticks and the channel every `stride` of those,
+  // so the last tick of the group is the one that carries the channel's sample.
+  const u64 index = absolute_index * stride_ + (stride_ - 1);
+  // The time ring is circular, so an index stays readable while it is *retained*
+  // and `copy_from()` masks it. Testing it against `capacity()` would reject every
+  // index past the first wrap -- which is every sample once the ring has filled,
+  // and would silently stamp them all with x = 0.
+  //
+  // An index the ring has already dropped is **clamped to the oldest readable slot,
+  // never answered with a sentinel**. The published window is pinned by `acquire()`
+  // to the value ring's base, and both rings keep sliding afterwards (their
+  // capacities are equal, so there is no slack at all): once the ring saturates, the
+  // few oldest samples of the window routinely point at slots the producer has
+  // overwritten since. Returning 0 for those put a stamp of 0 into `x_bounds()`, and
+  // from there into `dx()` and `x0()` -- which is the renderer's entire index
+  // mapping, `(x - x0()) / dx()`. So *one* unreadable slot at the front inflated
+  // `dx()` by the ratio of the whole elapsed stream time to the retained window and
+  // pushed every index up with it: `first` landed well past the first visible
+  // sample, and the samples in between were in the buffer, readable by the crosshair
+  // (`x_at()`/`neighbours()` go to the ring per sample and never saw the sentinel),
+  // and never drawn. That is the "live trace is clipped, only the most recent part
+  // is visible, but the crosshair still reads values there" defect.
+  //
+  // Clamping degrades the way the library's own `StreamSeries` documents for this
+  // contract: a snapshot bounds the sample *count*, not the slots, so the oldest few
+  // samples of a saturated window may read a newer value than the window names. One
+  // frame's worth of samples at the very left edge is then drawn on a short plateau
+  // of equal stamps -- monotone, so the binary searches still hold -- instead of the
+  // whole trace's geometry collapsing.
+  const u64 base = times_->base();
+  const u64 produced = times_->produced();
+  if (produced == 0) return 0.0f;
+  u64 slot = index < base ? base : index;
+  if (slot >= produced) slot = produced - 1;
+  f32 out = 0.0f;
+  times_->copy_from(slot, 1, &out);
+  return out;
+}
+
+f64 ChannelBuffer::dx() const {
+  const u64 n = pyramid_.size();
+  if (n < 2) return dt_ > 0.0 ? dt_ : 1.0;
+  const plot::Range b = x_bounds();
+  const double span = b.max - b.min;
+  if (!(span > 0.0) || !std::isfinite(span)) return dt_ > 0.0 ? dt_ : 1.0;
+  return span / f64(n - 1);
+}
+
+f64 ChannelBuffer::x0() const {
+  if (pyramid_.size() == 0) return epoch_;
+  return epoch_ + f64(time_of(absolute(0)));
+}
+
+f64 ChannelBuffer::x_at(u64 i) const {
+  if (i >= pyramid_.size()) return x0();
+  return epoch_ + f64(time_of(absolute(i)));
+}
+
+bool ChannelBuffer::neighbours(f64 x, u64& i0, u64& i1) const {
+  const u64 n = pyramid_.size();
+  if (n == 0) return false;
+  if (x < x_at(0) || x > x_at(n - 1)) return false;
+  // The time ring is monotonic, so the bracketing pair is a binary search rather
+  // than a grid walk: after a lost packet the two samples either side of `x` are
+  // not `x`/`dx` apart, and a grid would name the wrong pair.
+  u64 lo = 0;
+  u64 hi = n - 1;
+  while (lo < hi) {
+    const u64 mid = lo + (hi - lo) / 2;
+    if (x_at(mid) < x) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+  i1 = lo;
+  i0 = lo;
+  if (x_at(lo) > x && lo > 0) i0 = lo - 1;
+  return true;
+}
+
+u64 ChannelBuffer::snap_index(f64 x) const {
+  u64 i0 = 0;
+  u64 i1 = 0;
+  if (!neighbours(x, i0, i1)) {
+    if (pyramid_.size() == 0) return 0;
+    return x < x_at(0) ? 0 : pyramid_.size() - 1;
+  }
+  if (i0 == i1) return i0;
+  return (x - x_at(i0)) <= (x_at(i1) - x) ? i0 : i1;
+}
+
+plot::Range ChannelBuffer::x_bounds() const {
+  const u64 n = pyramid_.size();
+  if (n == 0) return plot::Range{epoch_, epoch_};
+  return plot::Range{epoch_ + f64(time_of(absolute(0))),
+                     epoch_ + f64(time_of(absolute(n - 1)))};
+}
+
+plot::Range ChannelBuffer::y_bounds() const {
+  const u64 n = pyramid_.size();
+  if (n == 0) return plot::Range{0.0, 0.0};
+  return reduce(0, n);
+}
+
+void ChannelBuffer::raw(u64 begin, u64 end, f32* out) const {
+  const u64 n = pyramid_.size();
+  const u64 b = std::min(begin, n);
+  const u64 e = std::min(end, n);
+  const u64 count = e > b ? e - b : 0;
+  if (count > 0) values_->copy_from(absolute(b), count, out);
+  for (u64 i = count; i < end - begin; ++i) out[i] = 0.0f;
+}
+
+void ChannelBuffer::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+                           plot::data::GatherMode mode) const {
+  const u64 n = pyramid_.size();
+  const u64 b = std::min(begin, n);
+  const u64 e = std::min(std::max(end, b), n);
+  if (b >= e) return;
+
+  const u64 origin = pyramid_.window_base();
+  const f64 base = x0();  // x is emitted relative to this (see the header)
+
+  const auto emit_raw = [&](u64 from, u64 to) {
+    for (u64 i = from; i < to; ++i) {
+      f32 y = 0.0f;
+      raw(i, i + 1, &y);
+      out_xy.push_back(static_cast<f32>(x_at(i) - base));
+      out_xy.push_back(y);
+    }
+  };
+  const auto rel = [&](u64 i) { return static_cast<f32>(x_at(i) - base); };
+
+  if (level == 0) {
+    emit_raw(b, e);
+    return;
+  }
+  level = std::min(level, plot::data::kMaxPyramidLevel);
+
+  // One geometry element per *complete* bucket wholly inside the range. `first` is
+  // a ceiling and `last` a floor, so no aggregate can reach outside [b, e) -- a
+  // floor on `first` or a `last` that includes the bucket holding `e-1` would emit
+  // aggregates covering samples the caller did not ask for (the library's B3 fix,
+  // which this mirrors). The spans left at the two edges are drawn from raw
+  // samples, so the geometry still covers the range exactly and a partial bucket is
+  // drawn once, not twice.
+  const u64 span = u64{plot::data::kBucket} << level;
+  const u64 lbase = pyramid_.level_base(level);
+  const u64 lend = lbase + pyramid_.level_size(level);
+  const u64 ceil_div = (origin + b) / span + ((origin + b) % span == 0 ? u64{0} : u64{1});
+  const u64 first = std::max(ceil_div, lbase);
+  const u64 last = std::min((origin + e) / span, lend);
+  if (first >= last) {
+    emit_raw(b, e);
+    return;
+  }
+  const u64 lead = first * span - origin;
+  if (b < lead) emit_raw(b, std::min(lead, e));
+
+  for (u64 bi = first; bi < last; ++bi) {
+    const u32 count = pyramid_.bucket_count(level, bi);
+    const u64 fs = bi * span - origin;  // >= 0: a stored bucket starts inside the window
+    switch (mode) {
+      case plot::data::GatherMode::Nearest: {
+        const u64 centre = bi * span + span / 2 - origin;
+        f32 y = 0.0f;
+        raw(centre, centre + 1, &y);
+        out_xy.push_back(rel(centre));
+        out_xy.push_back(y);
+        break;
+      }
+      case plot::data::GatherMode::Mean: {
+        if (count == 0) break;  // no finite sample: no mean to draw
+        const u64 centre = bi * span + span / 2 - origin;
+        out_xy.push_back(rel(centre));
+        out_xy.push_back(static_cast<f32>(pyramid_.bucket_sum(level, bi) / f64(count)));
+        break;
+      }
+      default: {  // Envelope
+        if (count == 0) break;
+        const plot::data::MinMax m = pyramid_.bucket(level, bi);
+        const u64 ls = std::min((bi + 1) * span, origin + e) - 1 - origin;
+        out_xy.push_back(rel(fs));
+        out_xy.push_back(m.min);
+        out_xy.push_back(rel(ls));
+        out_xy.push_back(m.max);
+        break;
+      }
+    }
+  }
+  const u64 trail = last * span - origin;
+  if (trail < e) emit_raw(trail, e);
+}
+
+// --- SlotSeries -------------------------------------------------------------
+
+plot::Range SlotSeries::x_bounds() const {
+  if (event_ != nullptr) return event_->x_bounds();
+  return buffer_ != nullptr ? buffer_->x_bounds() : plot::Range{0.0, 1.0};
+}
+
+plot::Range SlotSeries::y_bounds() const {
+  if (event_ != nullptr) return event_->y_bounds();
+  return buffer_ != nullptr ? buffer_->y_bounds() : plot::Range{0.0, 0.0};
+}
+
+const plot::data::MinMaxPyramid& SlotSeries::pyramid() const {
+  if (event_ != nullptr) return event_->pyramid();
+  return buffer_ != nullptr ? buffer_->pyramid() : null_pyramid();
+}
+
+f64 SlotSeries::x_at(u64 i) const {
+  if (event_ != nullptr) return event_->x_at(i);
+  return buffer_ != nullptr ? buffer_->x_at(i) : 0.0;
+}
+
+bool SlotSeries::neighbours(f64 x, u64& i0, u64& i1) const {
+  if (event_ != nullptr) return event_->neighbours(x, i0, i1);
+  return buffer_ != nullptr && buffer_->neighbours(x, i0, i1);
+}
+
+u64 SlotSeries::snap_index(f64 x) const {
+  if (event_ != nullptr) return event_->snap_index(x);
+  return buffer_ != nullptr ? buffer_->snap_index(x) : 0;
+}
+
+void SlotSeries::gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+                        plot::data::GatherMode mode) const {
+  if (event_ != nullptr) {
+    event_->gather(level, begin, end, out_xy, mode);
+    return;
+  }
+  if (buffer_ != nullptr) buffer_->gather(level, begin, end, out_xy, mode);
+}
+
+void SlotSeries::copy_raw(u64 begin, u64 end, f32* out) const {
+  if (event_ != nullptr) {
+    event_->raw_values(begin, end, out);
+    return;
+  }
+  if (buffer_ != nullptr) {
+    buffer_->raw(begin, end, out);
+    return;
+  }
+  for (u64 i = 0; i < end - begin; ++i) out[i] = 0.0f;
+}
+
+}  // namespace udpscope

src/channel.hpp

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include <plot/data/minmax_pyramid.hpp>
+#include <plot/data/ring_buffer.hpp>
+#include <plot/data/series.hpp>
+
+#include "event_series.hpp"
+
+#include <memory>
+#include <vector>
+
+namespace udpscope {
+
+using plot::f32;
+using plot::f64;
+using plot::u32;
+using plot::u64;
+
+/// One channel's view of a (value, time) ring pair.
+///
+/// The sample grid the library's `Series` contract assumes -- `x = x0 + i*dx` --
+/// does not hold here, because x is a *streamed timestamp*, not an index: a lost
+/// datagram leaves a gap and the samples either side of it are not one grid step
+/// apart. `dx()` and `x0()` therefore report a nominal grid (what the LOD level
+/// and the snap use), while `gather()` and `x_bounds()` report the real
+/// timestamps. `reduce()`, `sum()` and `sumsq()` are the inherited ones and read
+/// only y, so they are exact either way.
+///
+/// The time ring is shared by every channel of one buffer (spec: the +1 slice);
+/// channel sample `j` is stamped by base tick `j * stride`. A stride of 1 is the
+/// undecimated case and the common one.
+class ChannelBuffer final : public plot::data::Series {
+ public:
+  ChannelBuffer(std::shared_ptr<const plot::data::RingBuffer<f32>> values,
+                std::shared_ptr<const plot::data::RingBuffer<f32>> times, u64 stride, f64 epoch,
+                f64 nominal_dt);
+
+  ChannelBuffer(const ChannelBuffer&) = delete;
+  ChannelBuffer& operator=(const ChannelBuffer&) = delete;
+
+  /// Consumer thread: publishes everything the producer pushed since the previous
+  /// call into the LOD pyramid and slides the window. O(samples produced).
+  void acquire() noexcept;
+  /// Consumer thread: forgets the published window (after a rebind or a reset).
+  void invalidate() noexcept;
+
+  void set_nominal_dt(f64 dt) noexcept { dt_ = dt; }
+  /// Re-bases the x axis: `x0()`/`x_at()` become `epoch + timestamp`. Used to make
+  /// the axis read seconds from the trigger event instead of from the stream.
+  void set_epoch(f64 e) noexcept { epoch_ = e; }
+  u64 stride() const noexcept { return stride_; }
+
+  // --- plot::data::Series ---------------------------------------------------
+  u64 size() const override { return pyramid_.size(); }
+  f64 x0() const override;
+  /// The *mean* spacing of the retained window. The renderer converts a visible x
+  /// range into an index range with `(x - x0()) / dx()`, so this must describe the
+  /// samples that are actually retained: reporting the nominal `stride * dt` made
+  /// that index range exceed the series by the decimation factor, the gather
+  /// clamped to nothing, and the trace drew empty -- which is exactly what a fast
+  /// channel looked like next to a slow one, because only the slow one is
+  /// recognisable from the few samples a wrong range still happens to cover.
+  f64 dx() const override;
+  /// The authoritative x of a sample: the streamed timestamp, not a grid. `dx()`
+  /// is only the mean spacing (the LOD level and a coarse snap use it); a lost
+  /// datagram leaves a gap, so index times must come from the time ring.
+  f64 x_at(u64 i) const override;
+  /// Bracketing samples by binary search over the time ring, which is monotonic,
+  /// so a crosshair value is interpolated between the two samples actually either
+  /// side of the pointer -- a grid walk would land on the wrong pair after a gap.
+  bool neighbours(f64 x, u64& i0, u64& i1) const override;
+  u64 snap_index(f64 x) const override;
+  plot::Range x_bounds() const override;
+  plot::Range y_bounds() const override;
+  const plot::data::MinMaxPyramid& pyramid() const override { return pyramid_; }
+  /// x is emitted **relative to `x0()`** (the library's contract): staging an
+  /// absolute epoch time as f32 would quantise it far coarser than a pixel.
+  void gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+              plot::data::GatherMode mode = plot::data::GatherMode::Envelope) const override;
+
+  /// `copy_raw`, published so the retargetable trace series can forward the
+  /// protected hook of another object.
+  void raw(u64 begin, u64 end, f32* out) const;
+
+ protected:
+  void copy_raw(u64 begin, u64 end, f32* out) const override { raw(begin, end, out); }
+
+ private:
+  /// Absolute (channel) index of retained-window index `i`.
+  u64 absolute(u64 i) const noexcept { return pyramid_.window_base() + i; }
+  /// Timestamp of channel sample `absolute_index`, in seconds since `epoch_`.
+  f32 time_of(u64 absolute_index) const noexcept;
+
+  std::shared_ptr<const plot::data::RingBuffer<f32>> values_;
+  std::shared_ptr<const plot::data::RingBuffer<f32>> times_;
+  u64 stride_ = 1;
+  f64 epoch_ = 0.0;
+  f64 dt_ = 1.0;
+  u64 published_ = 0;
+  plot::data::MinMaxPyramid pyramid_;
+};
+
+/// A trace's series: one stable object whose channel can be rebound.
+///
+/// `Plot` has no `set_trace_series()` and no `remove_trace()`, so a trace's series
+/// pointer is fixed for the plot's life. Everything that would otherwise need a
+/// new pointer -- which signal a trace plots, and the switch between the live ring
+/// and a frozen event -- is therefore expressed here as a rebind.
+class SlotSeries final : public plot::data::Series {
+ public:
+  /// Takes shared ownership: a structural change in the model may drop its
+  /// `BufferStore` while a trace still points here, and the renderer reads the
+  /// buffer after this frame's bind has returned.
+  void bind(std::shared_ptr<ChannelBuffer> buffer) noexcept {
+    buffer_ = std::move(buffer);
+    event_ = nullptr;
+  }
+  /// Binds the captured event (edge-relative stamps). Binding an event clears
+  /// the ring binding and vice versa: the slot shows exactly one source.
+  void bind_event(std::shared_ptr<const EventSnapshot> snap, std::size_t channel) {
+    if (snap == nullptr || channel >= snap->values.size()) {
+      event_ = nullptr;
+      return;
+    }
+    if (event_ == nullptr || !event_->same(snap, channel)) {
+      event_ = std::make_unique<EventSeries>(std::move(snap), channel);
+    }
+    buffer_ = nullptr;
+  }
+  ChannelBuffer* bound() const noexcept { return buffer_.get(); }
+  const EventSeries* bound_event() const noexcept { return event_.get(); }
+  bool empty() const noexcept {
+    if (event_ != nullptr) return event_->size() == 0;
+    return buffer_ == nullptr || buffer_->size() == 0;
+  }
+
+  u64 size() const override { return event_ != nullptr ? event_->size() : buffer_ != nullptr ? buffer_->size() : 0; }
+  f64 x0() const override { return event_ != nullptr ? event_->x0() : buffer_ != nullptr ? buffer_->x0() : 0.0; }
+  f64 dx() const override { return event_ != nullptr ? event_->dx() : buffer_ != nullptr ? buffer_->dx() : 1.0; }
+  f64 x_at(u64 i) const override;
+  bool neighbours(f64 x, u64& i0, u64& i1) const override;
+  u64 snap_index(f64 x) const override;
+  plot::Range x_bounds() const override;
+  plot::Range y_bounds() const override;
+  const plot::data::MinMaxPyramid& pyramid() const override;
+  void gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+              plot::data::GatherMode mode = plot::data::GatherMode::Envelope) const override;
+  bool streaming() const noexcept override { return event_ == nullptr && buffer_ != nullptr; }
+
+ protected:
+  void copy_raw(u64 begin, u64 end, f32* out) const override;
+
+ private:
+  std::shared_ptr<ChannelBuffer> buffer_;
+  std::unique_ptr<EventSeries> event_;  ///< the captured event, when held
+};
+
+}  // namespace udpscope

src/config.cpp

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "config.hpp"
+
+#include <cstdio>
+#include <cstdlib>
+#include <stdexcept>
+#include <string>
+
+namespace udpscope {
+namespace {
+
+[[noreturn]] void fail(const std::string& what) { throw std::runtime_error(what); }
+
+/// `--name=value` / `--name value`; returns the value and advances `i` past both
+/// spellings. `argv[i]` must start with `--name`.
+std::string value_of(int argc, char** argv, int& i, const char* name) {
+  const std::string arg = argv[i];
+  const std::string prefix = std::string(name) + "=";
+  if (arg.rfind(prefix, 0) == 0) return arg.substr(prefix.size());
+  if (i + 1 >= argc) fail(std::string("missing value for ") + name);
+  return argv[++i];
+}
+
+double parse_double(const char* name, const std::string& v) {
+  try {
+    std::size_t used = 0;
+    const double d = std::stod(v, &used);
+    if (used != v.size()) fail(std::string("not a number: ") + name + " " + v);
+    return d;
+  } catch (const std::exception&) {
+    fail(std::string("not a number: ") + name + " " + v);
+  }
+}
+
+}  // namespace
+
+void print_usage(std::FILE* out, const char* argv0) {
+  std::fprintf(out,
+               "usage: %s --server ADDR --port PORT [options]\n"
+               "\n"
+               "  --server ADDR        stream source IPv4 address (default 127.0.0.1)\n"
+               "  --port PORT          UDP port (unicast) or TCP port (multicast) (default 8000)\n"
+               "  --multicast GROUP    join GROUP for DATA instead of unicast\n"
+               "  --interface ADDR     local IPv4 of the interface to join on\n"
+               "  --buffer-mb MB       size of each of the two sample buffers (default 200)\n"
+               "  --max-window SEC     largest time window the toolbar offers (default 600)\n"
+               "  --holdoff SEC        default trigger hold-off (default 0.010)\n"
+               "  --recv-buffer BYTES  SO_RCVBUF for the receiver socket (default 8388608)\n"
+               "  --plots N            initial number of stacked plots, 1..4 (default 1)\n"
+               "  -h, --help           this text\n",
+               argv0);
+}
+
+Config parse_args(int argc, char** argv) {
+  Config c;
+  for (int i = 1; i < argc; ++i) {
+    const std::string a = argv[i];
+    if (a == "-h" || a == "--help") {
+      print_usage(stdout, argv[0]);
+      std::exit(0);
+    } else if (a == "--server" || a.rfind("--server=", 0) == 0) {
+      c.server = value_of(argc, argv, i, "--server");
+    } else if (a == "--port" || a.rfind("--port=", 0) == 0) {
+      const std::string v = value_of(argc, argv, i, "--port");
+      const long p = std::strtol(v.c_str(), nullptr, 10);
+      if (p <= 0 || p > 65535) fail("port out of range: " + v);
+      c.port = static_cast<std::uint16_t>(p);
+    } else if (a == "--multicast" || a.rfind("--multicast=", 0) == 0) {
+      c.multicast = value_of(argc, argv, i, "--multicast");
+    } else if (a == "--interface" || a.rfind("--interface=", 0) == 0) {
+      c.interface_addr = value_of(argc, argv, i, "--interface");
+    } else if (a == "--buffer-mb" || a.rfind("--buffer-mb=", 0) == 0) {
+      c.buffer_mb = parse_double("--buffer-mb", value_of(argc, argv, i, "--buffer-mb"));
+      if (c.buffer_mb < 1.0) fail("--buffer-mb must be at least 1");
+    } else if (a == "--max-window" || a.rfind("--max-window=", 0) == 0) {
+      c.max_window_s = parse_double("--max-window", value_of(argc, argv, i, "--max-window"));
+      if (c.max_window_s <= 0.0) fail("--max-window must be positive");
+    } else if (a == "--holdoff" || a.rfind("--holdoff=", 0) == 0) {
+      c.trigger_holdoff_s = parse_double("--holdoff", value_of(argc, argv, i, "--holdoff"));
+      if (c.trigger_holdoff_s < 0.0) fail("--holdoff must not be negative");
+    } else if (a == "--recv-buffer" || a.rfind("--recv-buffer=", 0) == 0) {
+      const std::string v = value_of(argc, argv, i, "--recv-buffer");
+      const long n = std::strtol(v.c_str(), nullptr, 10);
+      if (n <= 0) fail("--recv-buffer must be positive: " + v);
+      c.recv_buffer_bytes = static_cast<int>(n);
+    } else if (a == "--plots" || a.rfind("--plots=", 0) == 0) {
+      const std::string v = value_of(argc, argv, i, "--plots");
+      const long n = std::strtol(v.c_str(), nullptr, 10);
+      if (n < 1 || n > 4) fail("--plots must be 1..4: " + v);
+      c.plots = static_cast<int>(n);
+    } else {
+      fail("unknown argument: " + a);
+    }
+  }
+  return c;
+}
+
+}  // namespace udpscope

src/config.hpp

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace udpscope {
+
+/// Everything the command line can say. Defaults are the ones the spec names
+/// (200 MB per buffer, 10 ms trigger hold-off) unless the user overrides them.
+struct Config {
+  std::string server = "127.0.0.1";   ///< IPv4 dotted quad of the stream source.
+  std::uint16_t port = 8000;          ///< UDP port (unicast) or TCP port (multicast).
+  std::string multicast;              ///< Empty selects unicast.
+  std::string interface_addr;         ///< Local IPv4 to join the group on; empty = default route.
+
+  /// Size of *each* of the two sample buffers, in megabytes. The application
+  /// always allocates two identical buffers (spec item 1).
+  double buffer_mb = 200.0;
+
+  /// Largest time window the toolbar offers, in seconds. The buffer partition is
+  /// sized to hold at least this much time (spec: decimation).
+  double max_window_s = 600.0;
+
+  double trigger_holdoff_s = 0.010;
+  int recv_buffer_bytes = 8 * 1024 * 1024;
+
+  /// Number of stacked plots (rows) to start with, 1..4.
+  int plots = 1;
+};
+
+/// Parses argv. On `--help` prints usage to stdout and exits(0); on a bad
+/// argument prints a diagnostic to stderr and exits(2).
+Config parse_args(int argc, char** argv);
+
+/// Writes the usage text to `out`.
+void print_usage(std::FILE* out, const char* argv0);
+
+}  // namespace udpscope

src/event_series.hpp

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+#pragma once
+
+#include <plot/data/series.hpp>
+
+#include <algorithm>
+#include <memory>
+#include <vector>
+
+namespace udpscope {
+
+using plot::f32;
+using plot::f64;
+using plot::u32;
+using plot::u64;
+
+/// One captured trigger event, immutable once published: per-channel values over
+/// a shared, edge-relative time stamp array (the edge sits at exactly x = 0, the
+/// window spans [-pre, +post]).
+///
+/// The plot binds to a snapshot while the trigger holds an event. Because the
+/// snapshot can never change after publication, nothing can drag, re-base or
+/// refresh the view while it is held -- the failures the previous design (two
+/// live ring buffers switched by a pending flag, plus a display-epoch shift)
+/// could not stop.
+struct EventSnapshot {
+  std::vector<f32> stamps;               ///< edge-relative seconds, monotonic
+  std::vector<std::vector<f32>> values;  ///< one array per channel, same length
+  double pre_s = 0.0;                    ///< seconds of pre-trigger data kept
+  double post_s = 0.0;                   ///< seconds of post-trigger data kept
+  std::vector<plot::Range> y;            ///< per-channel value bounds, precomputed
+};
+
+/// A plot::data::Series view of one channel of an EventSnapshot. The stamps are
+/// near-uniform (the arrival clock), so dx is the mean spacing and x_at returns
+/// the exact stamp; gather decimates by 2^level like the ring series does.
+class EventSeries final : public plot::data::Series {
+ public:
+  explicit EventSeries(std::shared_ptr<const EventSnapshot> snap, std::size_t channel)
+      : snap_(std::move(snap)), channel_(channel) {}
+
+  /// Identity for rebind: same snapshot object and channel means the existing
+  /// EventSeries already shows this event.
+  bool same(const std::shared_ptr<const EventSnapshot>& snap, std::size_t channel) const {
+    return snap_ == snap && channel_ == channel;
+  }
+
+  /// The shorter of the two arrays this series reads. `gather()` indexes `stamps`
+  /// and `values[channel]` at the same i, so reporting the stamp count alone would
+  /// be an out-of-bounds read the moment they differ.
+  u64 size() const override {
+    if (channel_ >= snap_->values.size()) return 0;
+    return static_cast<u64>(
+        std::min(snap_->stamps.size(), snap_->values[channel_].size()));
+  }
+  f64 x0() const override { return snap_->stamps.empty() ? 0.0 : snap_->stamps.front(); }
+  f64 dx() const override {
+    const auto& s = snap_->stamps;
+    return s.size() > 1 ? (s.back() - s.front()) / static_cast<f64>(s.size() - 1) : 1.0;
+  }
+  f64 x_at(u64 i) const override {
+    const auto& s = snap_->stamps;
+    return i < s.size() ? s[static_cast<std::size_t>(i)] : 0.0;
+  }
+  plot::Range x_bounds() const override {
+    const auto& s = snap_->stamps;
+    return s.empty() ? plot::Range{0.0, 0.0} : plot::Range{s.front(), s.back()};
+  }
+  plot::Range y_bounds() const override {
+    return channel_ < snap_->y.size() ? snap_->y[channel_] : plot::Range{0.0, 0.0};
+  }
+  const plot::data::MinMaxPyramid& pyramid() const override { return empty_pyramid_; }
+  bool streaming() const noexcept override { return false; }
+
+  void gather(u32 level, u64 begin, u64 end, std::vector<f32>& out_xy,
+              plot::data::GatherMode /*mode*/ =
+                  plot::data::GatherMode::Envelope) const override {
+    if (channel_ >= snap_->values.size()) return;
+    const auto& vals = snap_->values[channel_];
+    const auto& stamps = snap_->stamps;
+    const u64 n = size();
+    const u64 stride = u64{1} << level;
+    if (stride == 0 || begin >= n) return;
+    if (end > n) end = n;
+    // x **relative to x0()**, which is the library's gather contract: the renderer
+    // adds `x0()` back before mapping to the screen. Emitting the absolute stamp made
+    // it add x0 twice, so the whole capture was drawn one `x0()` -- a full
+    // pre-trigger window -- to the left of the axis it had just been measured
+    // against. The event's own stamps are small (edge-relative, so [-pre, +post]),
+    // which is why that shift looked like a plausible picture: with a 50/50 split the
+    // right half of the plot was simply empty, zooming out showed the trace ending at
+    // the x = 0 marker, and zooming in past the shift showed nothing at all while the
+    // crosshair -- which reads `x_at()`, never `gather()` -- went on reporting the
+    // right values.
+    const f64 base = x0();
+    out_xy.reserve(out_xy.size() + static_cast<std::size_t>((end - begin) / stride * 2 + 4));
+    for (u64 i = (begin / stride) * stride; i < end; i += stride) {
+      out_xy.push_back(static_cast<f32>(stamps[static_cast<std::size_t>(i)] - base));
+      out_xy.push_back(vals[static_cast<std::size_t>(i)]);
+    }
+  }
+
+  bool neighbours(f64 x, u64& i0, u64& i1) const override {
+    const u64 n = size();
+    if (n < 2) return false;
+    const f64 step = dx();
+    if (!(step > 0.0)) return false;
+    f64 idx = (x - x0()) / step;
+    if (idx < 0.0) idx = 0.0;
+    if (idx > static_cast<f64>(n - 1)) idx = static_cast<f64>(n - 1);
+    i0 = static_cast<u64>(idx);
+    i1 = i0 + 1 < n ? i0 + 1 : i0;
+    return true;
+  }
+  u64 snap_index(f64 x) const override {
+    u64 i0 = 0, i1 = 0;
+    if (!neighbours(x, i0, i1)) return 0;
+    return i1;
+  }
+
+  /// SlotSeries::copy_raw forwards here (public: the base's hook is protected,
+  /// and SlotSeries is a different class).
+  void raw_values(u64 begin, u64 end, f32* out) const {
+    const auto& vals = snap_->values[channel_];
+    const u64 n = static_cast<u64>(vals.size());
+    if (end > n) end = n;
+    for (u64 i = begin; i < end; ++i)
+      out[static_cast<std::size_t>(i - begin)] = vals[static_cast<std::size_t>(i)];
+  }
+
+ protected:
+  void copy_raw(u64 begin, u64 end, f32* out) const override { raw_values(begin, end, out); }
+
+ private:
+  std::shared_ptr<const EventSnapshot> snap_;
+  std::size_t channel_;
+  plot::data::MinMaxPyramid empty_pyramid_{};
+};
+
+}  // namespace udpscope

src/export.cpp

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "export.hpp"
+
+#include <algorithm>
+#include <bit>
+#include <cerrno>
+#include <cstdio>
+#include <cstring>
+
+namespace udpscope {
+namespace {
+
+// The writers memcpy `f64`/`f32` straight out and label them `<f8`/`<f4`, so a
+// big-endian host would produce a file whose bytes contradict its own dtype. There is no
+// such host in this app's reach and a byte-swapping path nobody runs is a path nobody
+// tests, so the assumption is stated instead of handled.
+static_assert(std::endian::native == std::endian::little,
+              "the .npy writer labels its fields little-endian and does not swap");
+
+/// A column label a reader can use: NumPy rejects duplicate field names outright, and a
+/// quote or a brace in one would break the header dict it is spelled into. Signal names
+/// come from the stream, so neither is this app's to promise.
+std::string sanitise(const std::string& name) {
+  std::string out;
+  out.reserve(name.size());
+  for (const char ch : name) {
+    const bool ok = (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+                    (ch >= '0' && ch <= '9') || ch == '_';
+    out.push_back(ok ? ch : '_');
+  }
+  if (out.empty()) out = "col";
+  return out;
+}
+
+/// The final labels: sanitised, and de-duplicated against each other *and* against the
+/// two time columns, with a `_2`, `_3` suffix. Two elements of one vector signal can
+/// easily sanitise to the same string.
+std::vector<std::string> column_labels(const ExportTable& table) {
+  std::vector<std::string> taken{"time", "stream_time"};
+  std::vector<std::string> out;
+  out.reserve(table.columns.size());
+  for (const ExportTable::Column& col : table.columns) {
+    const std::string base = sanitise(col.name);
+    std::string label = base;
+    for (int n = 2; std::find(taken.begin(), taken.end(), label) != taken.end(); ++n) {
+      label = base + "_" + std::to_string(n);
+    }
+    taken.push_back(label);
+    out.push_back(std::move(label));
+  }
+  return out;
+}
+
+struct File {
+  explicit File(const std::string& path) : f(std::fopen(path.c_str(), "wb")) {}
+  ~File() {
+    if (f != nullptr) std::fclose(f);
+  }
+  File(const File&) = delete;
+  File& operator=(const File&) = delete;
+  std::FILE* f = nullptr;
+};
+
+bool opened(const File& out, const std::string& path, std::string& error) {
+  if (out.f != nullptr) return true;
+  error = "cannot write '" + path + "': " + std::strerror(errno);
+  return false;
+}
+
+}  // namespace
+
+ExportTable collect_export(ScopeModel& model, RowSet& rows) {
+  ExportTable table;
+  const RowSet::Row& r0 = rows.row(0);
+  if (r0.plot == nullptr) return table;
+  const plot::Range view = r0.plot->x_range(r0.axis_x);
+
+  // Which channels: every bound slot on a visible row, de-duplicated, then sorted. A
+  // signal dropped on two rows is one column, and channel order is the signal list's
+  // order, so the columns read in the same order as the panel.
+  std::vector<int> chans;
+  for (int i = 0; i < rows.row_count(); ++i) {
+    for (int s = 0; s < RowSet::kSlotsPerRow; ++s) {
+      const int c = rows.channel_of(i, s);
+      if (c >= 0 && std::find(chans.begin(), chans.end(), c) == chans.end()) {
+        chans.push_back(c);
+      }
+    }
+  }
+  std::sort(chans.begin(), chans.end());
+  if (chans.empty()) return table;
+
+  const std::vector<ChannelInfo>& infos = model.channels();
+  const auto name_of = [&](int c) {
+    return static_cast<std::size_t>(c) < infos.size() ? infos[static_cast<std::size_t>(c)].name
+                                                     : std::string("ch") + std::to_string(c);
+  };
+
+  // What the rows bind to is what gets exported, which is the same branch `RowSet::bind()`
+  // takes: the frozen event in trigger mode, the live ring otherwise. Reading the ring
+  // while an event is on screen would export data the user cannot see.
+  std::shared_ptr<const EventSnapshot> snap = model.event();
+  if (model.trigger_enabled() && snap != nullptr) {
+    // The snapshot is immutable and already index-aligned, so the visible window is two
+    // binary searches over its stamps and the same index range for every channel.
+    const std::vector<f32>& st = snap->stamps;
+    const auto lo = std::lower_bound(st.begin(), st.end(), static_cast<f32>(view.min));
+    const auto hi = std::upper_bound(st.begin(), st.end(), static_cast<f32>(view.max));
+    if (hi <= lo) return table;
+    const std::size_t first = static_cast<std::size_t>(lo - st.begin());
+    const std::size_t n = static_cast<std::size_t>(hi - lo);
+    // The event's x = 0 is the edge, so the stream clock has to be added back for the
+    // second column -- the one case where the visible x is not the stream's own.
+    const f64 edge = model.trigger_time().load(std::memory_order_relaxed);
+
+    table.time.resize(n);
+    table.stream_time.resize(n);
+    for (std::size_t i = 0; i < n; ++i) {
+      table.time[i] = static_cast<f64>(st[first + i]);
+      table.stream_time[i] = edge + table.time[i];
+    }
+    for (const int c : chans) {
+      const std::size_t ch = static_cast<std::size_t>(c);
+      if (ch >= snap->values.size()) continue;
+      const std::vector<f32>& src = snap->values[ch];
+      if (src.size() < first + n) continue;
+      table.columns.push_back({name_of(c), std::vector<f32>(src.begin() + static_cast<std::ptrdiff_t>(first),
+                                                            src.begin() + static_cast<std::ptrdiff_t>(first + n))});
+    }
+    return table;
+  }
+
+  // Live: one absolute index range over the shared time ring, used for every channel --
+  // `live_window_locked()` is the same cut a latch makes, so an export and a capture of
+  // the same window hold the same samples. The lock is against a structural change
+  // dropping the rings under the copy, which is what the UI thread has to fear here.
+  std::lock_guard<std::mutex> lock(model.mutex());
+  // The axis reads `display_epoch + stamp`, so the window has to be put back on the
+  // stream's clock before the ring is searched. It is 0 in live mode, but reading it is
+  // what keeps this correct rather than merely true today.
+  const f64 epoch = model.display_epoch();
+  u64 first = 0, last = 0;
+  model.live_window_locked(view.min - epoch, view.max - epoch, first, last);
+  const u64 n = last - first;
+  if (n == 0) return table;
+
+  BufferStore& store = model.live();
+  std::vector<f32> stamps(static_cast<std::size_t>(n));
+  store.time().copy_from(first, n, stamps.data());
+  table.time.resize(static_cast<std::size_t>(n));
+  table.stream_time.resize(static_cast<std::size_t>(n));
+  for (std::size_t i = 0; i < stamps.size(); ++i) {
+    table.stream_time[i] = static_cast<f64>(stamps[i]);
+    table.time[i] = epoch + table.stream_time[i];
+  }
+  for (const int c : chans) {
+    const std::size_t ch = static_cast<std::size_t>(c);
+    if (ch >= model.channel_count()) continue;
+    std::vector<f32> values(static_cast<std::size_t>(n));
+    store.values(ch).copy_from(first, n, values.data());
+    table.columns.push_back({name_of(c), std::move(values)});
+  }
+  return table;
+}
+
+bool write_npy(const std::string& path, const ExportTable& table, std::string& error) {
+  if (table.empty()) {
+    error = "nothing to export: no signal is plotted in the visible range";
+    return false;
+  }
+  const std::vector<std::string> labels = column_labels(table);
+
+  // `descr` as a list of (name, format) pairs is a *packed* structured dtype -- NumPy
+  // only inserts alignment padding when asked to (`align=True`) -- so the records below
+  // are field widths back to back with no gaps.
+  std::string descr = "[('time', '<f8'), ('stream_time', '<f8')";
+  for (const std::string& label : labels) descr += ", ('" + label + "', '<f4')";
+  descr += "]";
+  std::string header = "{'descr': " + descr + ", 'fortran_order': False, 'shape': (" +
+                       std::to_string(table.rows()) + ",), }";
+  // v1.0: a 6-byte magic, 2 version bytes and a 2-byte little-endian header length, and
+  // the whole preamble padded so the data starts on a 64-byte boundary.
+  constexpr std::size_t kPreamble = 10;
+  const std::size_t unpadded = kPreamble + header.size() + 1;
+  const std::size_t padded = (unpadded + 63) / 64 * 64;
+  header.append(padded - unpadded, ' ');
+  header.push_back('\n');
+  if (header.size() > 0xFFFFu) {
+    error = "too many columns for a v1.0 .npy header";
+    return false;
+  }
+
+  File out(path);
+  if (!opened(out, path, error)) return false;
+  const unsigned char len[2] = {static_cast<unsigned char>(header.size() & 0xFFu),
+                                static_cast<unsigned char>((header.size() >> 8) & 0xFFu)};
+  std::fwrite("\x93NUMPY\x01\x00", 1, 8, out.f);
+  std::fwrite(len, 1, 2, out.f);
+  std::fwrite(header.data(), 1, header.size(), out.f);
+
+  // One record at a time, into a reused buffer: a column-major staging array would be a
+  // second copy of the whole export, which at a full ring is tens of megabytes.
+  std::vector<unsigned char> record(2 * sizeof(f64) + table.columns.size() * sizeof(f32));
+  for (std::size_t i = 0; i < table.rows(); ++i) {
+    std::size_t at = 0;
+    std::memcpy(record.data() + at, &table.time[i], sizeof(f64));
+    at += sizeof(f64);
+    std::memcpy(record.data() + at, &table.stream_time[i], sizeof(f64));
+    at += sizeof(f64);
+    for (const ExportTable::Column& col : table.columns) {
+      const f32 v = i < col.values.size() ? col.values[i] : 0.0f;
+      std::memcpy(record.data() + at, &v, sizeof(f32));
+      at += sizeof(f32);
+    }
+    if (std::fwrite(record.data(), 1, record.size(), out.f) != record.size()) {
+      error = "short write to '" + path + "': " + std::strerror(errno);
+      return false;
+    }
+  }
+  if (std::fflush(out.f) != 0) {
+    error = "cannot flush '" + path + "': " + std::strerror(errno);
+    return false;
+  }
+  return true;
+}
+
+bool write_csv(const std::string& path, const ExportTable& table, std::string& error) {
+  if (table.empty()) {
+    error = "nothing to export: no signal is plotted in the visible range";
+    return false;
+  }
+  File out(path);
+  if (!opened(out, path, error)) return false;
+
+  const std::vector<std::string> labels = column_labels(table);
+  std::string line = "time,stream_time";
+  for (const std::string& label : labels) line += "," + label;
+  line += "\n";
+  std::fwrite(line.data(), 1, line.size(), out.f);
+
+  // `%.17g` for the f64 times and `%.9g` for the f32 values: the shortest widths that
+  // round-trip each type exactly. Anything less silently rewrites the samples, which is
+  // the one thing an export may not do.
+  char buf[64];
+  for (std::size_t i = 0; i < table.rows(); ++i) {
+    line.clear();
+    std::snprintf(buf, sizeof(buf), "%.17g", table.time[i]);
+    line += buf;
+    std::snprintf(buf, sizeof(buf), "%.17g", table.stream_time[i]);
+    line += ",";
+    line += buf;
+    for (const ExportTable::Column& col : table.columns) {
+      std::snprintf(buf, sizeof(buf), "%.9g",
+                    double(i < col.values.size() ? col.values[i] : 0.0f));
+      line += ",";
+      line += buf;
+    }
+    line += "\n";
+    if (std::fwrite(line.data(), 1, line.size(), out.f) != line.size()) {
+      error = "short write to '" + path + "': " + std::strerror(errno);
+      return false;
+    }
+  }
+  if (std::fflush(out.f) != 0) {
+    error = "cannot flush '" + path + "': " + std::strerror(errno);
+    return false;
+  }
+  return true;
+}
+
+}  // namespace udpscope

src/export.hpp

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include "model.hpp"
+#include "plot_host.hpp"
+
+#include <string>
+#include <vector>
+
+namespace udpscope {
+
+/// What the plots are showing, as a table: one row per sample of the visible x window,
+/// one column per plotted signal.
+///
+/// The samples are the *stored* ones, never the LOD pyramid's buckets: the pyramid is
+/// what makes a million samples drawable in a few hundred pixels, and exporting it would
+/// hand back the envelope the renderer drew rather than the acquisition. So an export is
+/// at the full rate the ring holds, however far the view is zoomed out.
+struct ExportTable {
+  struct Column {
+    std::string name;         ///< the legend name, sanitised for a column label
+    std::vector<f32> values;  ///< `rows()` long, the ring's own `f32`
+  };
+
+  /// The x the plot shows and the crosshair reads: stream seconds in live mode,
+  /// edge-relative seconds in `[-pre, +post]` while an event is held.
+  std::vector<f64> time;
+  /// The stream's own clock, so two exports taken in different modes line up. Equal to
+  /// `time` in live mode; `time + trigger_time` while an event is held, which is the one
+  /// case where the visible x is not the stream's.
+  std::vector<f64> stream_time;
+  std::vector<Column> columns;
+
+  std::size_t rows() const noexcept { return time.size(); }
+  bool empty() const noexcept { return columns.empty() || time.empty(); }
+};
+
+/// Collects every signal bound to a visible row, over the shared x window, at the stored
+/// rate. A signal on several rows is one column; the columns come out in channel order,
+/// which is the signal list's order.
+///
+/// Takes `model.mutex()` for the live cut, so call it from the GTK thread like any other
+/// model access. In trigger mode nothing is locked: the `EventSnapshot` is immutable.
+ExportTable collect_export(ScopeModel& model, RowSet& rows);
+
+/// Writes a NumPy `.npy` file holding one structured array: `time` and `stream_time` as
+/// `<f8`, every signal as `<f4` -- the width the ring actually stores, so the file is
+/// about half the size of an all-`f8` one and invents no precision.
+///
+/// `pd.DataFrame(np.load(path))` is the whole reader.
+bool write_npy(const std::string& path, const ExportTable& table, std::string& error);
+
+/// Writes the same table as CSV: a header row of column names, then `%.*g` fields --
+/// enough digits to round-trip each column's own type and no more.
+bool write_csv(const std::string& path, const ExportTable& table, std::string& error);
+
+}  // namespace udpscope

src/main.cpp

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "acquisition.hpp"
+#include "config.hpp"
+#include "model.hpp"
+#include "plot_host.hpp"
+#include "ui.hpp"
+
+#include <cstdio>
+#include <exception>
+
+int main(int argc, char** argv) {
+  udpscope::Config cfg;
+  try {
+    cfg = udpscope::parse_args(argc, argv);
+  } catch (const std::exception& e) {
+    std::fprintf(stderr, "udpscope: %s\n", e.what());
+    return 2;
+  }
+
+  udpscope::ScopeModel model(cfg);
+  udpscope::RowSet rows;
+  rows.set_row_count(cfg.plots);
+  udpscope::Acquisition acquisition(model, cfg);
+  try {
+    acquisition.start();
+  } catch (const std::exception& e) {
+    std::fprintf(stderr, "udpscope: %s\n", e.what());
+    return 1;
+  }
+
+  const int result = udpscope::run_ui(argc, argv, model, acquisition, rows);
+  acquisition.stop();
+  return result;
+}

src/model.cpp

@@ -0,0 +1,378 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "model.hpp"
+
+#include <udps_client.h>
+
+#include <algorithm>
+#include <cmath>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+
+namespace udpscope {
+namespace {
+
+u64 pow2_floor(u64 v) {
+  if (v == 0) return 0;
+  u64 p = 1;
+  while (p <= v / 2) p <<= 1;
+  return p;
+}
+
+}  // namespace
+
+u64 Partition::total_samples() const noexcept {
+  u64 total = time_capacity;
+  for (u64 c : value_capacity) total += c;
+  return total;
+}
+
+Partition plan_partition(const std::vector<double>& channel_dt, double buffer_bytes) {
+  Partition p;
+  const std::size_t n = channel_dt.size();
+  p.stride.assign(n, 1);
+  p.value_capacity.assign(n, 0);
+  if (n == 0) return p;
+
+  // The fastest channel drives the shared time base: every other channel is
+  // decimated by the integer ratio of its own interval to that one.
+  double base_dt = 0.0;
+  for (double dt : channel_dt) {
+    if (dt > 0.0) base_dt = base_dt > 0.0 ? std::min(base_dt, dt) : dt;
+  }
+  // No declared rate: assume 1 kHz rather than one sample per second, so a
+  // stream that only says "here are samples" still gets a sane time scale and a
+  // sane first frame in `Acquisition::build_stamps()`.
+  if (!(base_dt > 0.0)) base_dt = 1.0e-3;
+  p.base_dt = base_dt;
+
+  // No per-channel decimation, and none on the shared clock either. A stride of
+  // `round(dt_i / dt_fastest)` throws away all but one sample per stride, and when
+  // that stride equals the signal's own period -- a 2 kHz sine on a 1 MHz clock,
+  // stride 500 -- every kept sample sits at the same phase: the channel plots as a
+  // flat line. Decimating the shared clock to make a 600 s window fit did the same
+  // to *every* channel. The LOD min/max pyramid is what preserves the extremes at
+  // draw time, and it needs the real samples; the buffer simply holds as many as
+  // it holds, and the window dropdown is capped to that span.
+  for (std::size_t i = 0; i < n; ++i) p.stride[i] = 1;
+  p.time_stride = 1;
+
+  const u64 budget_bytes = static_cast<u64>(std::max(1.0, buffer_bytes));
+  const u64 budget = budget_bytes / sizeof(f32);
+  double weight = 1.0;  // the time slice itself
+  for (u64 s : p.stride) weight += 1.0 / static_cast<double>(s);
+
+  const u64 slots = budget / static_cast<u64>(std::llround(weight));
+  u64 time_capacity = pow2_floor(std::max<u64>(slots, 128));
+  if (time_capacity == 0) {
+    throw std::runtime_error("buffer too small for one time-base sample per channel");
+  }
+
+  // The target span sets a floor, not a ceiling: the rest of the budget buys a
+  // longer ring, which is strictly more history to scroll back through. Growth
+  // stops before the total would exceed the budget. A channel's slots are rounded
+  // *up* on the power of two `RingBuffer` will round them to anyway, so every
+  // channel covers at least the time ring's span.
+  // Floor, not ceiling: a channel's window must not be *longer* than the time ring
+  // it reads its stamps from. Rounding up (with a stride that is not a power of two)
+  // gave a channel more samples than the shared timeline covers, and the oldest of
+  // them referenced time slots the ring had already overwritten -- they were then
+  // stamped with the epoch, a plausible-looking coordinate that collapsed the trace
+  // against the axis. Flooring can leave a channel holding as little as ~62% of the
+  // time ring's span, which is a shorter history, not a wrong one.
+  const auto capacity_for = [&](u64 ticks, u64 stride) {
+    return std::max<u64>(pow2_floor(ticks / stride), 1);
+  };
+  const auto bytes_for = [&](u64 ticks) {
+    u64 total = ticks;
+    for (u64 s : p.stride) total += capacity_for(ticks, s);
+    return total * sizeof(f32);
+  };
+  while (time_capacity * 2 <= budget && bytes_for(time_capacity * 2) <= budget_bytes) {
+    time_capacity *= 2;
+  }
+  p.time_capacity = time_capacity;
+  for (std::size_t i = 0; i < n; ++i) {
+    p.value_capacity[i] = capacity_for(p.time_capacity, p.stride[i]);
+  }
+  p.span_s = static_cast<double>(p.time_capacity) * static_cast<double>(p.time_stride) * base_dt;
+  return p;
+}
+
+// --- BufferStore ------------------------------------------------------------
+
+BufferStore::BufferStore(const Partition& part, f64 span_s)
+    : part_(part),
+      time_(std::make_shared<plot::data::RingBuffer<f32>>(part.time_capacity)) {
+  (void)span_s;
+  const std::size_t n = part.value_capacity.size();
+  values_.reserve(n);
+  channels_.reserve(n);
+  for (std::size_t i = 0; i < n; ++i) {
+    values_.push_back(std::make_shared<plot::data::RingBuffer<f32>>(part.value_capacity[i]));
+    // `ChannelBuffer::dx()` multiplies this by the channel's stride, so the
+    // value here is the *slot* interval: stride * slot_dt is the real sample
+    // interval at the decimation the partition chose.
+    const double dt = part.slot_dt();
+    channels_.push_back(std::make_shared<ChannelBuffer>(values_[i], time_, part.stride[i], 0.0,
+                                                        dt));
+  }
+}
+
+void BufferStore::acquire_all() {
+  for (auto& c : channels_) c->acquire();
+}
+
+// --- ScopeModel -------------------------------------------------------------
+
+ScopeModel::ScopeModel(const Config& cfg) : cfg_(cfg) {
+  trigger_.holdoff_s = cfg.trigger_holdoff_s;
+}
+
+void ScopeModel::set_signals(std::vector<SignalInfo> signals) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  // Keep the enable state across CONFIG updates for signals that kept their name.
+  std::unordered_map<std::string, bool> was_enabled;
+  for (std::size_t i = 0; i < signals_.size(); ++i) {
+    was_enabled.emplace(signals_[i].name, i < enabled_.size() ? enabled_[i] : false);
+  }
+  signals_ = std::move(signals);
+  enabled_.assign(signals_.size(), false);
+  for (std::size_t i = 0; i < signals_.size(); ++i) {
+    auto it = was_enabled.find(signals_[i].name);
+    // Off until the user enables it (spec: the signal panel's switch is what
+    // starts acquisition of a signal). A later CONFIG keeps whatever the user
+    // chose for a signal that kept its name.
+    enabled_[i] = it != was_enabled.end() ? it->second : false;
+  }
+  rebuild_channels();
+  rebuild_locked();
+  generation_.fetch_add(1, std::memory_order_release);
+}
+
+void ScopeModel::rebuild_channels() {
+  channels_.clear();
+  for (std::size_t s = 0; s < signals_.size(); ++s) {
+    const SignalInfo& sig = signals_[s];
+    if (s >= enabled_.size() || !enabled_[s]) continue;
+    if (is_time_signal(signals_, s)) continue;
+    ChannelInfo ch;
+    ch.signal = s;
+    ch.enabled = true;
+    // A UDPStreamer signal is one channel: its columns are consecutive samples of
+    // that channel within a DATA packet (1x1000 is 1000 samples of the same
+    // signal, not 1000 signals). The worker client hands a multi-element signal
+    // exactly `elements` values per packet, which is the block of samples.
+    ch.name = sig.name;
+    ch.unit = sig.unit;
+    ch.elements = sig.elements();
+    ch.dt = sig.sampling_rate > 0.0 ? 1.0 / sig.sampling_rate : 0.0;
+    channels_.push_back(std::move(ch));
+  }
+}
+
+void ScopeModel::rebuild_locked() {
+  std::vector<double> dts;
+  dts.reserve(channels_.size());
+  for (const ChannelInfo& c : channels_) dts.push_back(c.dt);
+
+  if (dts.empty()) {
+    part_ = Partition{};
+    store_.reset();
+    return;
+  }
+
+  part_ = plan_partition(dts, cfg_.buffer_mb * 1024.0 * 1024.0);
+  store_ = std::make_unique<BufferStore>(part_, part_.span_s);
+
+  if (trigger_.channel >= static_cast<int>(channels_.size())) trigger_.channel = -1;
+}
+
+bool ScopeModel::is_time_signal(const std::vector<SignalInfo>& signals,
+                                std::size_t signal) {
+  if (signal >= signals.size()) return false;
+  const SignalInfo& s = signals[signal];
+  // Referenced by name: another signal declares this one as its time base.
+  for (const SignalInfo& other : signals) {
+    if (other.time_signal_idx == signal) return true;
+  }
+  // A full-array signal that declares **no sample rate** is the stream's timestamp
+  // signal: it has stamps but no cadence of its own, because it is not data.
+  // Data channels can also be declared full-array (per-element stamps), and they
+  // keep a declared rate -- treating them as time signals hid every real channel.
+  if (s.time_mode == UDPS_TIME_FULL_ARRAY && s.elements() > 1 && s.sampling_rate == 0.0) {
+    return true;
+  }
+  return false;
+}
+
+bool ScopeModel::signal_enabled(std::size_t signal) const {
+  return signal < enabled_.size() && enabled_[signal];
+}
+
+void ScopeModel::set_signal_enabled(std::size_t signal, bool on) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  if (signal >= enabled_.size() || enabled_[signal] == on) return;
+  enabled_[signal] = on;
+  // The trigger names a channel by its display name, which is stable across
+  // renumbering: when its own signal is disabled the channel vanishes (the trigger
+  // then waits, and comes back when the signal is re-enabled).
+  const int old_trigger = trigger_.channel;
+  const std::string trigger_name =
+      (old_trigger >= 0 && old_trigger < static_cast<int>(channels_.size()))
+          ? channels_[static_cast<std::size_t>(old_trigger)].name
+          : std::string();
+  rebuild_channels();
+  trigger_.channel = -1;
+  if (!trigger_name.empty()) {
+    for (std::size_t i = 0; i < channels_.size(); ++i) {
+      if (channels_[i].name == trigger_name) trigger_.channel = static_cast<int>(i);
+    }
+  }
+  rebuild_locked();
+  generation_.fetch_add(1, std::memory_order_release);
+}
+
+void ScopeModel::set_calibration(std::size_t signal, double gain, double offset) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  bool any = false;
+  for (ChannelInfo& c : channels_) {
+    if (c.signal != signal) continue;
+    c.gain = gain;
+    c.offset = offset;
+    any = true;
+  }
+  // Calibration is applied at ingest, so the buffers are rebuilt to avoid mixing
+  // calibrated and uncalibrated samples (and stale LOD aggregates).
+  if (any) {
+    rebuild_locked();
+    generation_.fetch_add(1, std::memory_order_release);
+  }
+}
+
+double ScopeModel::channel_dt(std::size_t channel) const {
+  return channel < channels_.size() ? channels_[channel].dt : 0.0;
+}
+
+BufferStore& ScopeModel::live() { return *store_; }
+
+void ScopeModel::live_window_locked(double lo_s, double hi_s, u64& first, u64& last) {
+  BufferStore& src = live();
+  plot::data::RingBuffer<f32>& tsrc = src.time();
+
+  // The slice is one absolute index range, found in the time ring and then shared by
+  // every value ring. Sharing it is what makes a cut's stamps and each of its channels
+  // the same length and index-aligned *by construction*, instead of by two independent
+  // truncations that could disagree.
+  const u64 tbase = tsrc.produced() - tsrc.size();
+  const u64 tend = tsrc.produced();
+  // The bounds are rounded to the ring's own `f32` before they are compared against
+  // it. The window arrives in f64 and the stamps are stored as f32, so an f64
+  // comparison decides a sample that sits exactly on a bound by which way its stamp
+  // happened to round -- the same nominal window then keeps or drops its first sample
+  // depending on how large the stream time is (`f32(38.001) < 38.001` but
+  // `f32(18.001) > 18.001`). One sample is invisible at 10 kS/s and a third of the
+  // capture at 1 S/s. Comparing in the stored type makes a bound that lands on a
+  // sample include it, always.
+  const f32 t_lo = static_cast<f32>(lo_s);
+  const f32 t_hi = static_cast<f32>(hi_s);
+
+  // Stream time is non-decreasing, so the bounds are a binary search. Searching the
+  // stamps is the whole point: the window is in seconds and this ring is the only
+  // thing that knows how many samples a second of this stream holds.
+  u64 a = tbase, b = tend;
+  while (a < b) {
+    const u64 m = a + (b - a) / 2;
+    if (tsrc[m - tbase] < t_lo) {
+      a = m + 1;
+    } else {
+      b = m;
+    }
+  }
+  first = a;
+  b = tend;
+  while (a < b) {
+    const u64 m = a + (b - a) / 2;
+    if (tsrc[m - tbase] <= t_hi) {
+      a = m + 1;
+    } else {
+      b = m;
+    }
+  }
+  last = a;
+
+  for (std::size_t c = 0; c < channels_.size(); ++c) {
+    plot::data::RingBuffer<f32>& from = src.values(c);
+    first = std::max(first, from.produced() - from.size());
+    last = std::min(last, from.produced());
+  }
+  if (last < first) last = first;
+}
+
+void ScopeModel::publish_event(double pre_s, double post_s, double edge) {
+  auto snap = std::make_shared<EventSnapshot>();
+  BufferStore& src = live();
+  plot::data::RingBuffer<f32>& tsrc = src.time();
+
+  u64 first = 0, last = 0;
+  live_window_locked(edge - std::max(0.0, pre_s), edge + std::max(0.0, post_s), first, last);
+  const u64 n = last - first;
+
+  snap->stamps.resize(static_cast<std::size_t>(n));
+  if (n > 0) {
+    tsrc.copy_from(first, n, snap->stamps.data());
+    // Edge-relative from here on: the frozen event reads [-pre, +post] with the
+    // edge at exactly 0, with no axis-level shift any other code path could
+    // disagree with.
+    for (auto& t : snap->stamps) t -= static_cast<f32>(edge);
+  }
+
+  snap->values.resize(channels_.size());
+  snap->y.resize(channels_.size(), plot::Range{0.0, 0.0});
+  for (std::size_t c = 0; c < channels_.size(); ++c) {
+    auto& vals = snap->values[c];
+    vals.resize(static_cast<std::size_t>(n));
+    if (n > 0) src.values(c).copy_from(first, n, vals.data());
+    f32 lo = vals.empty() ? 0.0f : vals.front();
+    f32 hi = lo;
+    for (f32 v : vals) {
+      lo = std::min(lo, v);
+      hi = std::max(hi, v);
+    }
+    snap->y[c] = plot::Range{lo, hi};
+  }
+
+  // The span is read off the stamps that were actually captured, never off the
+  // request: the ring may not reach back a full `pre_s`, and the producer stops the
+  // capture at the first sample past `post_s` rather than exactly on it.
+  snap->pre_s = snap->stamps.empty() ? 0.0 : -static_cast<double>(snap->stamps.front());
+  snap->post_s = snap->stamps.empty() ? 0.0 : static_cast<double>(snap->stamps.back());
+  event_.store(std::move(snap), std::memory_order_release);
+}
+
+void BufferStore::set_epoch(f64 epoch) noexcept {
+  for (auto& c : channels_) c->set_epoch(epoch);
+}
+
+void ScopeModel::set_display_epoch(f64 e) noexcept {
+  display_epoch_.store(e, std::memory_order_relaxed);
+  if (store_) store_->set_epoch(e);
+}
+
+void ScopeModel::acquire_all() {
+  if (store_) store_->acquire_all();
+}
+
+void ScopeModel::set_trigger_enabled(bool on) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  trigger_.enabled = on;
+  trigger_enabled_.store(on, std::memory_order_relaxed);
+}
+
+void ScopeModel::set_epoch_if_unset(f64 e) noexcept {
+  if (epoch_ == 0.0) epoch_ = e;
+}
+
+}  // namespace udpscope

src/model.hpp

@@ -0,0 +1,297 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include "channel.hpp"
+#include "config.hpp"
+#include "event_series.hpp"
+#include "trigger.hpp"
+
+#include <plot/data/ring_buffer.hpp>
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace udpscope {
+
+/// One streamed signal, as the CONFIG packet described it.
+struct SignalInfo {
+  std::string name;
+  std::string unit;
+  std::uint8_t type_code = 0;
+  std::uint8_t quant_type = 0;
+  std::uint32_t rows = 1;
+  std::uint32_t cols = 1;
+  double range_min = 0.0;
+  double range_max = 1.0;
+  std::uint8_t time_mode = 0;
+  double sampling_rate = 0.0;
+  std::uint32_t time_signal_idx = 0xFFFFFFFFu;
+
+  std::uint32_t elements() const noexcept {
+    const std::uint32_t n = rows * cols;
+    return n == 0 ? 1u : n;
+  }
+};
+
+/// One plottable signal element: a signal with a single element, or one element
+/// of a vector/matrix signal. The unit of enable/disable is the *signal*; the
+/// unit of acquisition and plotting is the channel.
+struct ChannelInfo {
+  std::size_t signal = 0;
+  bool enabled = false;   ///< whether its signal is enabled
+  double gain = 1.0;      ///< calibration, applied as sample * gain + offset
+  double offset = 0.0;
+
+  std::string name;       ///< the signal's name
+  std::string unit;
+
+  /// Samples of this channel per DATA packet (`elements()` of the signal). A
+  /// UDPStreamer signal is one channel: its columns are consecutive samples of the
+  /// same signal, not separate channels.
+  std::uint32_t elements = 1;
+
+  /// Sample interval of this channel's own cadence, in seconds. 0 when unknown.
+  double dt = 0.0;
+};
+
+/// How one buffer's storage is divided between the shared time base and the
+/// channels (spec item 2: "split in N+1", the +1 being the time base).
+///
+/// The split is by *time span*, not by bytes: every channel's ring and the time
+/// ring cover the same amount of stream time, which is what makes a shared time
+/// base meaningful. When no channel is decimated (the common case) the two rules
+/// coincide and every slice is the same size.
+struct Partition {
+  u64 time_capacity = 0;               ///< time-base slots retained
+  u64 time_stride = 1;                 ///< base ticks per time-base slot (reserved; 1)
+  std::vector<u64> stride;             ///< time slots per channel sample (>= 1)
+  std::vector<u64> value_capacity;     ///< samples retained per channel
+  double base_dt = 1.0;                ///< seconds per base tick
+  double span_s = 0.0;                 ///< stream seconds one buffer covers
+
+  u64 total_samples() const noexcept;
+  u64 total_bytes() const noexcept { return total_samples() * sizeof(f32); }
+  /// Seconds between two time-base slots (the sample interval of every channel).
+  double slot_dt() const noexcept { return base_dt * static_cast<double>(time_stride); }
+};
+
+/// Plans a partition for `channel_dt` cadences within `buffer_bytes`, targeting a
+/// span of `target_span_s` seconds. Throws std::runtime_error when the budget
+/// cannot hold even one sample per channel.
+Partition plan_partition(const std::vector<double>& channel_dt, double buffer_bytes);
+
+/// One of the two identical sample buffers: a shared time-base ring plus one
+/// value ring and one `ChannelBuffer` per channel.
+class BufferStore {
+ public:
+  BufferStore(const Partition& part, f64 span_s);
+
+  /// Re-bases every channel's x (see `ChannelBuffer::set_epoch`). Used to make the
+  /// axis read seconds from the trigger event.
+  void set_epoch(f64 epoch) noexcept;
+
+  plot::data::RingBuffer<f32>& time() noexcept { return *time_; }
+  const plot::data::RingBuffer<f32>& time() const noexcept { return *time_; }
+  plot::data::RingBuffer<f32>& values(std::size_t channel) { return *values_[channel]; }
+  ChannelBuffer& channel(std::size_t channel) { return *channels_[channel]; }
+  /// Shared handle to a channel view: the caller keeps the storage alive even if
+  /// the model rebuilds.
+  std::shared_ptr<ChannelBuffer> shared_channel(std::size_t channel) {
+    return channels_[channel];
+  }
+  const Partition& partition() const noexcept { return part_; }
+
+  /// Consumer: publishes every channel's new samples.
+  void acquire_all();
+
+ private:
+  Partition part_;
+  std::shared_ptr<plot::data::RingBuffer<f32>> time_;
+  std::vector<std::shared_ptr<plot::data::RingBuffer<f32>>> values_;
+  std::vector<std::shared_ptr<ChannelBuffer>> channels_;
+};
+
+/// Live connection and counter state, readable from the UI thread.
+struct StreamStats {
+  std::atomic<std::uint64_t> packets{0};
+  std::atomic<std::uint64_t> frames{0};
+  std::atomic<std::uint64_t> gaps{0};
+  std::atomic<std::uint64_t> reconnects{0};
+  std::atomic<bool> connected{false};
+  std::atomic<bool> have_config{false};
+};
+
+/// The application's data model: the stream description, the two sample buffers,
+/// the trigger configuration and the counters. Structural changes (a CONFIG
+/// update, an enable/disable, a calibration) rebuild the buffers, so all mutating
+/// access is serialised on one mutex; the acquisition thread takes it once per
+/// DATA frame.
+class ScopeModel {
+ public:
+  explicit ScopeModel(const Config& cfg);
+
+  const Config& config() const noexcept { return cfg_; }
+
+  // --- stream description ---------------------------------------------------
+  /// Takes a new CONFIG: rebuilds the signal and channel lists and the two
+  /// buffers. Clears the trigger's channel selection if the stream changed.
+  void set_signals(std::vector<SignalInfo> signals);
+  const std::vector<SignalInfo>& signals() const noexcept { return signals_; }
+  const std::vector<ChannelInfo>& channels() const noexcept { return channels_; }
+
+  bool signal_enabled(std::size_t signal) const;
+  /// True when the signal is the stream's time base, i.e. when some other signal
+  /// declares it via `time_signal_idx`. A signal used as a time base builds the x
+  /// axis and is not a plottable channel.
+  static bool is_time_signal(const std::vector<SignalInfo>& signals,
+                             std::size_t signal);
+  void set_signal_enabled(std::size_t signal, bool on);
+  void set_calibration(std::size_t signal, double gain, double offset);
+
+  std::size_t channel_count() const noexcept { return channels_.size(); }
+  const Partition& partition() const noexcept { return part_; }
+
+  /// The channel's sample interval (0 when the stream did not say).
+  double channel_dt(std::size_t channel) const;
+
+  // --- buffers --------------------------------------------------------------
+  /// The one sample store: the producer always writes it, and the plot draws from
+  /// it whenever it is not showing a frozen event. Always-filling is what
+  /// guarantees a full pre-trigger history on the *first* latch after the trigger
+  /// is armed.
+  BufferStore& live();
+
+  /// Builds the captured event from the slice of the live buffer covering
+  /// `[edge - pre_s, edge + post_s]` in stream seconds, and publishes it atomically.
+  /// The stamps are re-based so the edge sits at x = 0. The plot binds to this
+  /// immutable snapshot -- it is the "frozen buffer" -- while the live ring keeps
+  /// filling behind it.
+  ///
+  /// The cut is by time, not by a sample count: the window the trigger panel asks
+  /// for is in seconds and the time ring stores seconds, so any count in between
+  /// needs a cadence estimate -- which is exactly what used to size the capture
+  /// wrong.
+  void publish_event(double pre_s, double post_s, double edge);
+
+  /// The live buffer's absolute index range covering `[lo_s, hi_s]` in stream seconds,
+  /// clamped to what the time ring and *every* value ring still hold. One range for the
+  /// time ring and all the channels, which is what keeps a cut index-aligned by
+  /// construction; the bounds are compared in the ring's own `f32`, so a bound that
+  /// lands on a sample includes it whatever the magnitude of the stream time.
+  ///
+  /// Caller holds `mutex()` (the acquisition thread already does when it latches).
+  void live_window_locked(double lo_s, double hi_s, u64& first, u64& last);
+  /// The event on screen, or null before the first latch.
+  std::shared_ptr<const EventSnapshot> event() const noexcept {
+    return event_.load(std::memory_order_acquire);
+  }
+
+  /// Publishes the live buffer's new samples to its `ChannelBuffer`s.
+  void acquire_all();
+
+  // --- trigger --------------------------------------------------------------
+  /// The trigger configuration. Mutating it means holding `mutex()`: the producer
+  /// reads it once per frame (and writes `armed` itself when a single-shot latch
+  /// disarms), so an unguarded field write can be lost or read half-updated. The
+  /// panel's callbacks take the lock for the fields they touch.
+  TriggerConfig& trigger() noexcept { return trigger_; }
+  const TriggerConfig& trigger() const noexcept { return trigger_; }
+
+  /// Trigger mode on/off, as both the frame tick and the producer read it: the one
+  /// trigger field the tick needs and the only one written from the UI, so it has
+  /// an atomic mirror and a setter that keeps the copy under the lock in step.
+  bool trigger_enabled() const noexcept {
+    return trigger_enabled_.load(std::memory_order_relaxed);
+  }
+  void set_trigger_enabled(bool on);
+
+  /// Whether the engine is mid-capture (an edge was seen and the post-trigger
+  /// window is still filling). Purely informational: it drives the status line's
+  /// wording. The plot deliberately does *not* react to it -- in trigger mode the
+  /// picture changes only on a latch (SPECS: "data visualisation should not be
+  /// refreshed till next event").
+  bool trigger_pending() const noexcept {
+    return trigger_pending_.load(std::memory_order_relaxed);
+  }
+  void set_trigger_pending(bool on) noexcept {
+    trigger_pending_.store(on, std::memory_order_relaxed);
+  }
+
+  /// The x origin the plot uses: 0 for "seconds since the stream started", or minus
+  /// the trigger instant while in trigger mode, so the axis reads seconds from the
+  /// event. Applied to the live store's channels.
+  f64 display_epoch() const noexcept { return display_epoch_.load(std::memory_order_relaxed); }
+  void set_display_epoch(f64 e) noexcept;
+
+  // --- stream state ---------------------------------------------------------
+  StreamStats& stats() noexcept { return stats_; }
+  const StreamStats& stats() const noexcept { return stats_; }
+  /// Seconds since the epoch of the streamed time, or 0 before the first frame.
+  f64 epoch() const noexcept { return epoch_; }
+  void set_epoch_if_unset(f64 e) noexcept;
+
+  /// Bumped whenever the signal or channel lists change, so the UI knows to
+  /// rebuild the panels it derives from them.
+  unsigned generation() const noexcept { return generation_.load(std::memory_order_acquire); }
+
+  /// The length of the event the trigger latches, in seconds: the time window the
+  /// toolbar selects. The pre-trigger percentage is a share of *this*, not of the
+  /// whole ring, which is what makes the control mean something on a long buffer.
+  void set_event_span(double seconds) noexcept {
+    event_span_.store(seconds > 0.0 ? seconds : 1.0, std::memory_order_relaxed);
+  }
+  double event_span() const noexcept { return event_span_.load(std::memory_order_relaxed); }
+
+  /// Trigger state for the UI, published by the acquisition thread. Atomics
+  /// rather than fields of `TriggerConfig` because the producer writes the arm
+  /// state when a single-shot trigger disarms itself, and the frame tick reads it
+  /// without holding the model mutex.
+  std::atomic<bool>& trigger_armed() noexcept { return trigger_armed_; }
+  /// Incremented every time an event is latched, so the UI can tell "waiting for
+  /// an event" from "an event is on screen".
+  std::atomic<std::uint64_t>& trigger_latches() noexcept { return trigger_latches_; }
+  /// The stream time of the edge behind the event on screen, and whether there is
+  /// one. Written by the acquisition thread on a latch and cleared by the UI when
+  /// the event stops meaning anything (arming again, or leaving trigger mode).
+  std::atomic<double>& trigger_time() noexcept { return trigger_time_; }
+  std::atomic<bool>& trigger_time_valid() noexcept { return trigger_time_valid_; }
+
+  /// Serialises a structural change against the acquisition thread.
+  std::mutex& mutex() noexcept { return mutex_; }
+
+  /// Rebuilds buffers from the current channel list. Caller holds `mutex()`.
+  void rebuild_locked();
+
+ private:
+  void rebuild_channels();
+
+  Config cfg_;
+  std::vector<SignalInfo> signals_;
+  std::vector<ChannelInfo> channels_;
+  std::vector<bool> enabled_;
+
+  Partition part_;
+  std::unique_ptr<BufferStore> store_;
+  TriggerConfig trigger_{};
+  StreamStats stats_{};
+  f64 epoch_ = 0.0;
+  std::atomic<double> event_span_{1.0};
+  std::atomic<bool> trigger_pending_{false};
+  std::atomic<std::shared_ptr<const EventSnapshot>> event_;  ///< the event on screen
+  std::atomic<double> display_epoch_{0.0};
+  std::atomic<bool> trigger_armed_{false};
+  std::atomic<bool> trigger_enabled_{false};
+  std::atomic<std::uint64_t> trigger_latches_{0};
+  std::atomic<double> trigger_time_{0.0};
+  std::atomic<bool> trigger_time_valid_{false};
+  std::atomic<unsigned> generation_{0};
+  std::mutex mutex_;
+};
+
+}  // namespace udpscope

src/plot_host.cpp

@@ -0,0 +1,414 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "plot_host.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace udpscope {
+namespace {
+
+/// A small qualitative palette, one colour per *signal*. It is indexed by the signal
+/// rather than by the trace slot so that a signal plotted on several rows is the same
+/// colour in all of them: the signal list's chip is what ties a row of that list to a
+/// trace on screen, and a colour that depended on where the signal landed would name a
+/// different trace in every row.
+constexpr plot::u32 kPalette[] = {
+    0x4FA3FFu, 0xFF8A4Fu, 0x5FD08Au, 0xE86A9Cu, 0xC9A227u, 0x8F7BFFu, 0x4FD0D0u, 0xFF6B6Bu,
+};
+constexpr std::size_t kPaletteSize = sizeof(kPalette) / sizeof(kPalette[0]);
+
+/// The chip of a signal that is acquired but on no plot, and of one that is not even
+/// acquired. Mid grey: it has to read as "no trace" next to any palette entry.
+constexpr plot::u32 kUnplottedColor = 0x6E6E6Eu;
+
+constexpr plot::u32 kCursorAColor = 0xFFD24Fu;
+constexpr plot::u32 kCursorBColor = 0x7FE0FFu;
+constexpr plot::u32 kRulerColor = 0xB0B0B0u;
+constexpr plot::u32 kTriggerColor = 0xFF5B5Bu;
+
+constexpr double kParked = -1.0e12;  ///< hides an instrument without removing it
+
+/// The gap between two rows, in device pixels. The rows used to be separate widgets in
+/// a box, so there was a widget gap; a figure tiles its viewport, and without a gap two
+/// stacked frames read as one tall plot with a line through it.
+constexpr plot::f32 kRowGap = 6.0f;
+
+}  // namespace
+
+plot::Color RowSet::palette_color(int index) {
+  const std::size_t i = static_cast<std::size_t>(index < 0 ? 0 : index) % kPaletteSize;
+  return plot::Color::hex(kPalette[i]);
+}
+
+plot::Color RowSet::unplotted_color() { return plot::Color::hex(kUnplottedColor); }
+
+RowSet::RowSet() { rebuild_all(); }
+
+void RowSet::set_row_count(int rows) {
+  const int want = std::clamp(rows, 1, kMaxRows);
+  if (want == rows_) return;
+  rows_ = want;
+  // A `Figure`'s row count is fixed at construction, so a new count is a new figure.
+  rebuild_all();
+}
+
+void RowSet::install(Row& r, int /*row_index*/, plot::Plot& p) {
+  r.plot = &p;
+  r.axis_x = r.plot->add_x_axis(
+      {"time", {-1.0, 1.0}, true, plot::AxisPlace::Bottom, false, plot::TickFormat::Time});
+  r.axis_y = r.plot->add_y_axis(
+      {"value", {-1.0, 1.0}, true, plot::AxisPlace::Left, false, plot::TickFormat::Si});
+  for (int s = 0; s < kSlotsPerRow; ++s) {
+    const std::size_t i = static_cast<std::size_t>(s);
+    r.plot->add_trace(
+        {&r.slots[i], palette_color(r.color_index[i]), 1.2f, r.axis_x, r.axis_y, r.name[i]});
+  }
+  r.cursor_a = r.plot->add_cursor(0.0, plot::Color::hex(kCursorAColor));
+  r.cursor_b = r.plot->add_cursor(0.0, plot::Color::hex(kCursorBColor));
+  r.ruler = r.plot->add_h_ruler(0.0, plot::Color::hex(kRulerColor));
+  r.trigger_marker = r.plot->add_cursor(kParked, plot::Color::hex(kTriggerColor));
+  // A marker, not an instrument: it must sit exactly on the edge's time, so its
+  // snap is Free and the controller never rounds it onto a sample.
+  r.plot->set_cursor_snap(r.trigger_marker, plot::SnapMode::Free);
+  // No `set_x_follow(Live)`: the link group owns the window *and* the follow state, and
+  // `Figure::link_x()` refuses a member whose x axis still follows on its own.
+}
+
+void RowSet::rebuild_all() {
+  figure_ = std::make_unique<plot::Figure>(static_cast<plot::u32>(rows_));
+  figure_->set_row_gap(kRowGap);
+  x_group_ = figure_->add_x_link();
+  for (int i = 0; i < kMaxRows; ++i) {
+    Row& r = row(i);
+    row_dirty_[static_cast<std::size_t>(i)] = false;
+    if (i >= rows_) {
+      r.plot = nullptr;  // not a row of this figure: nothing to plot into
+      continue;
+    }
+    install(r, i, figure_->plot(static_cast<plot::u32>(i)));
+    place_cursors(r);
+    if (trigger_marker_on_) {
+      r.plot->set_cursor_x(r.trigger_marker, trigger_marker_x_, plot::CursorPlacement::Free);
+    }
+    figure_->link_x(static_cast<plot::u32>(i), x_group_);
+  }
+  if (y_gutter_px_ > 0.0) apply_y_gutter();
+  // A new figure starts with no window at all, so the one the rows were showing has to
+  // be restated -- as the pin it was, if an event is on screen: assigning a trace or
+  // changing the row count while a capture is displayed must not throw the view back
+  // onto the live edge, which in trigger mode nothing would move it off again until the
+  // next latch.
+  if (pinned_) {
+    pin_event_window(pinned_pre_, pinned_post_);
+  } else {
+    set_time_window(window_s_);
+  }
+}
+
+bool RowSet::rebuild_if_dirty() {
+  bool any = false;
+  for (int i = 0; i < kMaxRows; ++i) {
+    if (row_dirty_[static_cast<std::size_t>(i)]) any = true;
+  }
+  if (!any) return false;
+  // One row's legend text changed, which `Plot` cannot express, so its traces have to
+  // be created again -- and a row belongs to a figure, so the figure is rebuilt. That
+  // costs the plots' CPU state and nothing else: the host keeps its GL context and is
+  // handed the new figure.
+  rebuild_all();
+  return true;
+}
+
+void RowSet::assign(int row_index, int slot, std::string signal_name,
+                    std::string display_name, int color_index) {
+  if (row_index < 0 || row_index >= kMaxRows || slot < 0 || slot >= kSlotsPerRow) return;
+  Row& r = row(row_index);
+  const std::size_t s = static_cast<std::size_t>(slot);
+  r.signal_name[s] = std::move(signal_name);
+  r.channel[s] = -1;  // re-resolved by the next bind()
+  r.name[s] = std::move(display_name);
+  r.color_index[s] = color_index;
+  row_dirty_[static_cast<std::size_t>(row_index)] = true;
+}
+
+bool RowSet::slot_bound(int row_index, int slot) const {
+  if (row_index < 0 || row_index >= kMaxRows || slot < 0 || slot >= kSlotsPerRow) return false;
+  return !row(row_index).signal_name[static_cast<std::size_t>(slot)].empty();
+}
+
+int RowSet::channel_of(int row_index, int slot) const {
+  if (row_index < 0 || row_index >= kMaxRows || slot < 0 || slot >= kSlotsPerRow) return -1;
+  return row(row_index).channel[static_cast<std::size_t>(slot)];
+}
+
+void RowSet::bind(ScopeModel& model) {
+  const std::vector<SignalInfo>& signals = model.signals();
+  const std::vector<ChannelInfo>& channels = model.channels();
+  for (int i = 0; i < kMaxRows; ++i) {
+    Row& r = row(i);
+    for (int s = 0; s < kSlotsPerRow; ++s) {
+      const std::size_t si = static_cast<std::size_t>(s);
+      if (r.signal_name[si].empty()) {
+        r.channel[si] = -1;
+        r.slots[si].bind(nullptr);
+        continue;
+      }
+      // Resolve the stable identity every frame: the channel list is rebuilt (and
+      // renumbered) whenever a signal is enabled, disabled or re-described, and a
+      // stored index would then point at a different signal's channel.
+      int signal_index = -1;
+      for (std::size_t k = 0; k < signals.size(); ++k) {
+        if (signals[k].name == r.signal_name[si]) {
+          signal_index = static_cast<int>(k);
+          break;
+        }
+      }
+      int channel = -1;
+      if (signal_index >= 0) {
+        for (std::size_t c = 0; c < channels.size(); ++c) {
+          if (static_cast<int>(channels[c].signal) == signal_index) {
+            channel = static_cast<int>(c);
+            break;
+          }
+        }
+      }
+      r.channel[si] = channel;
+      if (channel < 0) {
+        // Its signal is present but not acquired: keep the identity (so enabling it
+        // brings the trace back) and plot nothing meanwhile.
+        r.slots[si].bind(nullptr);
+        continue;
+      }
+      // In trigger mode the trace shows the captured event and nothing else: the
+      // last one latched, or nothing at all before the first. Never the live ring,
+      // not even while the post window is filling -- a frozen picture that only
+      // changes on an event is the whole point of trigger mode, and binding the
+      // live ring mid-capture made the plot scroll for most of every event cycle.
+      const std::size_t ci = static_cast<std::size_t>(channel);
+      if (model.trigger_enabled()) {
+        if (auto snap = model.event()) {
+          r.slots[si].bind_event(std::move(snap), ci);
+        } else {
+          r.slots[si].bind(nullptr);  // armed, waiting for the first event: blank
+        }
+      } else {
+        r.slots[si].bind(model.live().shared_channel(ci));
+      }
+    }
+  }
+}
+
+bool RowSet::live_edge(double& newest) const {
+  bool any = false;
+  for (int i = 0; i < rows_; ++i) {
+    const Row& r = row(i);
+    if (!r.plot) continue;
+    double edge = 0.0;
+    // Follow-independent: it reads the row's streaming traces, so a row whose own axis
+    // is `Off` (which every member of a link group is) still reports its edge.
+    if (!r.plot->x_live_edge(r.axis_x, edge)) continue;
+    newest = any ? std::max(newest, edge) : edge;
+    any = true;
+  }
+  return any;
+}
+
+void RowSet::set_time_window(double seconds) {
+  window_s_ = std::max(0.05, seconds);
+  pinned_ = false;
+  if (!figure_) return;
+  figure_->set_x_link_follow(x_group_, plot::XFollow::Live);
+  double newest = 0.0;
+  if (live_edge(newest)) {
+    // Under a following group the range states the span and -- through its maximum --
+    // where the window sits behind the live edge, so a maximum *at* the edge is what
+    // makes the offset zero and parks the window on the newest sample. Asking for
+    // `{0, window}` here instead would state an offset of a whole epoch.
+    figure_->set_x_link_range(x_group_, {newest - window_s_, newest});
+  } else {
+    figure_->set_x_link_range(x_group_, {0.0, window_s_});
+  }
+}
+
+void RowSet::set_y_auto(int row_index, bool on) {
+  Row& r = row(row_index);
+  if (!r.plot) return;
+  r.plot->set_y_auto_scale(r.axis_y, on);
+  if (on) r.plot->auto_fit_y(r.axis_y);
+}
+
+void RowSet::set_y_range(int row_index, double lo, double hi) {
+  Row& r = row(row_index);
+  if (!r.plot) return;
+  const double a = std::min(lo, hi);
+  const double b = std::max(lo, hi);
+  if (!std::isfinite(a) || !std::isfinite(b) || !(b > a)) return;
+  r.plot->set_y_range(r.axis_y, {a, b});
+}
+
+void RowSet::place_cursors(Row& r) {
+  if (!r.plot) return;
+  const bool show = r.cursors_visible;
+  const double a = show ? r.cursor_a_x : kParked;
+  const double b = show ? r.cursor_b_x : kParked;
+  const double h = show ? r.ruler_y : kParked;
+  r.plot->set_cursor_x(r.cursor_a, a);
+  r.plot->set_cursor_x(r.cursor_b, b);
+  r.plot->set_cursor_y(r.ruler, h);
+}
+
+void RowSet::clamp_to_data() {
+  if (!figure_) return;
+  // The rows share one window, so they share one bound: the union of what they hold.
+  // Taking each row's own would let a row whose signal was enabled a moment ago clamp
+  // the window every row is looking at.
+  plot::Range data{};
+  bool have = false;
+  for (int i = 0; i < rows_; ++i) {
+    Row& r = row(i);
+    if (!r.plot) continue;
+    const plot::data::Series* series = nullptr;
+    for (int s = 0; s < kSlotsPerRow && series == nullptr; ++s) {
+      if (!r.signal_name[static_cast<std::size_t>(s)].empty()) {
+        series = r.slots[static_cast<std::size_t>(s)].bound();
+      }
+    }
+    if (series == nullptr || series->size() < 2) continue;
+    const plot::Range b = series->x_bounds();
+    if (!std::isfinite(b.min) || !std::isfinite(b.max) || !(b.max > b.min)) continue;
+    data = have ? plot::Range{std::min(data.min, b.min), std::max(data.max, b.max)} : b;
+    have = true;
+  }
+  if (!have) return;
+  const double retained = data.max - data.min;
+  const double span = figure_->x_link_range(x_group_).span();
+  if (!(span > 0.0) || !std::isfinite(span)) return;
+  // The *requested* window is intent, and a buffer that has not filled it yet must not
+  // be allowed to redefine it. This runs every frame and cannot tell "the user zoomed
+  // out past the data" from "the ring has only just started filling", and the first
+  // frames after a signal is enabled hold a couple of hundred samples: clamping to
+  // those shrank a requested 2 s window to ~0.02 s, and nothing here ever grows a span
+  // back, so the view stayed pinned to the newest 20 ms of a 6.5 s buffer for the rest
+  // of the run. That is the loudest form of the "live trace is clipped, only the most
+  // recent part is visible, data is there because the crosshair reads it" defect -- the
+  // data was never clipped at all, the window was. Clamping against `max(retained,
+  // window_s_)` leaves a partly filled window empty on its left, which is what a scope
+  // that just started should look like.
+  //
+  // The span only. A pan is the group's `offset` behind its live edge and the group
+  // clamps it against what its members retain on every layout, so there is nothing
+  // here to do about `view.min < data.min` -- and doing it anyway would state a maximum
+  // away from the live edge, i.e. ask the group to scroll back.
+  const double limit = std::max(retained, window_s_);
+  if (span > limit) figure_->set_x_link_range(x_group_, {data.max - limit, data.max});
+}
+
+void RowSet::pin_event_window(double pre_s, double post_s) {
+  window_s_ = std::max(1.0e-3, pre_s + post_s);
+  pinned_ = true;
+  pinned_pre_ = pre_s;
+  pinned_post_ = post_s;
+  if (!figure_) return;
+  // The captured event sits at [-pre, +post] with the edge at 0, and the bound series is
+  // the immutable snapshot. The group must stop following first: Live re-derives the
+  // window from a live edge, and with nothing streaming it would keep placing the window
+  // from the last stale edge instead of the event.
+  figure_->set_x_link_follow(x_group_, plot::XFollow::Off);
+  figure_->set_x_link_range(x_group_, {-pre_s, post_s});
+}
+
+void RowSet::fit_all() {
+  for (int i = 0; i < rows_; ++i) {
+    Row& r = row(i);
+    if (r.plot) r.plot->auto_fit_y(r.axis_y);
+  }
+  Row& first = row(0);
+  if (!first.plot || !figure_) return;
+  // Row 0 fits its own x to the data it holds; that span becomes the shared window, and
+  // stating it through the group is what puts every row on it.
+  first.plot->auto_fit_x();
+  const plot::Range fitted = first.plot->x_range(first.axis_x);
+  const double span = fitted.span();
+  if (!std::isfinite(span) || !(span > 0.0)) return;
+  if (pinned_) {
+    // Fitting a captured event: the window is the snapshot's own `[-pre, +post]` span,
+    // and `set_time_window()` would re-arm the follow and re-frame on a live edge that
+    // trigger mode has nothing bound to.
+    window_s_ = span;
+    figure_->set_x_link_range(x_group_, fitted);
+  } else {
+    set_time_window(span);
+  }
+}
+
+void RowSet::note_y_gutter(double need_px) {
+  double want = std::min(need_px + 6.0, 200.0);
+  // Reserve room for the widest label the formatter can produce, once, with the
+  // font the labels are actually drawn in (the embedded font is monospaced, so a
+  // character count is an exact width).
+  if (!y_gutter_reserved_) {
+    for (int i = 0; i < rows_; ++i) {
+      Row& r = row(i);
+      if (!r.plot) continue;
+      const plot::render::TextBackend* text = r.plot->text_backend();
+      if (text == nullptr) continue;
+      const plot::render::Style& style = r.plot->style();
+      const double advance = double(text->measure("0123456789")) / 10.0;
+      const double pad = double(style.device(style.grid_label_pad));
+      // "-1.23e-45" is the longest label `format_si()`'s fallback can print.
+      want = std::max(want, 9.0 * advance + 2.0 * pad + 2.0);
+      y_gutter_reserved_ = true;
+      break;
+    }
+  }
+  if (want > y_gutter_px_) y_gutter_px_ = want;
+}
+
+void RowSet::apply_y_gutter() {
+  if (!figure_ || !(y_gutter_px_ > 0.0)) return;
+  figure_->set_min_y_gutter(static_cast<f32>(y_gutter_px_));
+}
+
+void RowSet::set_trigger_marker(double x, bool visible) {
+  trigger_marker_on_ = visible;
+  trigger_marker_x_ = x;
+  const double want = visible ? x : kParked;
+  for (int i = 0; i < rows_; ++i) {
+    Row& r = row(i);
+    if (!r.plot) continue;
+    // Re-assert against what the plot *holds*, not against a cached value: the
+    // marker is a cursor, so the input layer will happily drag it, and a marker the
+    // user can move off the trigger instant is not marking anything. Comparing
+    // with the plot also keeps the steady state write-free (a write invalidates the
+    // plot's cached measurements).
+    if (r.plot->cursor(r.trigger_marker).x == want) continue;
+    r.plot->set_cursor_x(r.trigger_marker, want, plot::CursorPlacement::Free);
+  }
+}
+
+void RowSet::set_cursors_visible(bool on) {
+  for (int i = 0; i < kMaxRows; ++i) {
+    Row& r = row(i);
+    r.cursors_visible = on;
+    place_cursors(r);
+  }
+}
+
+void RowSet::reset_cursors() {
+  for (int i = 0; i < kMaxRows; ++i) {
+    Row& r = row(i);
+    if (!r.plot) continue;
+    const plot::Range xr = r.plot->x_range(r.axis_x);
+    const double span = xr.span() > 0.0 ? xr.span() : window_s_;
+    r.cursor_a_x = xr.min + 0.25 * span;
+    r.cursor_b_x = xr.min + 0.75 * span;
+    r.ruler_y = r.plot->y_range(r.axis_y).min +
+                0.5 * (r.plot->y_range(r.axis_y).span() > 0.0 ? r.plot->y_range(r.axis_y).span()
+                                                              : 1.0);
+    place_cursors(r);
+  }
+}
+
+}  // namespace udpscope

src/plot_host.hpp

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include "model.hpp"
+
+#include <plot/plot/figure.hpp>
+#include <plot/plot/plot.hpp>
+
+#include <array>
+#include <memory>
+#include <string>
+
+namespace udpscope {
+
+/// The stacked plots (spec item 4).
+///
+/// The rows are the rows of **one `plot::Figure`**, rendered by one
+/// `plot::gtk4::PlotArea` in figure mode. The figure owns everything the rows have
+/// to agree on, which is why it is one figure and not N plots:
+///
+/// - the x window, through a single x link group every row joins. A gesture on any
+///   row changes that row's range, the group adopts it and pushes it to the others
+///   (`Figure::sync_x_links()`, run from `layout()`), so there is no "which row
+///   acted" to work out and nothing to propagate by hand;
+/// - the live follow, which is the *group's* (`set_x_link_follow`). A member's own
+///   axis must be `XFollow::Off` -- `Figure::link_x()` refuses a `Live` member --
+///   because a following axis would reinterpret the pushed range as its own span and
+///   offset behind its own edge, which is per-row drift by construction;
+/// - the left gutter, so a vertical feature lands in the same pixel column in every
+///   row (`Figure::layout()` lays each row out twice and imposes the maximum);
+/// - the crosshair, placed on every row at one x by `PlotArea`'s figure-mode sync.
+///
+/// A row's `Plot` cannot drop a trace, so every row carries a fixed set of trace
+/// slots created up front; assigning a signal to a slot is a rebind of that slot's
+/// `SlotSeries`, and only a *name* change -- which `Plot` cannot express -- forces a
+/// rebuild (see `row_dirty()`). A rebuild is of the whole figure: `Figure`'s row
+/// count is fixed at construction, so there is one path for "a row's traces changed"
+/// and "the row count changed", and it costs no GL state -- the area keeps its
+/// context and is simply handed the new figure.
+class RowSet {
+ public:
+  static constexpr int kMaxRows = 4;
+  static constexpr int kSlotsPerRow = 4;
+
+  RowSet();
+
+  struct Row {
+    /// The figure's row, borrowed. Null for a row beyond `row_count()`, which is how
+    /// every loop here and in the UI stays inside the rows that exist. Invalidated by
+    /// `rebuild_all()`, which builds a new figure.
+    plot::Plot* plot = nullptr;
+    std::array<SlotSeries, kSlotsPerRow> slots;
+    /// Model channel per trace slot. Must start at -1: `std::array<Row, N>{}`
+    /// zero-initialises a `Row`, and a zero here reads as "slot 0 already holds
+    /// channel 0", which makes every drop look like the row is full.
+    /// What the slot plots, as a *stable identity*: a channel index is positional,
+    /// and enabling/disabling a signal or a new CONFIG renumbers the channel list,
+    /// so an index would silently start plotting a different signal. Empty name =
+    /// free slot.
+    std::array<std::string, kSlotsPerRow> signal_name;
+    /// The channel index `signal_name`/`element` resolved to, filled by `bind()`.
+    std::array<int, kSlotsPerRow> channel = {-1, -1, -1, -1};
+    /// The trace's legend name (the channel's display name), which is what the
+    /// plot was built with.
+    std::array<std::string, kSlotsPerRow> name;
+    /// The palette entry the slot's trace is drawn in. A *signal's* index, not the
+    /// slot's: a signal dropped on two rows has to be the same colour in both, or the
+    /// signal list's colour chip cannot name a trace. Supplied by the caller, because
+    /// only it knows the signal list this indexes into. A trace's colour is fixed at
+    /// `add_trace()`, which is why this is stored rather than resolved per frame --
+    /// changing it needs a rebuild, and `assign()` already forces one.
+    std::array<int, kSlotsPerRow> color_index = {0, 1, 2, 3};
+    plot::u32 axis_x = 0;
+    plot::u32 axis_y = 0;
+    plot::u32 cursor_a = 0;
+    plot::u32 cursor_b = 0;
+    plot::u32 ruler = 0;
+    /// The vertical line marking the trigger instant, drawn whenever an event is
+    /// on screen (and parked outside the axis otherwise). Not the user's cursor:
+    /// it keeps its position whatever the cursor toggle says.
+    plot::u32 trigger_marker = 0;
+    /// Off by default: the cursors are switched on from the toolbar, and a rebuild
+    /// (any drop, any row-count change) must not switch them back off.
+    bool cursors_visible = false;
+    double cursor_a_x = 0.0;
+    double cursor_b_x = 0.0;
+    double ruler_y = 0.0;
+  };
+
+  int row_count() const noexcept { return rows_; }
+  /// Shows `rows` rows. A changed count rebuilds the figure, since a `Figure`'s row
+  /// count is fixed at construction.
+  void set_row_count(int rows);
+  Row& row(int i) { return storage_[static_cast<std::size_t>(i)]; }
+  const Row& row(int i) const { return storage_[static_cast<std::size_t>(i)]; }
+
+  /// The figure the rows live in. The host must be handed this again after every
+  /// `rebuild_all()`.
+  plot::Figure& figure() noexcept { return *figure_; }
+
+  /// Builds a new figure: one `Plot` per visible row with its axes, cursors and fixed
+  /// trace slots, all joined by one x link group.
+  void rebuild_all();
+  /// Rebuilds if any row's traces changed, and reports whether it did -- in which case
+  /// the caller re-points its host at `figure()`.
+  bool rebuild_if_dirty();
+  bool row_dirty(int i) const { return row_dirty_[static_cast<std::size_t>(i)]; }
+
+  /// Binds a row's trace slot to a signal element (`signal_name` empty frees it).
+  /// `color_index` is the signal's palette entry (see `Row::color_index`).
+  void assign(int row, int slot, std::string signal_name, std::string display_name,
+              int color_index);
+  /// Whether a slot plots anything.
+  bool slot_bound(int row, int slot) const;
+  /// The channel index a row/slot holds, or -1.
+  int channel_of(int row, int slot) const;
+
+  /// Rebinds every slot to what it should show this frame: the model's live buffer,
+  /// or -- in trigger mode -- the captured event. Called every frame, because the
+  /// channel list is renumbered by any structural change.
+  void bind(ScopeModel& model);
+  /// Publishes the live buffer's new samples.
+  void acquire(ScopeModel& model) { model.acquire_all(); }
+
+  /// Frames the newest `seconds` of the stream: the link group follows the live edge,
+  /// with its window ending on that edge (which is what resets any pan the user had).
+  void set_time_window(double seconds);
+  double time_window() const noexcept { return window_s_; }
+
+  void set_y_auto(int row, bool on);
+  void set_y_range(int row, double lo, double hi);
+
+  void set_cursors_visible(bool on);
+  void reset_cursors();
+
+  /// Places the trigger marker at stream time `x` (seconds since the epoch), or
+  /// parks it when there is no event on screen.
+  void set_trigger_marker(double x, bool visible);
+
+  /// Keeps the shared x window inside the data the rings actually hold: zooming out
+  /// stops at the whole retained span. A time window is a view of the acquisition, so
+  /// there is nothing to see outside it -- zooming into empty time only loses the data
+  /// off the edge of the plot. Only the *span*: a following group clamps its own pan
+  /// against what its members retain (`Figure::place_live_window()`), while a wheel
+  /// notch multiplies the span and nothing in the library bounds that.
+  void clamp_to_data();
+
+  /// Pins the shared x window to the captured event: `[-pre, +post]` with the edge at
+  /// 0, so nothing outside the pre+post window is visible.
+  void pin_event_window(double pre_s, double post_s);
+
+  /// Fits every row's y axis to the data it holds, and re-frames the shared x window
+  /// on what row 0 retains (the same thing the plot's own `f` key does). The window
+  /// the toolbar reports becomes the fitted span, so the dropdown can say what is
+  /// actually on screen.
+  void fit_all();
+
+  /// Reports the left gutter the rows currently need, and reserves at least the width
+  /// of the widest *plausible* y label.
+  ///
+  /// The gutter is measured from the y tick labels, and `TickFormat::Si` makes their
+  /// width change as the auto-fitted range moves (`1.5` becomes `15`, `150`, `1.5k`),
+  /// so a gutter that follows them drags the whole axes -- and with it the x axis --
+  /// left and right by a few pixels every frame. Since `set_min_y_gutter()` is a
+  /// floor and the library still takes the larger of the two, a floor smaller than
+  /// the labels cannot stop that; the reservation therefore covers the widest label
+  /// `format_si()` can produce (three significant digits, a sign and a prefix, or the
+  /// `%.3g` fallback) plus the label padding, measured once with the plot's own font.
+  /// Both reservations only ever grow, so the gutter is constant in practice.
+  void note_y_gutter(double need_px);
+
+  /// Applies the stable gutter as the figure's floor. Call once per frame, before the
+  /// frame is drawn.
+  ///
+  /// It has to be the *figure's* floor and not each row's: `Figure::layout()` clears
+  /// every row's `set_min_y_gutter()` to measure what its own labels need, so a floor
+  /// written onto the rows survives exactly until the next layout.
+  void apply_y_gutter();
+
+  /// The palette entry `index`, wrapped. Keyed by the *signal*, so that the colour a
+  /// trace is drawn in is the colour the signal list's chip shows, on every row the
+  /// signal appears in.
+  static plot::Color palette_color(int index);
+  /// The colour of a signal that is on no plot, which the signal list shows instead of
+  /// leaving its chip blank -- a blank chip is a narrower cell than a filled one, so the
+  /// names beside it shifted sideways as signals were placed.
+  static plot::Color unplotted_color();
+
+ private:
+  void install(Row& r, int row_index, plot::Plot& p);
+  void place_cursors(Row& r);
+  /// The newest x any row's live traces hold, which is what the group follows.
+  bool live_edge(double& newest) const;
+
+  std::unique_ptr<plot::Figure> figure_;
+  /// The one x link group every visible row belongs to. Groups are numbered from 1.
+  plot::u32 x_group_ = 0;
+  int rows_ = 1;
+  double window_s_ = 2.0;
+  double trigger_marker_x_ = 0.0;
+  bool trigger_marker_on_ = false;
+  /// The event window currently pinned, so a rebuild can restate it instead of
+  /// re-framing on the live edge.
+  double pinned_pre_ = 0.0;
+  double pinned_post_ = 0.0;
+  bool pinned_ = false;
+  double y_gutter_px_ = 0.0;
+  bool y_gutter_reserved_ = false;
+  std::array<Row, static_cast<std::size_t>(kMaxRows)> storage_{};
+  std::array<bool, static_cast<std::size_t>(kMaxRows)> row_dirty_{};
+};
+
+}  // namespace udpscope

src/trigger.cpp

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#include "trigger.hpp"
+
+#include <algorithm>
+
+namespace udpscope {
+
+double TriggerConfig::post_span_s(double buffer_span_s) const {
+  const double pre = std::clamp(pretrigger_pct, 0.0, 100.0) / 100.0;
+  return buffer_span_s * (1.0 - pre);
+}
+
+void TriggerEngine::configure(const TriggerConfig& cfg, double post_seconds,
+                              double pre_seconds, double oldest_s) {
+  const bool channel_changed = cfg.channel != cfg_.channel;
+  cfg_ = cfg;
+  post_seconds_ = post_seconds > 0.0 ? post_seconds : 0.0;
+  pre_seconds_ = pre_seconds > 0.0 ? pre_seconds : 0.0;
+  oldest_s_ = oldest_s;
+  if (channel_changed) {
+    have_prev_ = false;
+    pending_ = false;
+    post_accum_count_ = 0;
+  }
+}
+
+void TriggerEngine::arm(double now_s) noexcept {
+  armed_ = true;
+  pending_ = false;
+  post_accum_count_ = 0.0;
+  holdoff_until_s_ = now_s;
+  have_prev_ = false;
+}
+
+bool TriggerEngine::process(double value, double now_s) noexcept {
+  if (!cfg_.enabled || !armed_ || cfg_.channel < 0) return false;
+
+  // Hold-off: settled, waiting for the next edge.
+  if (!pending_ && now_s < holdoff_until_s_) {
+    prev_ = value;
+    have_prev_ = true;
+    last_t_s_ = now_s;
+    return false;
+  }
+
+  if (!have_prev_) {
+    prev_ = value;
+    have_prev_ = true;
+    last_t_s_ = now_s;
+    return false;
+  }
+
+  last_t_s_ = now_s;
+
+  if (pending_) {
+    // Accumulate the post-trigger window; latch once the stream clock has advanced
+    // past it. Time, not a sample count: `now_s` is the same clock the x axis reads,
+    // so the capture covers exactly the requested span whatever the cadence is.
+    ++post_accum_count_;
+    prev_ = value;
+    if (now_s - pending_start_s_ >= post_seconds_) {
+      pending_ = false;
+      post_accum_count_ = 0;
+      if (cfg_.mode == TriggerMode::Single) {
+        armed_ = false;
+      } else {
+        holdoff_until_s_ = now_s + std::max(0.0, cfg_.holdoff_s);
+      }
+      return true;
+    }
+    return false;
+  }
+
+  // Edge detection against the level.
+  const bool crossed_up = prev_ < cfg_.level && value >= cfg_.level;
+  const bool crossed_down = prev_ > cfg_.level && value <= cfg_.level;
+  const bool fired = (cfg_.edge == TriggerEdge::Rising && crossed_up) ||
+                     (cfg_.edge == TriggerEdge::Falling && crossed_down) ||
+                     (cfg_.edge == TriggerEdge::Both && (crossed_up || crossed_down));
+  prev_ = value;
+  if (!fired) return false;
+
+  // The pre-trigger window has to already be behind this edge, or the capture opens
+  // on a half-filled pre window and the event is short on its left side -- the plot
+  // then shows a window that is correctly sized but only partly drawn. The buffer
+  // fills whether or not the trigger is armed, so this normally passes on the first
+  // edge; it only bites just after a rebuild (a CONFIG, or enabling the signal),
+  // when the history genuinely is not there yet.
+  if (now_s - oldest_s_ < pre_seconds_) return false;
+
+  // The edge's own time, which is what a trigger marker marks: the latch itself
+  // may happen a post-window later.
+  last_trigger_s_ = now_s;
+
+  // The edge always opens a capture; there is no "latch on the edge itself" case.
+  // A zero-length post window latches on the very next sample, which is the least a
+  // capture can hold, and every longer window is just more samples -- no conversion
+  // from seconds to a sample count, so no conversion to get wrong.
+  pending_ = true;
+  pending_start_s_ = now_s;
+  post_accum_count_ = 0;
+  return false;
+}
+
+}  // namespace udpscope

src/trigger.hpp

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include <cstdint>
+
+namespace udpscope {
+
+/// Which way the trigger signal crosses the level.
+enum class TriggerEdge { Rising, Falling, Both };
+
+/// How an armed trigger re-arms after it fired.
+enum class TriggerMode { Normal, Single };
+
+/// The trigger panel's configuration (spec item 2.2).
+///
+/// The trigger names a *signal* (an index into `ScopeModel::signals()`), not a
+/// channel: the panel lists every signal the stream describes, whether or not it
+/// is being acquired, and picking one is what arms the trigger on it. The
+/// acquisition resolves the signal to the channel carrying it.
+struct TriggerConfig {
+  bool enabled = false;          ///< trigger mode on/off (toolbar).
+  bool armed = false;            ///< arm/disarm button.
+  int channel = -1;              ///< index into ScopeModel::channels(), -1 = none.
+  double level = 0.0;
+  TriggerEdge edge = TriggerEdge::Rising;
+  double pretrigger_pct = 50.0;  ///< share of the buffer shown before the event.
+  double holdoff_s = 0.010;      ///< default from the spec.
+  TriggerMode mode = TriggerMode::Normal;
+
+  /// Seconds of post-trigger data to collect before latching the event, given
+  /// the buffer's span.
+  double post_span_s(double buffer_span_s) const;
+};
+
+/// The producer-side trigger state machine. Fed one sample at a time in stream
+/// order; it says when the event buffer should be latched.
+class TriggerEngine {
+ public:
+  /// Configures the channel and the post-trigger window. Resets the state when the
+  /// channel changes.
+  ///
+  /// `post_seconds` is the post-trigger window in **stream seconds**, the same clock
+  /// `process()` is fed and the same clock the x axis reads, so the capture covers
+  /// exactly that much axis by construction.
+  ///
+  /// It used to be a count of samples, converted from seconds by a measured estimate
+  /// of the channel's cadence. That estimate is what made the window wrong: when it
+  /// collapsed (any stream whose time signal advances in large steps drove it to the
+  /// 1 S/s floor) the count came out as 1, the engine latched on the edge sample
+  /// itself, and the event had no post-trigger data at all. Seconds need no estimate.
+  ///
+  /// `pre_seconds` is the pre-trigger window, and `oldest_s` the stream time of the
+  /// oldest sample the buffer still holds. Together they gate the edge: a capture is
+  /// only allowed once the history reaches back a full `pre_seconds` before it, so an
+  /// event cannot latch onto a half-filled pre window. `oldest_s` has to be the real
+  /// buffer's, not a timer since arming -- the ring keeps filling with the trigger
+  /// off, so the history is usually already there and waiting would be wrong.
+  void configure(const TriggerConfig& cfg, double post_seconds, double pre_seconds,
+                 double oldest_s);
+  /// Disarms without forgetting the configuration.
+  void disarm() noexcept { armed_ = false; pending_ = false; }
+  void arm(double now_s) noexcept;
+
+  /// Feeds one sample of the trigger channel. `now_s` is the sample's timestamp
+  /// in stream seconds. Returns true when the event has just been latched.
+  bool process(double value, double now_s) noexcept;
+
+  bool pending() const noexcept { return pending_; }
+  bool armed() const noexcept { return armed_; }
+
+  /// Diagnostics for the capture state machine: how many samples have landed in
+  /// the post-trigger window, the window it is filling (in stream seconds), how
+  /// much of that has elapsed, and the last value fed.
+  std::uint64_t post_accum() const noexcept { return post_accum_count_; }
+  double post_seconds() const noexcept { return post_seconds_; }
+  double post_elapsed() const noexcept {
+    return pending_ ? last_t_s_ - pending_start_s_ : 0.0;
+  }
+  /// How much history the buffer holds behind the newest sample, against the
+  /// pre-trigger window an edge needs before it may open a capture.
+  double history() const noexcept { return last_t_s_ - oldest_s_; }
+  double pre_seconds() const noexcept { return pre_seconds_; }
+  double last_value() const noexcept { return prev_; }
+  bool have_last() const noexcept { return have_prev_; }
+  double last_t() const noexcept { return last_t_s_; }
+  double holdoff_until() const noexcept { return holdoff_until_s_; }
+
+  /// Stream time of the edge that armed the event now on screen. Valid once
+  /// `process()` has fired; the view is centred on this instant (pre-trigger share
+  /// before it, post-trigger share after), so it is the x a trigger marker belongs
+  /// at. Unchanged while a later event has not fired yet.
+  double last_trigger_time() const noexcept { return last_trigger_s_; }
+
+ private:
+  TriggerConfig cfg_{};
+  bool armed_ = false;
+  bool have_prev_ = false;
+  double prev_ = 0.0;
+  bool pending_ = false;      ///< an edge was seen; collecting the post window
+  double pending_start_s_ = 0.0;
+  double holdoff_until_s_ = 0.0;
+  std::uint64_t post_accum_count_ = 0;
+  double post_seconds_ = 0.0;  ///< post-trigger window, in stream seconds.
+  double pre_seconds_ = 0.0;   ///< pre-trigger window an edge needs behind it.
+  double oldest_s_ = 0.0;      ///< stream time of the oldest sample still buffered.
+  double last_t_s_ = 0.0;
+  double last_trigger_s_ = 0.0;
+};
+
+}  // namespace udpscope

src/ui.hpp

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+namespace udpscope {
+
+struct Config;
+class ScopeModel;
+class Acquisition;
+class RowSet;
+
+/// Runs the GTK application. Never returns while the window is open; returns the
+/// `g_application_run()` result once it closes.
+int run_ui(int argc, char** argv, ScopeModel& model, Acquisition& acq, RowSet& rows);
+
+}  // namespace udpscope

tools/mock_udpstreamer.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2026 Martino Ferrari
+"""A minimal UDPStreamer (UDPS) producer, for exercising udpscope without MARTe2.
+
+Unicast only: binds `--port`, waits for a CONNECT datagram, then streams CONFIG
+once and DATA packets to whoever connected. Publish mode is Accumulate, so each
+packet carries `--batch` consecutive samples per (scalar) signal -- the shape the
+viewer's per-sample path expects.
+
+Signals: `time` (the stream's own clock, seconds), `sine`, `square`, `ramp`.
+Everything is float64 and unquantised.
+
+    ./tools/mock_udpstreamer.py --port 8000 --rate 10000 --batch 100
+"""
+
+import argparse
+import math
+import socket
+import struct
+import time
+
+MAGIC = 0x53504455
+PKT_DATA, PKT_CONFIG, PKT_ACK, PKT_CONNECT, PKT_DISCONNECT = 0, 1, 2, 3, 4
+T_FLOAT64 = 9
+QUANT_NONE = 0
+TIME_PACKET, TIME_FULL_ARRAY = 0, 1
+PUBLISH_ACCUMULATE = 1
+NO_TIME_SIGNAL = 0xFFFFFFFF
+
+
+def header(pkt_type, counter, payload_bytes):
+    return struct.pack("<IBIHHI", MAGIC, pkt_type, counter, 0, 1, payload_bytes)
+
+
+def signal_desc(name, *, rate, time_mode, time_idx, unit, rows=1, cols=1, dims=0):
+    """One 136-byte signal descriptor."""
+    d = bytearray(136)
+    d[0:64] = name.encode()[:64].ljust(64, b"\0")
+    d[64] = T_FLOAT64
+    d[65] = QUANT_NONE
+    d[66] = dims
+    struct.pack_into("<II", d, 67, rows, cols)
+    struct.pack_into("<dd", d, 75, -10.0, 10.0)
+    d[91] = time_mode
+    struct.pack_into("<d", d, 92, rate)
+    struct.pack_into("<I", d, 100, time_idx)
+    d[104:136] = unit.encode()[:32].ljust(32, b"\0")
+    return bytes(d)
+
+
+def build_config(rate):
+    sigs = [
+        # The stream's clock: referenced by every data signal, so udpscope treats
+        # it as the time base rather than a plottable channel.
+        signal_desc("time", rate=0.0, time_mode=TIME_FULL_ARRAY,
+                    time_idx=NO_TIME_SIGNAL, unit="s"),
+        signal_desc("sine", rate=rate, time_mode=TIME_FULL_ARRAY, time_idx=0, unit="V"),
+        signal_desc("square", rate=rate, time_mode=TIME_FULL_ARRAY, time_idx=0, unit="V"),
+        signal_desc("ramp", rate=rate, time_mode=TIME_FULL_ARRAY, time_idx=0, unit="V"),
+    ]
+    payload = struct.pack("<I", len(sigs)) + b"".join(sigs)
+    payload += bytes([PUBLISH_ACCUMULATE])
+    return header(PKT_CONFIG, 0, len(payload)) + payload
+
+
+def build_data(counter, t0, dt, batch, freq):
+    stamps = [t0 + i * dt for i in range(batch)]
+    sine = [math.sin(2.0 * math.pi * freq * t) for t in stamps]
+    square = [1.0 if math.sin(2.0 * math.pi * freq * 0.5 * t) >= 0.0 else -1.0 for t in stamps]
+    ramp = [(freq * t) % 1.0 * 2.0 - 1.0 for t in stamps]
+    payload = struct.pack("<QI", int(t0 * 1e9), batch)
+    for arr in (stamps, sine, square, ramp):
+        payload += struct.pack("<%dd" % batch, *arr)
+    return header(PKT_DATA, counter, len(payload)) + payload
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--port", type=int, default=8000)
+    ap.add_argument("--rate", type=float, default=10000.0, help="samples per second")
+    ap.add_argument("--batch", type=int, default=100, help="samples per packet")
+    ap.add_argument("--freq", type=float, default=5.0, help="waveform frequency, Hz")
+    ap.add_argument("--duration", type=float, default=0.0, help="0 = forever")
+    ap.add_argument("--stream-scale", type=float, default=1.0,
+                    help="stream seconds per wall second: 0.1 mimics a producer whose own "
+                         "clock advances ten times slower than the wire delivers samples")
+    ap.add_argument("--declared-rate", type=float, default=-1.0,
+                    help="sampling_rate to put in CONFIG; -1 = the real rate, 0 = 'unknown'")
+    args = ap.parse_args()
+
+    dt = args.stream_scale / args.rate          # stream seconds per sample
+    period = args.batch / args.rate             # wall seconds per packet
+    declared = args.rate if args.declared_rate < 0.0 else args.declared_rate
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("0.0.0.0", args.port))
+    sock.settimeout(0.001)
+    print("mock udpstreamer: waiting for CONNECT on :%d (%.0f S/s wire, %d per packet, "
+          "stream clock x%.3g, declared %.0f S/s)"
+          % (args.port, args.rate, args.batch, args.stream_scale, declared), flush=True)
+
+    peer = None
+    counter = 1
+    t_stream = 0.0
+    started = None
+    next_send = time.monotonic()
+
+    while True:
+        try:
+            buf, addr = sock.recvfrom(2048)
+            if len(buf) >= 17:
+                magic, ptype = struct.unpack_from("<IB", buf, 0)
+                if magic == MAGIC and ptype == PKT_CONNECT:
+                    peer = addr
+                    counter = 1
+                    t_stream = 0.0
+                    started = time.monotonic()
+                    next_send = started
+                    sock.sendto(build_config(declared), peer)
+                    print("mock udpstreamer: CONNECT from %s:%d, CONFIG sent" % peer, flush=True)
+                elif magic == MAGIC and ptype == PKT_DISCONNECT:
+                    print("mock udpstreamer: DISCONNECT", flush=True)
+                    peer = None
+        except socket.timeout:
+            pass
+
+        if peer is None:
+            continue
+
+        now = time.monotonic()
+        if now < next_send:
+            time.sleep(min(next_send - now, 0.002))
+            continue
+
+        sock.sendto(build_data(counter, t_stream, dt, args.batch, args.freq), peer)
+        counter += 1
+        t_stream += args.batch * dt
+        next_send += period
+        if args.duration > 0.0 and started is not None and now - started > args.duration:
+            print("mock udpstreamer: done (%d packets)" % counter, flush=True)
+            return
+
+
+if __name__ == "__main__":
+    main()