motion_scrubber.hpp

Go to the documentation of this file.

// motion_scrubber.hpp — Timeline scrubber that replays a .motion.jsonl
// fixture frame-by-frame against an inspector client.
//
// The scrubber is passive: it does not run animations live and does not
// advance a clock. It loads a recorded fixture into memory, exposes a
// playhead (frame index), and re-emits the prefix of events with
// `frame <= playhead` to a caller-supplied Sink each time the playhead
// moves. This is sufficient for design-review timeline scrubbing and CI
// artifact triage; live overlay drawing belongs to a separate layer.
//
// Inspector dispatch:
//   Motion.loadFixture { path }    → load events, reset playhead to 0
//   Motion.scrubTo     { frame }   → set playhead, re-emit prefix
//   Motion.play        {}          → mark playing, jump to max frame
//   Motion.pause       {}          → clear playing flag
//   Motion.snapshot    {}          → playhead + loaded state
//
// The scrubber is off by default — `loaded()` is false until
// `load_fixture()` succeeds. Wiring is analogous to MotionInspector:
// DomainHandler owns the instance and routes Motion.* requests to it
// when the method is a scrubber method.
 
#pragma once
 
#include <pulp/inspect/inspector_delivery.hpp>
#include <pulp/view/motion.hpp>
 
#include <cstdint>
#include <mutex>
#include <string>
#include <vector>
 
namespace pulp::inspect {
 
class MotionScrubber {
public:
    explicit MotionScrubber(InspectorEventSink event_sink = {});
    ~MotionScrubber();
 
    MotionScrubber(const MotionScrubber&) = delete;
    MotionScrubber& operator=(const MotionScrubber&) = delete;

    InspectorMessage handle(const InspectorMessage& req);

    static bool owns_method(const std::string& method);
 
    // ── Direct API (used by tests + advanced clients) ───────────────

    bool load_fixture(const std::string& path);

    std::size_t scrub_to(std::uint64_t frame);

    std::size_t scrub_to_bounded(std::uint64_t frame, std::size_t maximum_events,
                                 bool& truncated, std::function<bool()> continue_emission = {},
                                 bool* interrupted = nullptr);

    std::size_t play();
 
    std::size_t play_bounded(std::size_t maximum_events, bool& truncated,
                             std::function<bool()> continue_emission = {},
                             bool* interrupted = nullptr);

    void pause();

    int add_sink(view::motion::Sink sink);
    void remove_sink(int id);
 
    // ── Read-only accessors ─────────────────────────────────────────
 
    bool loaded() const;
    bool playing() const;
    std::uint64_t playhead_frame() const;
    std::size_t event_count() const;
    std::uint64_t max_frame() const;
    view::motion::FixtureHeader header() const;
 
private:
    InspectorEventSink event_sink_;
 
    mutable std::mutex mtx_;
    std::vector<view::motion::SampleEvent> events_;
    view::motion::FixtureHeader header_{};
    std::uint64_t playhead_frame_ = 0;
    std::uint64_t max_frame_ = 0;
    bool loaded_ = false;
    bool playing_ = false;
 
    struct SinkSlot {
        int id = 0;
        view::motion::Sink sink;
    };
    std::vector<SinkSlot> sinks_;
    int next_sink_id_ = 1;
 
    // Protocol handlers.
    InspectorMessage handle_load_fixture(const InspectorMessage& req);
    InspectorMessage handle_scrub_to(const InspectorMessage& req);
    InspectorMessage handle_play(const InspectorMessage& req);
    InspectorMessage handle_pause(const InspectorMessage& req);
 
    // Dispatch a snapshot of events to the given sinks + callback WITHOUT
    // holding mtx_. Callers must collect the snapshot under the lock and
    // then call this. Sinks are free to re-enter MotionScrubber methods.
    static std::size_t dispatch_snapshot(
        const std::vector<view::motion::SampleEvent>& events,
        const std::vector<SinkSlot>& sinks,
        const InspectorEventSink& event_sink,
        const std::function<bool()>& continue_emission = {}, bool* interrupted = nullptr);
};
 
} // namespace pulp::inspect