fix(udpscope): bound accumulated-burst chaining so packet loss cannot displace the trace

Forward-chaining each accumulated burst onto the previous one suppresses
arrival jitter, but an unchecked chain never recovers: one lost datagram, or a
declared sampling rate that differs from the producer's real one, dates every
later sample early for the rest of the run. The chain is now a prediction,
compared each packet against the arrival anchor and abandoned beyond
kBurstResyncThresholdS, which bounds the error instead of accumulating it.

Plan amended so the hrt-fit fallback (unusable here: the fit needs 32 packets
and is itself corrupted by bursty arrivals) cannot come back.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Client/udpscope/.gitignore

@@ -0,0 +1,2 @@
+build/
+compile_commands.json

Client/udpscope/CMakeLists.txt

@@ -0,0 +1,132 @@
+cmake_minimum_required(VERSION 3.16)
+project(UDPScope CXX C)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+option(UDPSCOPE_BUILD_TESTS "Build the unit tests" ON)
+
+set(STREAMHUB_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../streamhub)
+set(CCLIENT_DIR   ${CMAKE_CURRENT_SOURCE_DIR}/../../Common/Client/c)
+
+# ── The standalone C UDPS client, compiled in directly ────────────────────────
+# Building it here rather than shelling out to its own Makefile keeps this a
+# single cmake --build away from a working binary.
+add_library(udpsclient STATIC ${CCLIENT_DIR}/udps_client.c)
+target_include_directories(udpsclient PUBLIC ${CCLIENT_DIR})
+target_compile_options(udpsclient PRIVATE -Wall -Wextra -Wpedantic)
+
+# ── System packages ───────────────────────────────────────────────────────────
+find_package(OpenGL REQUIRED)
+
+find_package(SDL2 QUIET CONFIG)
+if(NOT SDL2_FOUND)
+    find_package(PkgConfig REQUIRED)
+    pkg_check_modules(SDL2 REQUIRED sdl2)
+    add_library(SDL2::SDL2 INTERFACE IMPORTED)
+    target_include_directories(SDL2::SDL2 INTERFACE ${SDL2_INCLUDE_DIRS})
+    target_link_libraries(SDL2::SDL2 INTERFACE ${SDL2_LIBRARIES})
+    target_compile_options(SDL2::SDL2 INTERFACE ${SDL2_CFLAGS_OTHER})
+endif()
+
+# ── Dear ImGui + ImPlot ───────────────────────────────────────────────────────
+include(FetchContent)
+
+FetchContent_Declare(imgui
+    GIT_REPOSITORY https://github.com/ocornut/imgui.git
+    GIT_TAG        v1.91.8
+    GIT_SHALLOW    TRUE)
+FetchContent_MakeAvailable(imgui)
+
+FetchContent_Declare(implot
+    GIT_REPOSITORY https://github.com/epezent/implot.git
+    GIT_TAG        v0.17
+    GIT_SHALLOW    TRUE)
+FetchContent_MakeAvailable(implot)
+
+add_library(imgui_lib STATIC
+    ${imgui_SOURCE_DIR}/imgui.cpp
+    ${imgui_SOURCE_DIR}/imgui_draw.cpp
+    ${imgui_SOURCE_DIR}/imgui_tables.cpp
+    ${imgui_SOURCE_DIR}/imgui_widgets.cpp
+    ${imgui_SOURCE_DIR}/backends/imgui_impl_sdl2.cpp
+    ${imgui_SOURCE_DIR}/backends/imgui_impl_opengl3.cpp
+    ${implot_SOURCE_DIR}/implot.cpp
+    ${implot_SOURCE_DIR}/implot_items.cpp)
+target_include_directories(imgui_lib PUBLIC
+    ${imgui_SOURCE_DIR} ${imgui_SOURCE_DIR}/backends ${implot_SOURCE_DIR})
+target_link_libraries(imgui_lib PUBLIC SDL2::SDL2 OpenGL::GL)
+target_compile_options(imgui_lib PRIVATE -w)
+
+# ── Bundled resources, borrowed read-only from the StreamHub client ───────────
+set(RESOURCE_DIR ${STREAMHUB_DIR}/resources)
+set(FONT_DIR     ${RESOURCE_DIR}/fonts)
+
+if(EXISTS ${FONT_DIR}/fa-solid-900.ttf AND EXISTS ${FONT_DIR}/IconsFontAwesome6.h)
+    set(HAVE_FONT_AWESOME TRUE)
+    message(STATUS "Font Awesome icons enabled (${FONT_DIR})")
+else()
+    set(HAVE_FONT_AWESOME FALSE)
+    message(WARNING "Bundled Font Awesome missing — using ASCII icon fallbacks")
+endif()
+
+# Guarded: file(COPY) is a hard configure error on a missing source, which
+# would defeat the fallback the block above just chose.
+if(EXISTS ${FONT_DIR})
+    file(COPY ${FONT_DIR} DESTINATION ${CMAKE_BINARY_DIR}/resources)
+endif()
+
+# ── Core library: everything except main.cpp, so tests can link it ────────────
+set(CORE_SOURCES
+    Decimate.cpp
+    PaneTree.cpp
+    TimeBase.cpp
+    FrameDecoder.cpp
+)
+
+add_library(udpscope_core STATIC ${CORE_SOURCES})
+target_include_directories(udpscope_core PUBLIC
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${STREAMHUB_DIR})          # SignalBuffer.h, reused verbatim
+target_link_libraries(udpscope_core PUBLIC udpsclient pthread)
+target_compile_options(udpscope_core PRIVATE -Wall -Wextra -Wno-unused-parameter)
+
+# ── Application ───────────────────────────────────────────────────────────────
+set(APP_SOURCES
+    main.cpp
+)
+
+if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
+    add_executable(UDPScope ${APP_SOURCES})
+    target_link_libraries(UDPScope PRIVATE udpscope_core imgui_lib SDL2::SDL2 OpenGL::GL)
+    target_compile_definitions(UDPScope PRIVATE APP_RESOURCE_DIR="${RESOURCE_DIR}")
+    if(HAVE_FONT_AWESOME)
+        target_include_directories(UDPScope PRIVATE ${FONT_DIR})
+        target_compile_definitions(UDPScope PRIVATE HAVE_FONT_AWESOME)
+    endif()
+    target_compile_options(UDPScope PRIVATE -Wall -Wextra -Wno-unused-parameter)
+
+    install(TARGETS UDPScope DESTINATION bin)
+    install(DIRECTORY ${FONT_DIR} DESTINATION share/udpscope)
+endif()
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+if(UDPSCOPE_BUILD_TESTS)
+    FetchContent_Declare(googletest
+        GIT_REPOSITORY https://github.com/google/googletest.git
+        GIT_TAG        v1.15.2
+        GIT_SHALLOW    TRUE)
+    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(googletest)
+
+    file(GLOB TEST_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/tests/*.cpp)
+    add_executable(udpscope_tests ${TEST_SOURCES})
+    target_link_libraries(udpscope_tests PRIVATE udpscope_core GTest::gtest_main)
+    target_compile_options(udpscope_tests PRIVATE -Wall -Wextra -Wno-unused-parameter)
+
+    enable_testing()
+    include(GoogleTest)
+    gtest_discover_tests(udpscope_tests)
+endif()

Client/udpscope/Decimate.cpp

@@ -0,0 +1,47 @@
+#include "Decimate.h"
+
+#include <algorithm>
+
+namespace udpscope {
+
+void MinMaxDecimate(const double* t, const double* v, size_t n,
+                    size_t maxPoints, Series& out) {
+    out.clear();
+    if (n == 0 || t == nullptr || v == nullptr) {
+        return;
+    }
+    if (n <= maxPoints || maxPoints < 4) {
+        out.t.assign(t, t + n);
+        out.v.assign(v, v + n);
+        return;
+    }
+
+    /* Two points per bucket, so the bucket count is half the budget. */
+    const size_t buckets = maxPoints / 2;
+    out.t.reserve(buckets * 2);
+    out.v.reserve(buckets * 2);
+
+    for (size_t b = 0; b < buckets; b++) {
+        const size_t begin = (n * b) / buckets;
+        size_t       end   = (n * (b + 1)) / buckets;
+        if (end <= begin) { end = begin + 1; }
+        if (end > n) { end = n; }
+
+        size_t lo = begin, hi = begin;
+        for (size_t i = begin + 1; i < end; i++) {
+            if (v[i] < v[lo]) { lo = i; }
+            if (v[i] > v[hi]) { hi = i; }
+        }
+
+        const size_t first  = std::min(lo, hi);
+        const size_t second = std::max(lo, hi);
+        out.t.push_back(t[first]);
+        out.v.push_back(v[first]);
+        if (second != first) {
+            out.t.push_back(t[second]);
+            out.v.push_back(v[second]);
+        }
+    }
+}
+
+} /* namespace udpscope */

Client/udpscope/Decimate.h

@@ -0,0 +1,25 @@
+/**
+ * @file Decimate.h
+ * @brief Min/max envelope decimation for screen rendering.
+ */
+#pragma once
+
+#include "Types.h"
+
+namespace udpscope {
+
+/**
+ * @brief Reduce n points to at most maxPoints by emitting each bucket's
+ *        minimum and maximum, in time order.
+ *
+ * LTTB is deliberately not used. It selects representative points and will
+ * silently drop a one-sample glitch; on a scope that glitch is usually the
+ * thing being looked for. The emitted pair stays in time order rather than
+ * value order because callers binary-search the result by time.
+ *
+ * Input shorter than maxPoints is copied through unchanged.
+ */
+void MinMaxDecimate(const double* t, const double* v, size_t n,
+                    size_t maxPoints, Series& out);
+
+} /* namespace udpscope */

Client/udpscope/FrameDecoder.cpp

@@ -0,0 +1,192 @@
+#include "FrameDecoder.h"
+
+#include <cmath>
+
+namespace udpscope {
+
+/** Fallback cycle period before the first inter-packet gap is known. */
+static constexpr double kDefaultDt = 1.0e-3;
+
+/**
+ * How far the forward-chained prediction for an accumulated burst may sit from
+ * where arrival time says it should be before the chain is abandoned.
+ *
+ * A kernel draining a backlog of queued datagrams can legitimately put the
+ * prediction a few hundred milliseconds ahead of arrival, so the threshold has
+ * to be well clear of that. Anything larger is not delivery jitter: it is lost
+ * packets or a declared sampling rate that does not match the producer's real
+ * one, and both must resynchronise rather than accumulate forever. Same value
+ * and same reasoning as ClockOffset::kRecalibThresholdS.
+ */
+static constexpr double kBurstResyncThresholdS = 0.5;
+
+void FrameDecoder::setSignals(const std::vector<SignalMeta>& signals) {
+    signals_ = signals;
+    state_.assign(signals_.size(), SigState{});
+    hrtFit_.reset();
+}
+
+void FrameDecoder::reset() {
+    state_.assign(signals_.size(), SigState{});
+    hrtFit_.reset();
+}
+
+void FrameDecoder::beginFrame(const FrameView& f) {
+    if (f.hrt != 0u) { hrtFit_.add(f.hrt, f.recvTime); }
+}
+
+bool FrameDecoder::packetBurst(uint32_t idx, uint32_t nElems, double wallNow,
+                               std::vector<double>& tsOut) {
+    SigState& st = state_[idx];
+    if (!st.lastPacketValid || wallNow <= st.lastPacketWall) {
+        /* No previous arrival to span from, or time went backwards. Remember
+         * this one and drop the samples rather than store them at made-up
+         * spacing. */
+        st.lastPacketWall  = wallNow;
+        st.lastPacketValid = true;
+        return false;
+    }
+
+    const double dt = (wallNow - st.lastPacketWall) / static_cast<double>(nElems);
+    tsOut.resize(nElems);
+    for (uint32_t e = 0; e < nElems; e++) {
+        tsOut[e] = st.lastPacketWall + static_cast<double>(e + 1u) * dt;
+    }
+    st.lastPacketWall = wallNow;
+    return true;
+}
+
+bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
+                              std::vector<double>& tsOut) {
+    tsOut.clear();
+    if (idx >= signals_.size() || idx >= f.numSignals || f.counts == nullptr) {
+        return false;
+    }
+
+    const SignalMeta& d      = signals_[idx];
+    const uint32_t    nElems = f.counts[idx];
+    if (nElems == 0u) { return false; }
+
+    const double wallNow = f.recvTime;
+    SigState&    st      = state_[idx];
+
+    const bool     hasTimeSig = d.hasTimeSignal(f.numSignals);
+    const uint32_t tIdx       = hasTimeSig ? d.timeSignalIdx : 0u;
+    const double   tScale     = hasTimeSig
+                                ? TimeSignalScale(signals_[tIdx].typeCode)
+                                : 1.0e-6;
+
+    /* Rule 1: one stamp per element, straight from the time signal. */
+    if (d.timeMode == kTimeFullArray && hasTimeSig &&
+        f.counts[tIdx] >= nElems && f.values[tIdx] != nullptr) {
+        const double* tv = f.values[tIdx];
+        const double  t0 = tv[0] * tScale;
+        (void) st.offset.map(t0, wallNow);
+        const double base = st.offset.offset();
+        tsOut.resize(nElems);
+        for (uint32_t e = 0; e < nElems; e++) {
+            tsOut[e] = base + tv[e] * tScale;
+        }
+        return true;
+    }
+
+    /* Rule 2: anchor from the time signal, spread by the sampling rate. */
+    if ((d.timeMode == kTimeFirstSample || d.timeMode == kTimeLastSample) &&
+        hasTimeSig && f.counts[tIdx] >= 1u && f.values[tIdx] != nullptr) {
+        const double anchor = st.offset.map(f.values[tIdx][0] * tScale, wallNow);
+        const double dt     = (d.samplingRate > 0.0) ? (1.0 / d.samplingRate) : 0.0;
+        tsOut.resize(nElems);
+        for (uint32_t e = 0; e < nElems; e++) {
+            tsOut[e] = (d.timeMode == kTimeFirstSample)
+                     ? (anchor + static_cast<double>(e) * dt)
+                     : (anchor - static_cast<double>(nElems - 1u - e) * dt);
+        }
+        return true;
+    }
+
+    /* Rule 3: accumulated scalar, based on declared sampling rate or hrt.
+     *
+     * When samplingRate is declared the inter-element step is exact and we
+     * anchor from the end of the previous burst rather than from arrival time
+     * or hrt.  This makes the output immune to arrival jitter: even when the
+     * kernel delivers two packets microseconds apart each burst starts exactly
+     * one sample period after the previous burst ended.
+     *
+     * When samplingRate is absent we must derive dt from the hrt gap, which
+     * requires the HrtRateFit to be ready. Until then we fall back to
+     * packetBurst (arrival-time spanning), which is accurate during the normal
+     * pre-burst delivery phase that precedes the fit becoming ready. */
+    if (d.numElements() == 1u && nElems > 1u) {
+        const double dt = (d.samplingRate > 0.0)
+                          ? (1.0 / d.samplingRate)
+                          : 0.0;
+
+        if (d.samplingRate > 0.0) {
+            /* Where arrival time says this burst begins: its last element was
+             * acquired just before the packet landed. */
+            const double arrivalAnchor =
+                wallNow - static_cast<double>(nElems - 1u) * dt;
+
+            /* Chaining from the end of the previous burst is immune to arrival
+             * jitter — a kernel draining several queued datagrams microseconds
+             * apart still yields contiguous timestamps. But a pure chain is
+             * blind: one lost datagram, or a declared rate that does not match
+             * the producer's real one, displaces every later sample and never
+             * recovers. So the chain is a PREDICTION, checked each packet
+             * against arrival and abandoned when the two disagree by more than
+             * a delivery backlog can explain. That bounds the error instead of
+             * letting it accumulate. */
+            double base = arrivalAnchor;
+            if (st.lastEmittedValid) {
+                const double predicted = st.lastEmittedEnd + dt;
+                if (std::fabs(predicted - arrivalAnchor) <= kBurstResyncThresholdS) {
+                    base = predicted;
+                }
+            }
+            tsOut.resize(nElems);
+            for (uint32_t e = 0; e < nElems; e++) {
+                tsOut[e] = base + static_cast<double>(e) * dt;
+            }
+            st.lastEmittedEnd   = tsOut[nElems - 1u];
+            st.lastEmittedValid = true;
+            return true;
+        }
+
+        /* No declared rate: need hrt-derived dt. */
+        if (!hrtFit_.ready()) {
+            return packetBurst(idx, nElems, wallNow, tsOut);
+        }
+        const double hrtSec = hrtFit_.toSeconds(f.hrt);
+        const double base   = st.offset.map(hrtSec, wallNow);
+
+        double hrtDt;
+        if (st.lastAccValid && st.prevAccCount > 0u && hrtSec > st.lastAccHrtSec) {
+            /* The flushes carry contiguous RT cycles, so the gap divided by the
+             * previous packet's sample count is exactly one cycle period. */
+            hrtDt = (hrtSec - st.lastAccHrtSec) /
+                    static_cast<double>(st.prevAccCount);
+        } else {
+            hrtDt = kDefaultDt;
+        }
+
+        tsOut.resize(nElems);
+        for (uint32_t e = 0; e < nElems; e++) {
+            tsOut[e] = base + static_cast<double>(e) * hrtDt;
+        }
+        st.lastAccHrtSec  = hrtSec;
+        st.lastAccValid   = true;
+        st.prevAccCount   = nElems;
+        return true;
+    }
+
+    /* Rule 4: PACKET burst with no time reference at all. */
+    if (nElems > 1u) {
+        return packetBurst(idx, nElems, wallNow, tsOut);
+    }
+
+    /* Rule 5: plain scalar. */
+    tsOut.assign(1, wallNow);
+    return true;
+}
+
+} /* namespace udpscope */

Client/udpscope/FrameDecoder.h

@@ -0,0 +1,71 @@
+/**
+ * @file FrameDecoder.h
+ * @brief Per-element timestamp reconstruction for UDPS frames.
+ *
+ * The C client's udps_frame_element_time() is explicitly an arrival-anchored
+ * estimate. It is not sufficient: the kernel frequently delivers several queued
+ * datagrams in one burst, so two packets are processed microseconds apart even
+ * though each represents ~10 ms of signal, and arrival-time interpolation then
+ * crams a packet's samples into that tiny gap — the trace renders as a sawtooth.
+ * Source/Applications/StreamHub/UDPSourceSession.cpp documents this failure and
+ * solves it; these are the same rules, computed from udps_frame_t's own fields
+ * so the scope and StreamHub agree on the same stream.
+ */
+#pragma once
+
+#include "TimeBase.h"
+#include "Types.h"
+
+#include <vector>
+
+namespace udpscope {
+
+class FrameDecoder {
+public:
+    /** Installs the signal table. Clears all per-signal timing history. */
+    void setSignals(const std::vector<SignalMeta>& signals);
+
+    const std::vector<SignalMeta>& signals() const { return signals_; }
+
+    /** Call once per frame, before any timestamps() call for that frame. */
+    void beginFrame(const FrameView& f);
+
+    /**
+     * @brief Timestamps for every value of signal @p idx in this frame.
+     * @return false when the signal produced nothing usable — an empty slot, or
+     *         the first PACKET burst after connect, which has no previous
+     *         arrival to span from and would otherwise poison the ring with
+     *         wrongly spaced timestamps.
+     */
+    bool timestamps(const FrameView& f, uint32_t idx, std::vector<double>& tsOut);
+
+    /** Forgets all timing history; call on reconnect. */
+    void reset();
+
+private:
+    bool packetBurst(uint32_t idx, uint32_t nElems, double wallNow,
+                     std::vector<double>& tsOut);
+
+    struct SigState {
+        ClockOffset offset;
+        double      lastPacketWall  = 0.0;
+        bool        lastPacketValid = false;
+        double      lastAccHrtSec   = 0.0;
+        bool        lastAccValid    = false;
+        uint32_t    prevAccCount    = 0;
+        /** For accumulated scalars with a declared sampling rate: end timestamp
+         *  of the most recently emitted burst. The next burst is PREDICTED to
+         *  start one sample period after it — immune to arrival-time jitter —
+         *  but the prediction is discarded when arrival time disagrees with it
+         *  by more than a delivery backlog can explain, so packet loss cannot
+         *  displace the trace permanently. */
+        double      lastEmittedEnd  = 0.0;
+        bool        lastEmittedValid = false;
+    };
+
+    std::vector<SignalMeta> signals_;
+    std::vector<SigState>   state_;
+    HrtRateFit              hrtFit_;
+};
+
+} /* namespace udpscope */

Client/udpscope/PaneTree.cpp

@@ -0,0 +1,157 @@
+#include "PaneTree.h"
+
+#include <algorithm>
+#include <cmath>
+
+namespace udpscope {
+
+PaneTree::PaneTree() : root_(new PaneNode()) {}
+
+void PaneTree::setRoot(std::unique_ptr<PaneNode> node) {
+    if (node) { root_ = std::move(node); }
+}
+
+double PaneTree::clampRatio(double ratio, double extent) {
+    if (extent <= 2.0 * kMinPaneSize) {
+        return 0.5;   /* Too small to honour the minimum on both sides. */
+    }
+    const double lo = kMinPaneSize / extent;
+    return std::min(std::max(ratio, lo), 1.0 - lo);
+}
+
+void PaneTree::layoutNode(PaneNode* node, const Rect& r,
+                          std::vector<Placed>& leaves,
+                          std::vector<Splitter>& splitters) {
+    if (node == nullptr) { return; }
+    if (node->leaf) {
+        leaves.push_back(Placed{node, r});
+        return;
+    }
+
+    if (node->orient == Orient::Columns) {
+        const double ratio = clampRatio(node->ratio, r.w);
+        const double wA    = r.w * ratio;
+        layoutNode(node->a.get(), Rect{r.x, r.y, wA, r.h}, leaves, splitters);
+        layoutNode(node->b.get(), Rect{r.x + wA, r.y, r.w - wA, r.h}, leaves, splitters);
+        splitters.push_back(Splitter{
+            node,
+            Rect{r.x + wA - kSplitterGrab * 0.5, r.y, kSplitterGrab, r.h},
+            Orient::Columns});
+    } else {
+        const double ratio = clampRatio(node->ratio, r.h);
+        const double hA    = r.h * ratio;
+        layoutNode(node->a.get(), Rect{r.x, r.y, r.w, hA}, leaves, splitters);
+        layoutNode(node->b.get(), Rect{r.x, r.y + hA, r.w, r.h - hA}, leaves, splitters);
+        splitters.push_back(Splitter{
+            node,
+            Rect{r.x, r.y + hA - kSplitterGrab * 0.5, r.w, kSplitterGrab},
+            Orient::Rows});
+    }
+}
+
+void PaneTree::layout(const Rect& area,
+                      std::vector<Placed>& leaves,
+                      std::vector<Splitter>& splitters) const {
+    leaves.clear();
+    splitters.clear();
+    layoutNode(root_.get(), area, leaves, splitters);
+}
+
+void PaneTree::splitLeaf(PaneNode* leaf, Orient orient) {
+    if (leaf == nullptr || !leaf->leaf) { return; }
+
+    /* Move the existing content into a new first child; the second is empty. */
+    std::unique_ptr<PaneNode> first(new PaneNode());
+    first->signals     = std::move(leaf->signals);
+    first->profilePane = leaf->profilePane;
+
+    std::unique_ptr<PaneNode> second(new PaneNode());
+
+    leaf->leaf   = false;
+    leaf->orient = orient;
+    leaf->ratio  = 0.5;
+    leaf->signals.clear();
+    leaf->a = std::move(first);
+    leaf->b = std::move(second);
+}
+
+PaneNode* PaneTree::findParent(PaneNode* node, const PaneNode* child) {
+    if (node == nullptr || node->leaf) { return nullptr; }
+    if (node->a.get() == child || node->b.get() == child) { return node; }
+    if (PaneNode* p = findParent(node->a.get(), child)) { return p; }
+    return findParent(node->b.get(), child);
+}
+
+void PaneTree::closeLeaf(PaneNode* leaf) {
+    if (leaf == nullptr || !leaf->leaf) { return; }
+
+    PaneNode* parent = findParent(root_.get(), leaf);
+    if (parent == nullptr) {
+        return;   /* The root is the only leaf; a scope with no pane is useless. */
+    }
+
+    std::unique_ptr<PaneNode> survivor =
+        (parent->a.get() == leaf) ? std::move(parent->b) : std::move(parent->a);
+
+    /* Collapse the parent into the survivor in place, so the parent pointer
+     * held by any caller stays valid. */
+    parent->leaf        = survivor->leaf;
+    parent->signals     = std::move(survivor->signals);
+    parent->profilePane = survivor->profilePane;
+    parent->orient      = survivor->orient;
+    parent->ratio       = survivor->ratio;
+    parent->a           = std::move(survivor->a);
+    parent->b           = std::move(survivor->b);
+}
+
+void PaneTree::setRatio(PaneNode* split, double ratio) {
+    if (split != nullptr && !split->leaf) {
+        split->ratio = std::min(std::max(ratio, 0.0), 1.0);
+    }
+}
+
+size_t PaneTree::countLeaves(const PaneNode* node) {
+    if (node == nullptr) { return 0; }
+    if (node->leaf) { return 1; }
+    return countLeaves(node->a.get()) + countLeaves(node->b.get());
+}
+
+size_t PaneTree::leafCount() const { return countLeaves(root_.get()); }
+
+const PaneTree::Splitter* PaneTree::hitTestSplitter(
+        const std::vector<Splitter>& splitters, double px, double py) const {
+    for (const Splitter& s : splitters) {
+        if (s.rect.contains(px, py)) { return &s; }
+    }
+    return nullptr;
+}
+
+Handle PaneTree::hitTestHandle(const Rect& pane, double px, double py) {
+    if (!pane.contains(px, py)) { return Handle::None; }
+
+    const double relX = px - pane.x;
+    const double relY = py - pane.y;
+    const double midY = pane.h * 0.5;
+    const double midX = pane.w * 0.5;
+    const double half = kHandleSize * 0.5;
+
+    /* Close sits in the top-right corner and wins over the edge handles. */
+    if (relX >= pane.w - kHandleSize && relY <= kHandleSize) {
+        return Handle::Close;
+    }
+    if (relX <= kHandleSize && std::abs(relY - midY) <= half * 3.0) {
+        return Handle::Left;
+    }
+    if (relX >= pane.w - kHandleSize && std::abs(relY - midY) <= half * 3.0) {
+        return Handle::Right;
+    }
+    if (relY <= kHandleSize && std::abs(relX - midX) <= half * 3.0) {
+        return Handle::Top;
+    }
+    if (relY >= pane.h - kHandleSize && std::abs(relX - midX) <= half * 3.0) {
+        return Handle::Bottom;
+    }
+    return Handle::None;
+}
+
+} /* namespace udpscope */

Client/udpscope/PaneTree.h

@@ -0,0 +1,116 @@
+/**
+ * @file PaneTree.h
+ * @brief Binary-space-partition layout of the plot area.
+ *
+ * Framework-free: no ImGui, no UDPS. The geometry and the hit-testing are the
+ * fiddly part of the pane UI and are unit-tested without a window.
+ */
+#pragma once
+
+#include "Types.h"
+
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace udpscope {
+
+/** Direction a node splits its rectangle in. */
+enum class Orient { Columns, Rows };
+
+/** Vertical scaling strategy for one trace. */
+enum class VMode { Auto, Range, Manual };
+
+struct VScale {
+    VMode  mode   = VMode::Auto;
+    double div    = 1.0;   /**< Units per division, Manual only. */
+    double offset = 0.0;   /**< Centre value, Manual only. */
+};
+
+/** One signal drawn in one pane. Signals are named, never indexed. */
+struct Assignment {
+    std::string signalName;
+    Color       color;
+    float       lineWidth = 1.5f;
+    VScale      vs;
+};
+
+/** Smallest a pane may be squeezed to, in pixels. */
+constexpr double kMinPaneSize = 80.0;
+
+/** Thickness of the splitter drag zone and of the inset handles, in pixels. */
+constexpr double kSplitterGrab = 6.0;
+constexpr double kHandleSize   = 18.0;
+
+/** What the pointer is over inside a pane. */
+enum class Handle { None, Left, Right, Top, Bottom, Close };
+
+struct PaneNode {
+    bool leaf = true;
+
+    /* leaf only */
+    std::vector<Assignment> signals;
+    bool profilePane = false;   /**< Holds vector signals, not time series. */
+
+    /* split only */
+    Orient orient = Orient::Columns;
+    double ratio  = 0.5;        /**< First child's share of the parent. */
+    std::unique_ptr<PaneNode> a, b;
+};
+
+class PaneTree {
+public:
+    struct Placed   { PaneNode* leaf; Rect rect; };
+    struct Splitter { PaneNode* node; Rect rect; Orient orient; };
+
+    PaneTree();
+
+    PaneNode* root() { return root_.get(); }
+    const PaneNode* root() const { return root_.get(); }
+
+    /** Replaces the whole tree, e.g. when loading a session. */
+    void setRoot(std::unique_ptr<PaneNode> node);
+
+    /**
+     * @brief Walk the tree, producing every leaf's rectangle and every split's
+     *        drag zone.
+     */
+    void layout(const Rect& area,
+                std::vector<Placed>& leaves,
+                std::vector<Splitter>& splitters) const;
+
+    /** Turn a leaf into a split; the original content stays in the first child. */
+    void splitLeaf(PaneNode* leaf, Orient orient);
+
+    /** Replace the leaf's parent with its sibling. No-op on the last leaf. */
+    void closeLeaf(PaneNode* leaf);
+
+    void setRatio(PaneNode* split, double ratio);
+
+    size_t leafCount() const;
+
+    /** @return the splitter under the point, or nullptr. */
+    const Splitter* hitTestSplitter(const std::vector<Splitter>& splitters,
+                                    double px, double py) const;
+
+    /**
+     * @brief Which inset handle of @p pane the point is over.
+     *
+     * Handles sit inside the pane so they never overlap the splitter drag zone,
+     * and every pane has all four regardless of whether it touches a window
+     * edge — a pane in the middle of a 3x3 touches none.
+     */
+    static Handle hitTestHandle(const Rect& pane, double px, double py);
+
+private:
+    static void layoutNode(PaneNode* node, const Rect& r,
+                           std::vector<Placed>& leaves,
+                           std::vector<Splitter>& splitters);
+    static size_t countLeaves(const PaneNode* node);
+    static PaneNode* findParent(PaneNode* node, const PaneNode* child);
+    static double clampRatio(double ratio, double extent);
+
+    std::unique_ptr<PaneNode> root_;
+};
+
+} /* namespace udpscope */

Client/udpscope/TimeBase.cpp

@@ -0,0 +1,74 @@
+#include "TimeBase.h"
+
+#include <cmath>
+
+namespace udpscope {
+
+/* UDPS_T_UINT64 == 6 in Common/UDP/UDPSProtocol.h. Spelled numerically so this
+ * translation unit stays free of the C client header. */
+static constexpr uint8_t kTypeUint64 = 6u;
+
+double TimeSignalScale(uint8_t typeCode) {
+    return (typeCode == kTypeUint64) ? 1.0e-9 : 1.0e-6;
+}
+
+double ClockOffset::map(double producerSec, double wallSec) {
+    /* Symmetric on purpose. Delivery jitter of a few tens of ms either side of
+     * the prediction must not reset the offset or the whole trace wobbles, but a
+     * producer clock that steps in EITHER direction has to be picked up: a
+     * restart leaves the prediction behind the wall clock, an NTP correction on
+     * the producer's host leaves it ahead. A one-sided test silently never fires
+     * for the second case and the trace sits in the future for the whole run. */
+    if (!valid_ || std::fabs(wallSec - (offset_ + producerSec)) > kRecalibThresholdS) {
+        offset_ = wallSec - producerSec;
+        valid_  = true;
+    }
+    return offset_ + producerSec;
+}
+
+void HrtRateFit::reset() {
+    samples_.clear();
+    n_    = 0;
+    rate_ = 0.0;
+}
+
+void HrtRateFit::add(uint64_t hrt, double wallSec) {
+    samples_.push_back(Sample{static_cast<double>(hrt), wallSec});
+    if (samples_.size() > kWindow) { samples_.pop_front(); }
+    n_++;
+    if (n_ >= kMinSamples) { refit(); }
+}
+
+void HrtRateFit::refit() {
+    const size_t n = samples_.size();
+    if (n < 2) { return; }
+
+    /* Least squares slope of hrt against wall time. Both are subtracted from
+     * their first value first: raw hrt counts and epoch seconds are large
+     * enough that the naive sums lose precision. */
+    const double h0 = samples_.front().hrt;
+    const double w0 = samples_.front().wall;
+
+    double sw = 0.0, sh = 0.0, sww = 0.0, swh = 0.0;
+    for (const Sample& s : samples_) {
+        const double w = s.wall - w0;
+        const double h = s.hrt - h0;
+        sw  += w;
+        sh  += h;
+        sww += w * w;
+        swh += w * h;
+    }
+    const double dn    = static_cast<double>(n);
+    const double denom = dn * sww - sw * sw;
+    if (std::fabs(denom) < 1e-12) { return; }
+
+    const double slope = (dn * swh - sw * sh) / denom;
+    if (slope > 0.0 && std::isfinite(slope)) { rate_ = slope; }
+}
+
+double HrtRateFit::toSeconds(uint64_t hrt) const {
+    if (rate_ <= 0.0) { return 0.0; }
+    return static_cast<double>(hrt) / rate_;
+}
+
+} /* namespace udpscope */

Client/udpscope/TimeBase.h

@@ -0,0 +1,87 @@
+/**
+ * @file TimeBase.h
+ * @brief Producer-clock to wall-clock reconstruction.
+ *
+ * Framework-free. A UDPS stream's accurate timestamps come from a producer
+ * clock — either a declared time signal or the packet's embedded hrt — and both
+ * need mapping onto the client's wall clock before they can be plotted.
+ */
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <deque>
+
+namespace udpscope {
+
+/**
+ * @brief Seconds per count of a time signal, from its type code.
+ *
+ * The protocol carries uint64 time signals in nanoseconds and everything else
+ * in microseconds; this mirrors UDPSourceSession so the two agree on a stream.
+ */
+double TimeSignalScale(uint8_t typeCode);
+
+/**
+ * @brief A latched producer-to-wall offset.
+ *
+ * Established from the first sample and then held, so network jitter does not
+ * wobble the trace. Only a drift beyond kRecalibThresholdS — a producer restart
+ * or re-phase, not delivery noise — forces a new calibration.
+ */
+class ClockOffset {
+public:
+    static constexpr double kRecalibThresholdS = 0.5;
+
+    /** @return producerSec mapped onto wall clock. */
+    double map(double producerSec, double wallSec);
+
+    bool valid() const { return valid_; }
+    void reset() { valid_ = false; offset_ = 0.0; }
+    double offset() const { return offset_; }
+
+private:
+    double offset_ = 0.0;
+    bool   valid_  = false;
+};
+
+/**
+ * @brief Recovers the producer's hrt tick rate by least squares against arrival
+ *        time.
+ *
+ * The protocol does not carry the tick rate, and StreamHub's approach of using
+ * the local MARTe HighResolutionTimer frequency is only valid when the client
+ * runs on the producer's host. A remote bench scope cannot assume that, so the
+ * rate is measured: hrt against recv_time is a straight line whose slope is
+ * ticks per second.
+ */
+class HrtRateFit {
+public:
+    static constexpr size_t kMinSamples = 32;
+    static constexpr size_t kWindow     = 256;
+
+    void add(uint64_t hrt, double wallSec);
+    bool ready() const { return n_ >= kMinSamples && rate_ > 0.0; }
+    double ticksPerSecond() const { return rate_; }
+    /**
+     * @brief Converts a tick count to seconds on the PRODUCER's own epoch.
+     *
+     * The fit recovers the slope only and discards the intercept, so this is
+     * `hrt / ticksPerSecond()` — not a wall-clock time. A producer's hrt counts
+     * from its own boot, not from the Unix epoch. Pass the result to
+     * ClockOffset::map() to land it on the wall clock; latching that arbitrary
+     * epoch difference is precisely what ClockOffset is for.
+     */
+    double toSeconds(uint64_t hrt) const;
+    void reset();
+
+private:
+    void refit();
+
+    struct Sample { double hrt; double wall; };
+    std::deque<Sample> samples_;
+    size_t n_    = 0;
+    double rate_ = 0.0;
+};
+
+} /* namespace udpscope */

Client/udpscope/Types.h

@@ -0,0 +1,103 @@
+/**
+ * @file Types.h
+ * @brief Plain data shared across UDPScope modules. No logic, no dependencies.
+ */
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace udpscope {
+
+/** A time series as two parallel arrays, which is what ImPlot wants. */
+struct Series {
+    std::vector<double> t;
+    std::vector<double> v;
+
+    void clear() { t.clear(); v.clear(); }
+    size_t size() const { return t.size(); }
+    bool empty() const { return t.empty(); }
+};
+
+/** RGBA in 0..1. Framework-free so PaneTree needs no ImGui. */
+struct Color {
+    float r = 1.f, g = 1.f, b = 1.f, a = 1.f;
+};
+
+/** Screen rectangle in pixels. */
+struct Rect {
+    double x = 0.0, y = 0.0, w = 0.0, h = 0.0;
+
+    bool contains(double px, double py) const {
+        return px >= x && px < (x + w) && py >= y && py < (y + h);
+    }
+};
+
+/* Protocol constants, spelled out rather than included, so the framework-free
+ * modules stay independent of udps_client.h. They mirror Common/UDP/UDPSProtocol.h. */
+constexpr uint8_t  kTimePacket      = 0;
+constexpr uint8_t  kTimeFullArray   = 1;
+constexpr uint8_t  kTimeFirstSample = 2;
+constexpr uint8_t  kTimeLastSample  = 3;
+constexpr uint32_t kNoTimeSignal    = 0xFFFFFFFFu;
+
+/** Framework-free mirror of udps_signal_t, plus UI state. */
+struct SignalMeta {
+    std::string name;
+    uint8_t     typeCode      = 255;
+    uint8_t     quantType     = 0;
+    uint32_t    numRows       = 1;
+    uint32_t    numCols       = 1;
+    double      rangeMin      = 0.0;
+    double      rangeMax      = 0.0;
+    uint8_t     timeMode      = kTimePacket;
+    double      samplingRate  = 0.0;
+    uint32_t    timeSignalIdx = kNoTimeSignal;
+    std::string unit;
+
+    /** User override: treat an ambiguous PACKET array as a profile, not a burst. */
+    bool profileOverride = false;
+
+    uint32_t numElements() const {
+        const uint64_t n = static_cast<uint64_t>(numRows ? numRows : 1u) *
+                           static_cast<uint64_t>(numCols ? numCols : 1u);
+        return n == 0u ? 1u : static_cast<uint32_t>(n);
+    }
+
+    bool hasTimeSignal(uint32_t numSignals) const {
+        return timeSignalIdx != kNoTimeSignal && timeSignalIdx < numSignals;
+    }
+
+    /**
+     * @brief True when this array should be plotted against element index
+     *        rather than unrolled onto the time axis.
+     *
+     * Only PACKET arrays are ambiguous: the producer stamped the whole datagram
+     * with one time, which is what a genuine vector looks like and also what a
+     * burst carrying no time metadata looks like. Default is burst, matching
+     * UDPSourceSession, with this flag as the user's override.
+     */
+    bool isVectorProfile() const {
+        return profileOverride && numElements() > 1u && timeMode == kTimePacket;
+    }
+};
+
+/**
+ * @brief Non-owning mirror of udps_frame_t.
+ *
+ * Kept separate from the C struct so FrameDecoder can be tested with plain
+ * arrays and no socket. Points at memory owned by the caller.
+ */
+struct FrameView {
+    uint32_t             counter    = 0;
+    uint64_t             hrt        = 0;
+    double               recvTime   = 0.0;
+    uint32_t             numSamples = 1;
+    uint32_t             numSignals = 0;
+    const double* const* values     = nullptr;  /**< values[i][0..counts[i]) */
+    const uint32_t*      counts     = nullptr;
+};
+
+} /* namespace udpscope */

Client/udpscope/tests/DecimateTest.cpp

@@ -0,0 +1,90 @@
+#include "Decimate.h"
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <vector>
+
+using namespace udpscope;
+
+TEST(MinMaxDecimate, PassesShortInputThroughUnchanged) {
+    const std::vector<double> t{0.0, 1.0, 2.0};
+    const std::vector<double> v{5.0, 6.0, 7.0};
+    Series out;
+
+    MinMaxDecimate(t.data(), v.data(), t.size(), 100, out);
+
+    EXPECT_EQ(out.t, t);
+    EXPECT_EQ(out.v, v);
+}
+
+// The whole reason for preferring min/max over LTTB: a single-sample spike is
+// usually the thing the user is looking for, and it must survive decimation.
+TEST(MinMaxDecimate, PreservesAnIsolatedSpike) {
+    std::vector<double> t(1000), v(1000, 0.0);
+    for (size_t i = 0; i < t.size(); i++) { t[i] = static_cast<double>(i); }
+    v[437] = 42.0;
+    Series out;
+
+    MinMaxDecimate(t.data(), v.data(), t.size(), 50, out);
+
+    ASSERT_FALSE(out.v.empty());
+    EXPECT_EQ(*std::max_element(out.v.begin(), out.v.end()), 42.0);
+}
+
+TEST(MinMaxDecimate, PreservesTheExtremesOfEveryBucket) {
+    std::vector<double> t(100), v(100);
+    for (size_t i = 0; i < t.size(); i++) {
+        t[i] = static_cast<double>(i);
+        v[i] = (i % 10 == 3) ? -9.0 : ((i % 10 == 7) ? 9.0 : 0.0);
+    }
+    Series out;
+
+    MinMaxDecimate(t.data(), v.data(), t.size(), 20, out);
+
+    EXPECT_EQ(*std::min_element(out.v.begin(), out.v.end()), -9.0);
+    EXPECT_EQ(*std::max_element(out.v.begin(), out.v.end()), 9.0);
+}
+
+// A ring whose timestamps are not monotonic breaks any later binary search by
+// time, so the pair emitted per bucket must be ordered by time, not by value.
+TEST(MinMaxDecimate, EmitsPointsInTimeOrder) {
+    // Two buckets of four. In the first the minimum comes before the maximum,
+    // in the second the order is reversed. An implementation that emitted
+    // (min, max) by value rather than by time passes on bucket 0 and fails on
+    // bucket 1, so this data exercises the swap that a monotonically growing
+    // ramp never triggers.
+    const double st[8] = {0, 1, 2, 3, 4, 5, 6, 7};
+    const double sv[8] = {-5, 0, 0, 9, 9, 0, 0, -5};
+    Series pair;
+    MinMaxDecimate(st, sv, 8, 4, pair);
+    ASSERT_EQ(pair.size(), 4u);
+    const double wantT[4] = {0, 3, 4, 7};
+    const double wantV[4] = {-5, 9, 9, -5};
+    for (size_t i = 0; i < 4; i++) {
+        EXPECT_EQ(pair.t[i], wantT[i]) << "time at " << i;
+        EXPECT_EQ(pair.v[i], wantV[i]) << "value at " << i;
+    }
+
+    std::vector<double> t(400), v(400);
+    for (size_t i = 0; i < t.size(); i++) {
+        t[i] = static_cast<double>(i);
+        v[i] = (i % 2 == 0) ? -static_cast<double>(i) : static_cast<double>(i);
+    }
+    Series out;
+
+    MinMaxDecimate(t.data(), v.data(), t.size(), 40, out);
+
+    ASSERT_GT(out.t.size(), 1u);
+    for (size_t i = 1; i < out.t.size(); i++) {
+        EXPECT_LE(out.t[i - 1], out.t[i]) << "at index " << i;
+    }
+}
+
+TEST(MinMaxDecimate, HandlesEmptyInput) {
+    Series out;
+    out.t.push_back(1.0);   // must be cleared
+    MinMaxDecimate(nullptr, nullptr, 0, 10, out);
+    EXPECT_TRUE(out.t.empty());
+    EXPECT_TRUE(out.v.empty());
+}

Client/udpscope/tests/FrameDecoderTest.cpp

@@ -0,0 +1,315 @@
+#include "FrameDecoder.h"
+
+#include <gtest/gtest.h>
+
+#include <vector>
+
+using namespace udpscope;
+
+namespace {
+
+/** Builds a FrameView over vectors the test owns. */
+struct FrameBuilder {
+    std::vector<std::vector<double>> storage;
+    std::vector<const double*>       ptrs;
+    std::vector<uint32_t>            counts;
+    FrameView                        view;
+
+    void addSignal(std::vector<double> vals) {
+        storage.push_back(std::move(vals));
+    }
+
+    const FrameView& build(uint64_t hrt, double recvTime, uint32_t numSamples = 1) {
+        ptrs.clear();
+        counts.clear();
+        for (const auto& s : storage) {
+            ptrs.push_back(s.data());
+            counts.push_back(static_cast<uint32_t>(s.size()));
+        }
+        view.hrt        = hrt;
+        view.recvTime   = recvTime;
+        view.numSamples = numSamples;
+        view.numSignals = static_cast<uint32_t>(storage.size());
+        view.values     = ptrs.data();
+        view.counts     = counts.data();
+        return view;
+    }
+};
+
+SignalMeta burst(const char* name, uint8_t timeMode, double rate,
+                 uint32_t elems, uint32_t timeIdx) {
+    SignalMeta m;
+    m.name          = name;
+    m.typeCode      = 8;              /* float32 */
+    m.numRows       = elems;
+    m.numCols       = 1;
+    m.timeMode      = timeMode;
+    m.samplingRate  = rate;
+    m.timeSignalIdx = timeIdx;
+    return m;
+}
+
+SignalMeta timeSignal(const char* name, uint32_t elems) {
+    SignalMeta m;
+    m.name     = name;
+    m.typeCode = 6;                   /* uint64 -> nanoseconds */
+    m.numRows  = elems;
+    m.numCols  = 1;
+    return m;
+}
+
+} /* namespace */
+
+TEST(FrameDecoder, FullArrayTakesOneStampPerElementFromTheTimeSignal) {
+    FrameDecoder dec;
+    dec.setSignals({burst("Sine", kTimeFullArray, 1000.0, 4, 1),
+                    timeSignal("Time", 4)});
+
+    FrameBuilder fb;
+    fb.addSignal({1.0, 2.0, 3.0, 4.0});
+    /* Nanoseconds: 5.000, 5.001, 5.002, 5.003 s of producer time. */
+    fb.addSignal({5.0e9, 5.001e9, 5.002e9, 5.003e9});
+    const FrameView& f = fb.build(0, 1000.0);
+
+    dec.beginFrame(f);
+    std::vector<double> ts;
+    ASSERT_TRUE(dec.timestamps(f, 0, ts));
+    ASSERT_EQ(ts.size(), 4u);
+
+    /* Element 0 lands on the arrival time; the rest keep the producer spacing. */
+    EXPECT_NEAR(ts[0], 1000.000, 1e-9);
+    EXPECT_NEAR(ts[1], 1000.001, 1e-9);
+    EXPECT_NEAR(ts[2], 1000.002, 1e-9);
+    EXPECT_NEAR(ts[3], 1000.003, 1e-9);
+}
+
+TEST(FrameDecoder, FirstSampleAnchorsElementZeroAndCountsForward) {
+    FrameDecoder dec;
+    dec.setSignals({burst("Sine", kTimeFirstSample, 1000.0, 4, 1),
+                    timeSignal("Time", 1)});
+
+    FrameBuilder fb;
+    fb.addSignal({1.0, 2.0, 3.0, 4.0});
+    fb.addSignal({7.0e9});
+    const FrameView& f = fb.build(0, 2000.0);
+
+    dec.beginFrame(f);
+    std::vector<double> ts;
+    ASSERT_TRUE(dec.timestamps(f, 0, ts));
+    ASSERT_EQ(ts.size(), 4u);
+    EXPECT_NEAR(ts[0], 2000.000, 1e-9);
+    EXPECT_NEAR(ts[3], 2000.003, 1e-9);
+}
+
+TEST(FrameDecoder, LastSampleAnchorsTheFinalElementAndCountsBackward) {
+    FrameDecoder dec;
+    dec.setSignals({burst("Sine", kTimeLastSample, 1000.0, 4, 1),
+                    timeSignal("Time", 1)});
+
+    FrameBuilder fb;
+    fb.addSignal({1.0, 2.0, 3.0, 4.0});
+    fb.addSignal({7.0e9});
+    const FrameView& f = fb.build(0, 3000.0);
+
+    dec.beginFrame(f);
+    std::vector<double> ts;
+    ASSERT_TRUE(dec.timestamps(f, 0, ts));
+    ASSERT_EQ(ts.size(), 4u);
+    EXPECT_NEAR(ts[3], 3000.000, 1e-9);
+    EXPECT_NEAR(ts[0], 3000.000 - 0.003, 1e-9);
+}
+
+TEST(FrameDecoder, PlainScalarUsesArrivalTime) {
+    FrameDecoder dec;
+    SignalMeta m;
+    m.name = "Level";
+    m.typeCode = 9;
+    dec.setSignals({m});
+
+    FrameBuilder fb;
+    fb.addSignal({42.0});
+    const FrameView& f = fb.build(0, 1234.5);
+
+    dec.beginFrame(f);
+    std::vector<double> ts;
+    ASSERT_TRUE(dec.timestamps(f, 0, ts));
+    ASSERT_EQ(ts.size(), 1u);
+    EXPECT_DOUBLE_EQ(ts[0], 1234.5);
+}
+
+// This is the failure UDPSourceSession.cpp:560 documents. The kernel delivers
+// two queued datagrams microseconds apart even though each carries 10 ms of
+// signal. Dating from arrival crams the second packet's samples into that gap
+// and the trace becomes a sawtooth; dating from the producer hrt does not.
+TEST(FrameDecoder, AccumulatedScalarSurvivesBurstyDelivery) {
+    FrameDecoder dec;
+    SignalMeta m;
+    m.name         = "Acc";
+    m.typeCode     = 9;
+    m.numRows      = 1;
+    m.samplingRate = 1000.0;          /* 1 kHz, 10 samples = 10 ms per packet */
+    dec.setSignals({m});
+
+    const double ticks = 1.0e9;
+    std::vector<double> all;
+
+    for (int p = 0; p < 40; p++) {
+        FrameBuilder fb;
+        fb.addSignal(std::vector<double>(10, static_cast<double>(p)));
+        const double producerSec = 100.0 + p * 0.010;
+        /* Packets 20+ arrive in a burst, all within 50 us of each other. */
+        const double arrival = (p < 20) ? (500.0 + p * 0.010)
+                                        : (500.2 + (p - 20) * 0.00005);
+        const FrameView& f = fb.build(static_cast<uint64_t>(producerSec * ticks),
+                                      arrival, 10);
+        dec.beginFrame(f);
+        std::vector<double> ts;
+        if (dec.timestamps(f, 0, ts)) {
+            all.insert(all.end(), ts.begin(), ts.end());
+        }
+    }
+
+    ASSERT_GT(all.size(), 300u);
+    for (size_t i = 1; i < all.size(); i++) {
+        EXPECT_GT(all[i], all[i - 1]) << "non-monotonic at " << i;
+        EXPECT_NEAR(all[i] - all[i - 1], 0.001, 2e-4)
+            << "spacing collapsed at " << i << " (sawtooth)";
+    }
+}
+
+// The counterweight to the test above. Suppressing arrival jitter by chaining
+// each burst onto the previous one is only safe while the chain is checked: on
+// UDP, packets are lost, and a chain that ignores arrival entirely closes the
+// hole silently and dates every later sample a full second early — for the rest
+// of the run, because nothing ever pulls it back. The prediction has to be
+// abandoned once arrival contradicts it by more than a delivery backlog could.
+TEST(FrameDecoder, AccumulatedScalarResynchronisesAfterLostPackets) {
+    FrameDecoder dec;
+    SignalMeta m;
+    m.name         = "Acc";
+    m.typeCode     = 9;
+    m.numRows      = 1;
+    m.samplingRate = 1000.0;          /* 10 samples = 10 ms per packet */
+    dec.setSignals({m});
+
+    std::vector<double> ts;
+    for (int p = 0; p < 10; p++) {
+        FrameBuilder fb;
+        fb.addSignal(std::vector<double>(10, 1.0));
+        const FrameView& f = fb.build(0, 500.0 + p * 0.010, 10);
+        dec.beginFrame(f);
+        ASSERT_TRUE(dec.timestamps(f, 0, ts));
+    }
+    /* Contiguous so far: burst 9 ends at 500.090. */
+    EXPECT_NEAR(ts[9], 500.090, 1e-9);
+
+    /* A full second of packets never arrives. The next one lands at 501.100. */
+    FrameBuilder fb;
+    fb.addSignal(std::vector<double>(10, 1.0));
+    const FrameView& f = fb.build(0, 501.100, 10);
+    dec.beginFrame(f);
+    ASSERT_TRUE(dec.timestamps(f, 0, ts));
+
+    /* Chaining blindly would put this burst at 500.091..500.100, overlapping
+     * the gap as though no data were missing. */
+    EXPECT_NEAR(ts[0], 501.091, 1e-9);
+    EXPECT_NEAR(ts[9], 501.100, 1e-9);
+}
+
+TEST(FrameDecoder, AccumulatedScalarDerivesDtFromTheHrtGapWhenNoRateIsDeclared) {
+    FrameDecoder dec;
+    SignalMeta m;
+    m.name         = "Acc";
+    m.typeCode     = 9;
+    m.samplingRate = 0.0;             /* undeclared */
+    dec.setSignals({m});
+
+    const double ticks = 1.0e9;
+    std::vector<double> last;
+    for (int p = 0; p < 40; p++) {
+        FrameBuilder fb;
+        fb.addSignal(std::vector<double>(10, 1.0));
+        const double producerSec = 100.0 + p * 0.010;   /* 10 ms per packet */
+        const FrameView& f = fb.build(static_cast<uint64_t>(producerSec * ticks),
+                                      700.0 + p * 0.010, 10);
+        dec.beginFrame(f);
+        std::vector<double> ts;
+        if (dec.timestamps(f, 0, ts)) { last = ts; }
+    }
+
+    ASSERT_EQ(last.size(), 10u);
+    /* 10 ms of producer time across 10 samples is a 1 ms period. */
+    EXPECT_NEAR(last[1] - last[0], 0.001, 1e-5);
+}
+
+// A PACKET burst has no per-element time at all. Elements span
+// (lastPacket, thisPacket] — backwards from arrival, because the samples were
+// acquired before the packet landed. Forward extrapolation would let a jittered
+// packet overlap the next one and break ring monotonicity.
+TEST(FrameDecoder, PacketBurstDropsTheFirstFrameThenSpansBackwards) {
+    FrameDecoder dec;
+    dec.setSignals({burst("Raw", kTimePacket, 0.0, 5, kNoTimeSignal)});
+
+    FrameBuilder fb1;
+    fb1.addSignal({1.0, 2.0, 3.0, 4.0, 5.0});
+    const FrameView& f1 = fb1.build(0, 10.0);
+    dec.beginFrame(f1);
+    std::vector<double> ts;
+    EXPECT_FALSE(dec.timestamps(f1, 0, ts))
+        << "the first packet has no previous arrival to span from";
+
+    FrameBuilder fb2;
+    fb2.addSignal({6.0, 7.0, 8.0, 9.0, 10.0});
+    const FrameView& f2 = fb2.build(0, 10.05);
+    dec.beginFrame(f2);
+    ASSERT_TRUE(dec.timestamps(f2, 0, ts));
+    ASSERT_EQ(ts.size(), 5u);
+    EXPECT_GT(ts[0], 10.0);
+    EXPECT_NEAR(ts[4], 10.05, 1e-12);
+    EXPECT_NEAR(ts[1] - ts[0], 0.01, 1e-12);
+}
+
+TEST(FrameDecoder, PacketBurstStaysMonotonicUnderJitteredArrivals) {
+    FrameDecoder dec;
+    dec.setSignals({burst("Raw", kTimePacket, 0.0, 8, kNoTimeSignal)});
+
+    const double jitter[] = {0.0, 0.004, -0.003, 0.006, -0.002, 0.0, 0.005, -0.004};
+    std::vector<double> all;
+    for (int p = 0; p < 8; p++) {
+        FrameBuilder fb;
+        fb.addSignal(std::vector<double>(8, 1.0));
+        const FrameView& f = fb.build(0, 20.0 + p * 0.05 + jitter[p]);
+        dec.beginFrame(f);
+        std::vector<double> ts;
+        if (dec.timestamps(f, 0, ts)) {
+            all.insert(all.end(), ts.begin(), ts.end());
+        }
+    }
+
+    ASSERT_GT(all.size(), 8u);
+    for (size_t i = 1; i < all.size(); i++) {
+        EXPECT_GT(all[i], all[i - 1]) << "packets overlapped at " << i;
+    }
+}
+
+TEST(FrameDecoder, ResetForgetsPerSignalHistory) {
+    FrameDecoder dec;
+    dec.setSignals({burst("Raw", kTimePacket, 0.0, 4, kNoTimeSignal)});
+
+    FrameBuilder fb;
+    fb.addSignal({1.0, 2.0, 3.0, 4.0});
+    const FrameView& f = fb.build(0, 5.0);
+    dec.beginFrame(f);
+    std::vector<double> ts;
+    EXPECT_FALSE(dec.timestamps(f, 0, ts));
+
+    const FrameView& f2 = fb.build(0, 5.1);
+    dec.beginFrame(f2);
+    EXPECT_TRUE(dec.timestamps(f2, 0, ts));
+
+    dec.reset();
+    const FrameView& f3 = fb.build(0, 5.2);
+    dec.beginFrame(f3);
+    EXPECT_FALSE(dec.timestamps(f3, 0, ts))
+        << "after reset the next packet is again the first one";
+}

Client/udpscope/tests/PaneTreeTest.cpp

@@ -0,0 +1,230 @@
+#include "PaneTree.h"
+
+#include <gtest/gtest.h>
+
+using namespace udpscope;
+
+namespace {
+
+const Rect kScreen{0.0, 0.0, 1000.0, 600.0};
+
+std::vector<PaneTree::Placed> leavesOf(const PaneTree& tree, const Rect& area) {
+    std::vector<PaneTree::Placed>   leaves;
+    std::vector<PaneTree::Splitter> splitters;
+    tree.layout(area, leaves, splitters);
+    return leaves;
+}
+
+} /* namespace */
+
+TEST(PaneTree, StartsAsOneEmptyLeafFillingTheArea) {
+    PaneTree tree;
+    EXPECT_EQ(tree.leafCount(), 1u);
+
+    const auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 1u);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.w, 1000.0);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.h, 600.0);
+    EXPECT_TRUE(leaves[0].leaf->signals.empty());
+}
+
+TEST(PaneTree, SplittingIntoColumnsHalvesTheWidth) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+
+    const auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.w, 500.0);
+    EXPECT_DOUBLE_EQ(leaves[1].rect.w, 500.0);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.h, 600.0);
+    EXPECT_DOUBLE_EQ(leaves[1].rect.x, 500.0);
+}
+
+TEST(PaneTree, SplittingIntoRowsHalvesTheHeight) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Rows);
+
+    const auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.h, 300.0);
+    EXPECT_DOUBLE_EQ(leaves[1].rect.y, 300.0);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.w, 1000.0);
+}
+
+// The pane being split keeps its content; the new pane is the empty one.
+TEST(PaneTree, SplitKeepsTheOriginalContentInTheFirstChild) {
+    PaneTree tree;
+    tree.root()->signals.push_back(Assignment{"Voltage", Color{}, 1.5f, VScale{}});
+    tree.splitLeaf(tree.root(), Orient::Columns);
+
+    const auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+    ASSERT_EQ(leaves[0].leaf->signals.size(), 1u);
+    EXPECT_EQ(leaves[0].leaf->signals[0].signalName, "Voltage");
+    EXPECT_TRUE(leaves[1].leaf->signals.empty());
+}
+
+TEST(PaneTree, ClosingALeafGivesItsSpaceToTheSibling) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+    auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+    leaves[1].leaf->signals.push_back(Assignment{"Keep", Color{}, 1.5f, VScale{}});
+
+    tree.closeLeaf(leaves[0].leaf);
+
+    EXPECT_EQ(tree.leafCount(), 1u);
+    leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 1u);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.w, 1000.0);
+    ASSERT_EQ(leaves[0].leaf->signals.size(), 1u);
+    EXPECT_EQ(leaves[0].leaf->signals[0].signalName, "Keep");
+}
+
+TEST(PaneTree, RefusesToCloseTheLastLeaf) {
+    PaneTree tree;
+    tree.closeLeaf(tree.root());
+    EXPECT_EQ(tree.leafCount(), 1u);
+}
+
+// A pane in the middle of a 3x3 touches no window edge. It must still be
+// splittable, which is why handles are inset inside the pane rather than
+// keyed on the window border.
+TEST(PaneTree, AnInteriorPaneIsStillSplittable) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Rows);          // top / bottom
+    auto leaves = leavesOf(tree, kScreen);
+    tree.splitLeaf(leaves[1].leaf, Orient::Rows);       // 3 rows
+    leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 3u);
+
+    PaneNode* middle = leaves[1].leaf;
+    tree.splitLeaf(middle, Orient::Columns);
+    leaves = leavesOf(tree, kScreen);
+    tree.splitLeaf(leaves[2].leaf, Orient::Columns);
+
+    EXPECT_EQ(tree.leafCount(), 5u);
+}
+
+TEST(PaneTree, LayoutReportsOneSplitterPerSplitNode) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+    auto leaves = leavesOf(tree, kScreen);
+    tree.splitLeaf(leaves[0].leaf, Orient::Rows);
+
+    std::vector<PaneTree::Placed>   out;
+    std::vector<PaneTree::Splitter> splitters;
+    tree.layout(kScreen, out, splitters);
+
+    EXPECT_EQ(out.size(), 3u);
+    EXPECT_EQ(splitters.size(), 2u);
+}
+
+TEST(PaneTree, RatioSurvivesALayoutRoundTrip) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+    tree.setRatio(tree.root(), 0.25);
+
+    const auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+    EXPECT_DOUBLE_EQ(leaves[0].rect.w, 250.0);
+    EXPECT_DOUBLE_EQ(leaves[1].rect.w, 750.0);
+}
+
+TEST(PaneTree, RatioIsClampedSoNeitherPaneGoesBelowTheMinimum) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+    tree.setRatio(tree.root(), 0.001);
+
+    const auto leaves = leavesOf(tree, kScreen);
+    EXPECT_GE(leaves[0].rect.w, kMinPaneSize);
+    EXPECT_GE(leaves[1].rect.w, kMinPaneSize);
+}
+
+TEST(PaneTree, HitTestFindsTheSplitterBetweenTwoPanes) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+
+    std::vector<PaneTree::Placed>   leaves;
+    std::vector<PaneTree::Splitter> splitters;
+    tree.layout(kScreen, leaves, splitters);
+    ASSERT_EQ(splitters.size(), 1u);
+
+    const PaneTree::Splitter* hit = tree.hitTestSplitter(splitters, 500.0, 300.0);
+    ASSERT_NE(hit, nullptr);
+    EXPECT_EQ(hit->orient, Orient::Columns);
+
+    EXPECT_EQ(tree.hitTestSplitter(splitters, 100.0, 300.0), nullptr);
+}
+
+TEST(PaneTree, HitTestFindsInsetSplitHandlesAndTheCloseButton) {
+    const Rect pane{0.0, 0.0, 400.0, 300.0};
+
+    EXPECT_EQ(PaneTree::hitTestHandle(pane, 8.0, 150.0),  Handle::Left);
+    EXPECT_EQ(PaneTree::hitTestHandle(pane, 392.0, 150.0), Handle::Right);
+    EXPECT_EQ(PaneTree::hitTestHandle(pane, 200.0, 8.0),   Handle::Top);
+    EXPECT_EQ(PaneTree::hitTestHandle(pane, 200.0, 292.0), Handle::Bottom);
+    EXPECT_EQ(PaneTree::hitTestHandle(pane, 392.0, 8.0),   Handle::Close);
+    EXPECT_EQ(PaneTree::hitTestHandle(pane, 200.0, 150.0), Handle::None);
+}
+
+// Gap 1: closeLeaf only tested with first child closed; test closing the second child.
+TEST(PaneTree, ClosingTheSecondLeafPreservesTheFirstLeafContent) {
+    PaneTree tree;
+    tree.splitLeaf(tree.root(), Orient::Columns);
+    auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+
+    // Assign distinct signals to each leaf
+    leaves[0].leaf->signals.push_back(Assignment{"Signal_A", Color{}, 1.5f, VScale{}});
+    leaves[1].leaf->signals.push_back(Assignment{"Signal_B", Color{}, 1.5f, VScale{}});
+
+    // Close the second leaf; the first should survive with its content
+    tree.closeLeaf(leaves[1].leaf);
+
+    EXPECT_EQ(tree.leafCount(), 1u);
+    leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 1u);
+    ASSERT_EQ(leaves[0].leaf->signals.size(), 1u);
+    EXPECT_EQ(leaves[0].leaf->signals[0].signalName, "Signal_A");
+}
+
+// Gap 2: closeLeaf only tested at depth 1; test at depth 2 (deeper recursion in findParent).
+TEST(PaneTree, ClosingALeafAtDepth2PreservesOthersAndUpdatesCount) {
+    PaneTree tree;
+    // Build tree: split root (a, b), split b to get depth-2 leaf in the RIGHT subtree
+    tree.splitLeaf(tree.root(), Orient::Columns);  // depth 1: root splits into a, b
+    auto leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+
+    tree.splitLeaf(leaves[1].leaf, Orient::Rows);  // depth 2: b splits into b.a, b.b
+    leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 3u);
+
+    // Assign distinct signals to each of the three leaves
+    leaves[0].leaf->signals.push_back(Assignment{"Depth1_Left", Color{}, 1.5f, VScale{}});
+    leaves[1].leaf->signals.push_back(Assignment{"Depth2_TopRight", Color{}, 1.5f, VScale{}});
+    leaves[2].leaf->signals.push_back(Assignment{"Depth2_BottomRight", Color{}, 1.5f, VScale{}});
+
+    // Close the first depth-2 leaf (leaves[1], which is in the right subtree)
+    tree.closeLeaf(leaves[1].leaf);
+
+    EXPECT_EQ(tree.leafCount(), 2u);
+    leaves = leavesOf(tree, kScreen);
+    ASSERT_EQ(leaves.size(), 2u);
+
+    // Verify the surviving depth-2 leaf has its signal intact
+    bool found_left = false;
+    bool found_bottom_right = false;
+    for (const auto& leaf : leaves) {
+        ASSERT_EQ(leaf.leaf->signals.size(), 1u);
+        if (leaf.leaf->signals[0].signalName == "Depth1_Left") {
+            found_left = true;
+        }
+        if (leaf.leaf->signals[0].signalName == "Depth2_BottomRight") {
+            found_bottom_right = true;
+        }
+    }
+    EXPECT_TRUE(found_left);
+    EXPECT_TRUE(found_bottom_right);
+}

Client/udpscope/tests/TimeBaseTest.cpp

@@ -0,0 +1,117 @@
+#include "TimeBase.h"
+
+#include <gtest/gtest.h>
+
+using namespace udpscope;
+
+TEST(ClockOffset, MapsTheFirstReadingOntoWallClockExactly) {
+    ClockOffset off;
+    EXPECT_FALSE(off.valid());
+
+    const double wall = 1756291200.5;
+    EXPECT_DOUBLE_EQ(off.map(10.0, wall), wall);
+    EXPECT_TRUE(off.valid());
+}
+
+// Network delay jitters the arrival time. If the offset chased every packet
+// the whole trace would wobble, so it is latched and only corrected on real
+// drift.
+TEST(ClockOffset, HoldsTheOffsetThroughSmallArrivalJitter) {
+    ClockOffset off;
+    off.map(10.0, 1000.0);                      // offset = 990
+
+    // Arrival wanders either side of the prediction. wallSec is a local receive
+    // timestamp, so it only ever advances — jitter shows up as the gap growing
+    // and shrinking, never as the clock going backwards.
+    EXPECT_DOUBLE_EQ(off.map(11.0, 1001.02), 1001.0);   // +0.02 late
+    EXPECT_DOUBLE_EQ(off.map(12.0, 1001.97), 1002.0);   // -0.03 early
+}
+
+// The threshold has to be symmetric. A producer whose clock steps FORWARD (an
+// NTP correction on the producer's host, say) puts the prediction permanently
+// ahead of the wall clock — a one-sided "recalibrate only when wall is ahead"
+// test never fires for it, and the trace sits in the future for the rest of the
+// run.
+TEST(ClockOffset, RecalibratesWhenTheProducerClockJumpsForward) {
+    ClockOffset off;
+    off.map(10.0, 1000.0);                      // offset = 990
+
+    // Producer leaps 100 s ahead while only 1 s of wall time passes.
+    EXPECT_DOUBLE_EQ(off.map(111.0, 1001.0), 1001.0);
+}
+
+TEST(ClockOffset, RecalibratesWhenDriftExceedsTheThreshold) {
+    ClockOffset off;
+    off.map(10.0, 1000.0);                      // offset = 990
+
+    /* Producer clock jumped (restart, re-phase): 5 s of error is not jitter. */
+    const double mapped = off.map(11.0, 1006.0);
+    EXPECT_DOUBLE_EQ(mapped, 1006.0);
+}
+
+TEST(ClockOffset, ResetForgetsTheCalibration) {
+    ClockOffset off;
+    off.map(10.0, 1000.0);
+    off.reset();
+    EXPECT_FALSE(off.valid());
+    EXPECT_DOUBLE_EQ(off.map(50.0, 2000.0), 2000.0);
+}
+
+// The tick rate of the producer's high-resolution timer is not carried by the
+// protocol, and StreamHub's trick of using the local MARTe timer frequency only
+// works on the producer's own host. Recover it from the data instead.
+TEST(HrtRateFit, RecoversAKnownTickRate) {
+    HrtRateFit fit;
+    const double ticksPerSec = 2.5e9;
+
+    EXPECT_FALSE(fit.ready());
+    for (int i = 0; i < 64; i++) {
+        const double wall = 1000.0 + i * 0.01;
+        fit.add(static_cast<uint64_t>(wall * ticksPerSec), wall);
+    }
+
+    ASSERT_TRUE(fit.ready());
+    EXPECT_NEAR(fit.ticksPerSecond(), ticksPerSec, ticksPerSec * 1e-6);
+}
+
+TEST(HrtRateFit, IsNotReadyBeforeTheMinimumSampleCount) {
+    HrtRateFit fit;
+    for (size_t i = 0; i < HrtRateFit::kMinSamples - 1; i++) {
+        fit.add(static_cast<uint64_t>(i) * 1000000u, 1000.0 + i * 0.001);
+    }
+    EXPECT_FALSE(fit.ready());
+
+    fit.add(static_cast<uint64_t>(HrtRateFit::kMinSamples) * 1000000u,
+            1000.0 + HrtRateFit::kMinSamples * 0.001);
+    EXPECT_TRUE(fit.ready());
+}
+
+TEST(HrtRateFit, ToSecondsUsesTheFittedRate) {
+    HrtRateFit fit;
+    const double ticksPerSec = 1.0e9;
+    for (int i = 0; i < 64; i++) {
+        const double wall = 500.0 + i * 0.005;
+        fit.add(static_cast<uint64_t>(wall * ticksPerSec), wall);
+    }
+    ASSERT_TRUE(fit.ready());
+    EXPECT_NEAR(fit.toSeconds(2000000000ull), 2.0, 1e-4);
+}
+
+TEST(HrtRateFit, SurvivesAStalledClock) {
+    HrtRateFit fit;
+    for (int i = 0; i < 64; i++) {
+        fit.add(12345u, 1000.0 + i * 0.01);   /* hrt never advances */
+    }
+    /* A degenerate fit must not produce a rate that would divide by zero, so it
+     * must decline to be ready at all. Guarding this behind `if (fit.ready())`
+     * would make the test vacuous: the branch never runs and a fit that
+     * declared itself ready with a rate of 0 or NaN would pass unnoticed. */
+    EXPECT_FALSE(fit.ready());
+    EXPECT_DOUBLE_EQ(fit.ticksPerSecond(), 0.0);
+}
+
+TEST(TimeSignalScale, UsesNanosecondsForUint64AndMicrosecondsOtherwise) {
+    EXPECT_DOUBLE_EQ(TimeSignalScale(6 /* UDPS_T_UINT64 */), 1.0e-9);
+    EXPECT_DOUBLE_EQ(TimeSignalScale(9 /* UDPS_T_FLOAT64 */), 1.0e-6);
+    EXPECT_DOUBLE_EQ(TimeSignalScale(4 /* UDPS_T_UINT32 */), 1.0e-6);
+}

docs/superpowers/plans/2026-08-27-udpscope.md

@@ -128,6 +128,23 @@ TEST(MinMaxDecimate, PreservesTheExtremesOfEveryBucket) {
 // A ring whose timestamps are not monotonic breaks any later binary search by
 // time, so the pair emitted per bucket must be ordered by time, not by value.
 TEST(MinMaxDecimate, EmitsPointsInTimeOrder) {
+    // Two buckets of four. In the first the minimum comes before the maximum,
+    // in the second the order is reversed. An implementation that emitted
+    // (min, max) by value rather than by time passes on bucket 0 and fails on
+    // bucket 1, so this data exercises the swap that a monotonically growing
+    // ramp never triggers.
+    const double st[8] = {0, 1, 2, 3, 4, 5, 6, 7};
+    const double sv[8] = {-5, 0, 0, 9, 9, 0, 0, -5};
+    Series pair;
+    MinMaxDecimate(st, sv, 8, 4, pair);
+    ASSERT_EQ(pair.size(), 4u);
+    const double wantT[4] = {0, 3, 4, 7};
+    const double wantV[4] = {-5, 9, 9, -5};
+    for (size_t i = 0; i < 4; i++) {
+        EXPECT_EQ(pair.t[i], wantT[i]) << "time at " << i;
+        EXPECT_EQ(pair.v[i], wantV[i]) << "value at " << i;
+    }
+
     std::vector<double> t(400), v(400);
     for (size_t i = 0; i < t.size(); i++) {
         t[i] = static_cast<double>(i);
@@ -362,7 +379,11 @@ else()
     message(WARNING "Bundled Font Awesome missing — using ASCII icon fallbacks")
 endif()
 
-file(COPY ${FONT_DIR} DESTINATION ${CMAKE_BINARY_DIR}/resources)
+# Guarded: file(COPY) is a hard configure error on a missing source, which
+# would defeat the fallback the block above just chose.
+if(EXISTS ${FONT_DIR})
+    file(COPY ${FONT_DIR} DESTINATION ${CMAKE_BINARY_DIR}/resources)
+endif()
 
 # ── Core library: everything except main.cpp, so tests can link it ────────────
 set(CORE_SOURCES
@@ -1022,8 +1043,24 @@ TEST(ClockOffset, HoldsTheOffsetThroughSmallArrivalJitter) {
     ClockOffset off;
     off.map(10.0, 1000.0);                      // offset = 990
 
-    EXPECT_DOUBLE_EQ(off.map(11.0, 1001.02), 1001.0);
+    // Arrival wanders either side of the prediction. wallSec is a local receive
-    EXPECT_DOUBLE_EQ(off.map(12.0, 1000.97), 1002.0);
+    // timestamp, so it only ever advances — jitter shows up as the gap growing
+    // and shrinking, never as the clock going backwards.
+    EXPECT_DOUBLE_EQ(off.map(11.0, 1001.02), 1001.0);   // +0.02 late
+    EXPECT_DOUBLE_EQ(off.map(12.0, 1001.97), 1002.0);   // -0.03 early
+}
+
+// The threshold has to be symmetric. A producer whose clock steps FORWARD (an
+// NTP correction on the producer's host, say) puts the prediction permanently
+// ahead of the wall clock — a one-sided "recalibrate only when wall is ahead"
+// test never fires for it, and the trace sits in the future for the rest of the
+// run.
+TEST(ClockOffset, RecalibratesWhenTheProducerClockJumpsForward) {
+    ClockOffset off;
+    off.map(10.0, 1000.0);                      // offset = 990
+
+    // Producer leaps 100 s ahead while only 1 s of wall time passes.
+    EXPECT_DOUBLE_EQ(off.map(111.0, 1001.0), 1001.0);
 }
 
 TEST(ClockOffset, RecalibratesWhenDriftExceedsTheThreshold) {
@@ -1572,6 +1609,42 @@ TEST(FrameDecoder, AccumulatedScalarSurvivesBurstyDelivery) {
     }
 }
 
+// ADDED in Task 4 review. The counterweight to the test above: suppressing
+// arrival jitter by chaining bursts is only safe while the chain is CHECKED. On
+// UDP packets are lost, and an unchecked chain closes the hole silently and
+// dates every later sample early for the rest of the run.
+TEST(FrameDecoder, AccumulatedScalarResynchronisesAfterLostPackets) {
+    FrameDecoder dec;
+    SignalMeta m;
+    m.name         = "Acc";
+    m.typeCode     = 9;
+    m.numRows      = 1;
+    m.samplingRate = 1000.0;          /* 10 samples = 10 ms per packet */
+    dec.setSignals({m});
+
+    std::vector<double> ts;
+    for (int p = 0; p < 10; p++) {
+        FrameBuilder fb;
+        fb.addSignal(std::vector<double>(10, 1.0));
+        const FrameView& f = fb.build(0, 500.0 + p * 0.010, 10);
+        dec.beginFrame(f);
+        ASSERT_TRUE(dec.timestamps(f, 0, ts));
+    }
+    EXPECT_NEAR(ts[9], 500.090, 1e-9);
+
+    /* A full second of packets never arrives. The next one lands at 501.100. */
+    FrameBuilder fb;
+    fb.addSignal(std::vector<double>(10, 1.0));
+    const FrameView& f = fb.build(0, 501.100, 10);
+    dec.beginFrame(f);
+    ASSERT_TRUE(dec.timestamps(f, 0, ts));
+
+    /* Chaining blindly would put this burst at 500.091..500.100, as though no
+     * data were missing. */
+    EXPECT_NEAR(ts[0], 501.091, 1e-9);
+    EXPECT_NEAR(ts[9], 501.100, 1e-9);
+}
+
 TEST(FrameDecoder, AccumulatedScalarDerivesDtFromTheHrtGapWhenNoRateIsDeclared) {
     FrameDecoder dec;
     SignalMeta m;
@@ -1845,8 +1918,44 @@ bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
         return true;
     }
 
-    /* Rule 3: accumulated scalar, based on the producer's own hrt. */
+    /* Rule 3: accumulated scalar.
+     *
+     * AMENDED after Task 4 review. The version below originally sent EVERY
+     * accumulated scalar through the hrt fit, falling back to packetBurst until
+     * the fit was ready. That cannot work when a declared samplingRate is
+     * present: HrtRateFit needs 32 packets, bursty delivery can begin before
+     * that, and packetBurst then crams a 10 ms burst into a 50 us arrival gap —
+     * exactly the sawtooth this rule exists to prevent. Worse, HrtRateFit fits
+     * hrt against ARRIVAL time, so a burst episode corrupts the very rate the
+     * fallback is waiting on.
+     *
+     * With a declared rate none of that is needed: the intra-packet step is
+     * exact, and bursts are contiguous, so the next burst is PREDICTED at
+     * lastEmittedEnd + dt. The prediction must be checked, not trusted — a pure
+     * chain silently closes the hole left by a lost datagram and dates every
+     * later sample early for the rest of the run. So each packet compares the
+     * prediction against the arrival anchor and abandons it beyond
+     * kBurstResyncThresholdS. The hrt path below remains for samplingRate == 0. */
     if (d.numElements() == 1u && nElems > 1u) {
+        const double dtDeclared = (d.samplingRate > 0.0) ? (1.0 / d.samplingRate) : 0.0;
+        if (d.samplingRate > 0.0) {
+            const double arrivalAnchor =
+                wallNow - static_cast<double>(nElems - 1u) * dtDeclared;
+            double base = arrivalAnchor;
+            if (st.lastEmittedValid) {
+                const double predicted = st.lastEmittedEnd + dtDeclared;
+                if (std::fabs(predicted - arrivalAnchor) <= kBurstResyncThresholdS) {
+                    base = predicted;
+                }
+            }
+            tsOut.resize(nElems);
+            for (uint32_t e = 0; e < nElems; e++) {
+                tsOut[e] = base + static_cast<double>(e) * dtDeclared;
+            }
+            st.lastEmittedEnd   = tsOut[nElems - 1u];
+            st.lastEmittedValid = true;
+            return true;
+        }
         if (!hrtFit_.ready()) {
             return packetBurst(idx, nElems, wallNow, tsOut);
         }
@@ -1854,9 +1963,7 @@ bool FrameDecoder::timestamps(const FrameView& f, uint32_t idx,
         const double base   = st.offset.map(hrtSec, wallNow);
 
         double dt;
-        if (d.samplingRate > 0.0) {
+        if (st.lastAccValid && st.prevAccCount > 0u &&
-            dt = 1.0 / d.samplingRate;
-        } else if (st.lastAccValid && st.prevAccCount > 0u &&
             hrtSec > st.lastAccHrtSec) {
             /* The flushes carry contiguous RT cycles, so the gap divided by the
              * previous packet's sample count is exactly one cycle period. */
@@ -1908,7 +2015,7 @@ cd Client/udpscope && cmake --build build -j && ./build/udpscope_tests --gtest_f
 
 Expected: PASS, 9 tests.
 
-If `AccumulatedScalarSurvivesBurstyDelivery` fails on the first few samples, check that `beginFrame()` is being called before `timestamps()` — the hrt fit needs 32 packets before rule 3 engages, and the packets before that legitimately go through rule 4.
+If `AccumulatedScalarSurvivesBurstyDelivery` fails, do NOT reach for the hrt fit: with a declared `samplingRate` rule 3 never consults it, precisely because the fit is not ready for the first 32 packets and is itself corrupted by bursty arrivals. Check instead that `lastEmittedEnd`/`lastEmittedValid` are being updated on every emitted burst. The only test that may legitimately fall through to rule 4 early is `AccumulatedScalarDerivesDtFromTheHrtGapWhenNoRateIsDeclared`, whose arrivals are uniform, so `packetBurst` is accurate there.
 
 - [ ] **Step 8: Commit**
 
@@ -2899,7 +3006,19 @@ TEST(SignalStore, ConcurrentPushAndReadDoNotCrash) {
     }
     stop.store(true);
     writer.join();
-    SUCCEED();
+
+    /* Not just "it did not crash": the store must still be coherent after the
+       race. The window is 0.05 s at 1 MHz, so the ring spans at most
+       0.05 * kRingMargin seconds, and readLast was capped at 4096 points. */
+    double oldest = 0.0, newest = 0.0;
+    ASSERT_TRUE(s.span("a", oldest, newest));
+    EXPECT_GE(newest, oldest);
+    EXPECT_LE(newest - oldest, 0.05 * SignalStore::kRingMargin * 1.5);
+    EXPECT_LE(out.size(), 4096u);
+    EXPECT_EQ(out.t.size(), out.v.size());
+    for (size_t i = 1; i < out.size(); ++i) {
+        EXPECT_GE(out.t[i], out.t[i - 1]) << "timestamps went backwards at " << i;
+    }
 }
 ```
 
@@ -4138,7 +4257,7 @@ TEST(ReceiverLink, StopIsSafeWhenNeverStarted) {
     Receiver rx(store);
     rx.stop();
     EXPECT_FALSE(rx.running());
-    SUCCEED();
+    EXPECT_FALSE(rx.link().running);
 }
 ```
 
@@ -5138,10 +5257,6 @@ void App::drawMenuBar() {
         }
         ImGui::EndMenu();
     }
-    if (ImGui::BeginMenu("View")) {
-        ImGui::MenuItem("(cursors land in Task 13)", nullptr, false, false);
-        ImGui::EndMenu();
-    }
     if (ImGui::BeginMenu("Help")) {
         ImGui::MenuItem("UDPScope — direct UDPS oscilloscope", nullptr, false, false);
         ImGui::EndMenu();
@@ -5974,8 +6089,9 @@ In `Client/udpscope/App.h`, add `#include "PaneView.h"` and the members:
     double   xSpanSec_ = 1.0;   /**< live window width, Task 12 makes it settable */
 ```
 
-In `Client/udpscope/App.cpp`, make the signal list a drag source by replacing
+In `Client/udpscope/SignalList.cpp` — that is where Task 9 put
-the `ImGui::Selectable(m.name.c_str());` line with:
+`App::drawSignalList()`, not `App.cpp` — make the signal list a drag source by
+replacing the `ImGui::Selectable(m.name.c_str());` line with:
 
 ```cpp
         ImGui::Selectable(m.name.c_str());
@@ -6035,10 +6151,14 @@ set(CORE_SOURCES
 set(APP_SOURCES
     main.cpp
     App.cpp
+    SignalList.cpp
     PaneView.cpp
 )
 ```
 
+`SignalList.cpp` stays in the list — it holds `App::drawSignalList()` and
+dropping it is a link error, not a warning.
+
 `PaneView.cpp` needs ImGui headers, so it belongs to the executable, not the
 core library — that is what keeps `udpscope_tests` free of a GUI dependency.
 
@@ -6977,7 +7097,8 @@ and after `paneView_.drawTree(...)`:
     }
 ```
 
-Add the live control to the View menu in `drawMenuBar()`:
+There is no View menu yet — Task 9 built only File and Help. Add one to
+`drawMenuBar()`, between the File and Help blocks:
 
 ```cpp
     if (ImGui::BeginMenu("View")) {
@@ -9169,7 +9290,8 @@ TEST(PaneTree, CloneIsADeepCopy) {
 
 - [ ] **Step 8: Add the File menu and save on exit**
 
-In `App::drawMenuBar()`, before the View menu:
+In `App::drawMenuBar()`, **replace** the File menu block Task 9 wrote (the one
+whose only item is Quit) — do not add a second one:
 
 ```cpp
     if (ImGui::BeginMenu("File")) {