motion.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/view/geometry.hpp>
 
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <utility>
#include <vector>
 
namespace pulp::view {
 
class FrameClock;
class ScrollView;
class View;
 
namespace motion {
 
// ── Geometry taxonomy ────────────────────────────────────────────────
 
enum class GeometrySource {
    Layout,        
    Presentation,  
};
 
enum class GeometrySpace {
    ViewLocal,    
    ViewGlobal,   
    Window,       
    Screen,       
};
 
enum class GeometryProperty {
    MinX, MinY, MaxX, MaxY,
    MidX, MidY,
    Width, Height,
};
 
// ── Scroll taxonomy ──────────────────────────────────────────────────
//
// Properties readable from a `pulp::view::ScrollView` — content offset,
// visible (viewport) rect, content size, content insets, and the max
// scrollable extent on each axis. ScrollView does not currently expose
// per-edge content insets; the four Inset* properties always report 0.0
// and remain on the enum so callers can wire them once insets land
// without breaking the API surface.
enum class ScrollProperty {
    ContentOffsetX, ContentOffsetY,
    VisibleRectMinX, VisibleRectMinY, VisibleRectWidth, VisibleRectHeight,
    ContentSizeWidth, ContentSizeHeight,
    InsetTop, InsetBottom, InsetLeft, InsetRight,
    ScrollableMaxX, ScrollableMaxY,   // max(0, contentSize - viewport) per axis
};
 
// ── Trace options ────────────────────────────────────────────────────
 
struct TraceOptions {
    int fps = 15;
};
 
// ── Provenance envelope ───────────────────────────────────────────────
//
// Opaque metadata describing *where* a trace came from. Carried on
// TraceStarted (trace-level) and on burst Start events (burst-level).
// Animation surfaces (Tween / CSS / AnimatorSet / JS rAF / design-import)
// can fill this envelope to make offline traces explainable.
 
struct Provenance {
    std::string source_kind;   
    std::string source_id;     
    std::string source_file;   
    int source_line = 0;       
 
    bool is_set() const noexcept {
        return !source_kind.empty() || !source_id.empty() ||
               !source_file.empty() || source_line != 0;
    }
};
 
// ── Sample event ─────────────────────────────────────────────────────
//
// Per-tick or per-publish event in a motion stream. Schema v2 carries
// stable identifiers (trace_id / metric_id / burst_id) so fixtures can
// be compared by identity instead of position — reordered identical
// bursts no longer false-fail an `assert_matches`.
 
struct SampleEvent {
    enum class Kind {
        TraceStarted,  
        Baseline,      
        Sample,        
        Start,         
        End,           
        Input,         
    };
 
    Kind kind = Kind::Baseline;
    std::string view_name;
    std::string metric_name;
    double t_seconds = 0.0;                  
    std::uint64_t frame = 0;                 
    int precision = 3;
 
    // Stable identifiers (schema v2). Sampler-driven traces get a
    // positive `trace_id` from `register_trace`; publishes use 0 to
    // signal the publish channel. `metric_id` is the metric's index
    // within its trace (or 0 for publish). `burst_id` increments at
    // each Start within a given (trace_id, metric_id).
    int trace_id = 0;
    int metric_id = 0;
    int burst_id = 0;
 
    Provenance provenance;  
 
    std::vector<std::pair<std::string, double>> components;  
    std::vector<std::pair<std::string, double>> deltas;      
 
    // ── Input fields (populated only when `kind == Input`) ───────────
    //
    // `input_kind` is one of `"click"`, `"drag"`, `"hover"`. `view_id`
    // is the recorded target's `View::id()` (empty when the recorder
    // captured an event that didn't land on an id-bearing view). The
    // Root-space coordinates ride on `components`. Click and drag also
    // carry `button`, `modifiers`, `pointer_id`, `pointer_type`, and
    // `pressure`; hover remains coordinate-only:
    //   - click: `{ "button": ..., "modifiers": ..., "pointer_id": ...,
    //               "pointer_type": ..., "pressure": ..., "x": ..., "y": ... }`
    //   - drag : `{ "button": ..., "end_x": ..., "end_y": ...,
    //               "modifiers": ..., "pointer_id": ..., "pointer_type": ...,
    //               "pressure": ..., "start_x": ..., "start_y": ...,
    //               "steps": ... }`
    //   - hover: `{ "x": ..., "y": ... }`
    // (Sorted by name, same as every other event.) The optional name
    // ride along with `view_name` set to "input" by convention so
    // `format_line` and existing groupers don't trip on an empty view.
    std::string input_kind;
    std::string view_id;
};

std::string format_line(const SampleEvent& e);
 
// ── Publish channel ──────────────────────────────────────────────────
//
// `publish_value()` is the entry point for any code that wants to make
// its scalar / structured values observable without taking a
// FrameClock sampler subscription. Typical callers are animation
// primitives — a `Tween`, a CSS `TransitionSpec`, a JS rAF callback —
// that already advance once per frame; calling publish at the same
// tick site avoids the doubled-sampling cost.
//
// Routing:
//   - When `Coordinator::tracing_enabled()` is false, publish is a
//     no-op (cheap, branch-predictable; safe to leave in hot paths).
//   - When `Coordinator::firehose()` is true, the published value fans
//     out as a Sample event to every installed sink, with the same
//     epsilon / Start/End burst semantics as sampler-driven traces.
//   - When `firehose()` is false and no subscription is wired, publish
//     is also a no-op.
//
// The publish channel is the underlying primitive for trace subscribers
// and firehose-style diagnostics.
 
struct PublishOptions {
    int precision = 3;
    double epsilon = 0.0001;
    Provenance provenance;
};

void publish_value(std::string view_name,
                   std::string metric_name,
                   double value,
                   PublishOptions opts = {});

void publish_components(std::string view_name,
                        std::string metric_name,
                        std::vector<std::pair<std::string, double>> components,
                        PublishOptions opts = {});
 
// ── Ambient provenance ───────────────────────────────────────────────
//
// Some animation surfaces (JS rAF, design-import codegen) don't easily
// thread a `PublishOptions{ .provenance = ... }` through every call site.
// For those, the publish channel offers a process-wide "ambient"
// provenance slot — `set_ambient_provenance(p)` is sticky until cleared
// (or replaced). When a publish call carries an empty `opts.provenance`,
// the coordinator stamps the ambient provenance instead. When both are
// set, the explicit `opts.provenance` wins.
//
// Ambient state is intended for single-threaded scripted contexts (one
// JS engine per bridge). Tests should call `clear_ambient_provenance()`
// between scenarios so leftover state doesn't bleed across.
void set_ambient_provenance(Provenance p);
void clear_ambient_provenance();
Provenance current_ambient_provenance();
 
// ── Record / replay fixtures ─────────────────────────────────────────
//
// A fixture is the on-disk form of a motion stream — one JSONL event
// per line, preceded by a header line carrying the schema version. The
// format is deliberately stable so checked-in goldens survive long
// after the recording session.
//
// Layered intent:
//   - `make_fixture_sink(path)` is a Sink that writes events to disk
//     as they're emitted. Plug it into the Coordinator's sink set to
//     record everything an active trace produces.
//   - `replay_fixture(path, sink)` re-emits a fixture's events to any
//     sink without running the original UI. Lets analyzers /
//     assertions work offline on a captured run.
//   - `assert_matches(golden, captured, opts)` compares two fixtures
//     and returns a structured diff agents can act on.
//
// Fixture schema v2 header:
//   {"motion_fixture_version":2,
//    "policy":"full|reduced|off",
//    "duration_scale":1.0}
//
// `policy` / `duration_scale` are optional. When absent, the loader
// defaults `policy` to `"full"` and `duration_scale` to `1.0` —
// earlier v2 fixtures still load. When `make_fixture_sink` writes a fresh
// fixture it snapshots `MotionPreferences::current()` /
// `current_duration_scale()` at first event.
 
constexpr int kFixtureSchemaVersion = 2;
constexpr int kInvalidFixtureSchemaVersion = 0;

struct FixtureHeader {
    int version = kInvalidFixtureSchemaVersion;
    std::string policy = "full";
    double duration_scale = 1.0;
};
 
// (`make_fixture_sink` and `replay_fixture` are declared below
// alongside the other Sink helpers so the `using Sink = …` typedef is
// visible at their declaration site.)

std::vector<SampleEvent> load_fixture(const std::string& path);

FixtureHeader load_fixture_header(const std::string& path);

struct FixtureDiff {
    struct Item {
        std::string kind;      
        std::string view_name;
        std::string metric_name;
        std::string component_name;
        std::string detail;
        double observed = 0.0;
        double expected = 0.0;
    };
    std::vector<Item> differences;
    bool matches() const noexcept { return differences.empty(); }
};
 
struct FixtureMatchOptions {
    double component_epsilon = 0.05;
    double timing_epsilon_seconds = 0.05;
    bool require_same_event_count = true;
    bool require_matching_policy = true;
    double duration_scale_epsilon = 1e-6;
};
 
FixtureDiff assert_matches(const std::vector<SampleEvent>& golden,
                           const std::vector<SampleEvent>& captured,
                           FixtureMatchOptions opts = {});

FixtureDiff assert_matches(const FixtureHeader& golden_header,
                           const std::vector<SampleEvent>& golden,
                           const FixtureHeader& captured_header,
                           const std::vector<SampleEvent>& captured,
                           FixtureMatchOptions opts = {});
 
// ── Assertion helpers ────────────────────────────────────────────────
//
// Each helper operates on a flat sequence of scalars extracted from
// the captured events. Use `extract_scalar(events, view, metric, comp)`
// to pull the time-ordered series, then pass it to the assertion.
// Helpers favor explicit semantics over heuristics — `is_monotonic` is
// strictly monotonic (with epsilon), `settling_time_seconds` is "time
// from first change to final stable value", etc.

struct ScalarSample { double t = 0.0; double value = 0.0; };
std::vector<ScalarSample> extract_scalar(
    const std::vector<SampleEvent>& events,
    std::string_view view_name,
    std::string_view metric_name,
    std::string_view component_name = "value");

bool is_monotonic(const std::vector<ScalarSample>& samples,
                  double epsilon = 1e-6);

double settling_time_seconds(const std::vector<ScalarSample>& samples,
                             double epsilon = 1e-6);

double overshoot(const std::vector<ScalarSample>& samples,
                 double epsilon = 1e-6);

double start_delay_seconds(const std::vector<ScalarSample>& samples,
                           double epsilon = 1e-6);

double frame_jitter_seconds(const std::vector<ScalarSample>& samples);

double final_value(const std::vector<ScalarSample>& samples);

double local_step_outlier_ratio(
    const std::vector<ScalarSample>& samples,
    std::size_t window_radius = 3,
    double epsilon = 1e-9);
 
// ── Sinks ────────────────────────────────────────────────────────────
 
using Sink = std::function<void(const SampleEvent&)>;

Sink make_log_sink();

Sink make_buffer_sink(std::vector<SampleEvent>* buffer);

Sink make_fixture_sink(std::string path);

int replay_fixture(const std::string& path, const Sink& sink);
 
// ── Input recording / replay ─────────────────────────────────────────
//
// `View::simulate_click` / `simulate_drag` / `simulate_hover` can feed the same
// fixture stream that carries motion samples. Recording is opt-in: nothing
// changes about simulate_* until a caller installs a recorder, after which every
// simulate_* dispatch emits an `Input` `SampleEvent` to the Coordinator's sinks
// (so the already-installed `make_fixture_sink(path)` captures inputs alongside
// samples). Replay reads the fixture, walks the view tree by `id()` to reattach
// each input to a live target, and re-invokes the matching `View::simulate_*`.
// The motion fixture that emerges from the replay — when paired with the same
// animation primitives — matches the originally-recorded one.
//
// Layered intent:
//   - `make_input_recorder(path)` is a one-call companion to
//     `make_fixture_sink(path)`: it installs a fixture sink AND turns
//     on simulate_* recording, returning a handle whose destructor
//     turns recording back off. Off by default everywhere else.
//   - `replay_inputs(path, root_view, frame_clock)` reads the fixture
//     and re-dispatches each `Input` event by `view_id` against
//     `root_view`. The `frame_clock` is advanced between inputs to
//     reproduce the original timing (FrameClock-relative).

class InputRecorder {
public:
    InputRecorder() noexcept = default;
    InputRecorder(InputRecorder&&) noexcept;
    InputRecorder& operator=(InputRecorder&&) noexcept;
    InputRecorder(const InputRecorder&) = delete;
    InputRecorder& operator=(const InputRecorder&) = delete;
    ~InputRecorder();

    void stop();
 
    bool is_recording() const noexcept { return sink_id_ != 0; }
 
private:
    friend InputRecorder make_input_recorder(std::string path);
    explicit InputRecorder(int sink_id) noexcept : sink_id_(sink_id) {}
    int sink_id_ = 0;
};

InputRecorder make_input_recorder(std::string path);

int replay_inputs(const std::string& path,
                  View& root_view,
                  FrameClock& frame_clock);

void record_simulated_input(const std::string& input_kind,
                            const std::string& view_id,
                            std::vector<std::pair<std::string, double>> coords);

bool input_recording_enabled() noexcept;
 
// ── Forward declarations ─────────────────────────────────────────────
 
class Coordinator;
class TraceBuilder;
 
// ── Trace handle (RAII) ──────────────────────────────────────────────
 
class TraceHandle {
public:
    TraceHandle() noexcept = default;
    TraceHandle(TraceHandle&& other) noexcept;
    TraceHandle& operator=(TraceHandle&& other) noexcept;
    TraceHandle(const TraceHandle&) = delete;
    TraceHandle& operator=(const TraceHandle&) = delete;
    ~TraceHandle();

    void detach();
 
    bool is_attached() const noexcept { return coord_ != nullptr; }
    int id() const noexcept { return id_; }
 
private:
    friend class Coordinator;
    friend class TraceBuilder;
    TraceHandle(int id, Coordinator* coord) noexcept
        : id_(id), coord_(coord) {}
 
    int id_ = 0;
    Coordinator* coord_ = nullptr;
};
 
// ── Trace builder DSL ────────────────────────────────────────────────
 
class TraceBuilder {
public:
    using ValueSampler = std::function<double()>;
    using Component = std::pair<std::string, ValueSampler>;

    TraceBuilder& value(std::string name, ValueSampler sampler,
                        int precision = 3, double epsilon = 0.0001);

    TraceBuilder& multi(std::string name, std::vector<Component> components,
                        int precision = 3, double epsilon = 0.0001);

    TraceBuilder& geometry(std::string name,
                           pulp::view::View& target,
                           std::vector<GeometryProperty> props
                               = {GeometryProperty::MinX, GeometryProperty::MinY,
                                  GeometryProperty::Width, GeometryProperty::Height},
                           GeometrySpace space = GeometrySpace::Window,
                           GeometrySource source = GeometrySource::Layout,
                           int precision = 2, double epsilon = 0.1);

    TraceBuilder& scroll_geometry(
        std::string name,
        pulp::view::ScrollView& target,
        std::vector<ScrollProperty> props = {
            ScrollProperty::ContentOffsetX, ScrollProperty::ContentOffsetY,
            ScrollProperty::VisibleRectMinY, ScrollProperty::VisibleRectHeight,
        },
        int precision = 2, double epsilon = 0.1);

    TraceBuilder& with_provenance(Provenance p);

    TraceHandle attach();

    struct Spec;
 
private:
    friend class Coordinator;
    TraceBuilder(Coordinator* coord, std::string view_name, TraceOptions opts);
 
    std::shared_ptr<Spec> spec_;
    Coordinator* coord_ = nullptr;
};
 
// ── Coordinator ──────────────────────────────────────────────────────

class Coordinator {
public:
    static Coordinator& instance();

    void bind(pulp::view::FrameClock& clock);

    void unbind();
 
    bool is_bound() const noexcept;

    int add_sink(Sink sink);
    void remove_sink(int sink_id);
    void clear_sinks();

    int install_default_log_sink();

    void set_tracing_enabled(bool on);
    bool tracing_enabled() const noexcept;

    void set_firehose(bool on);
    bool firehose() const noexcept;

    TraceBuilder trace(std::string view_name, TraceOptions opts = {});

    void detach(int trace_id);

    void reset();
 
    std::size_t active_trace_count() const noexcept;

    std::size_t emitted_event_count() const noexcept;
 
    // ── Publish-channel internals ─────────────────────────────────────
    void publish_internal(std::string view_name,
                          std::string metric_name,
                          std::vector<std::pair<std::string, double>> components,
                          PublishOptions opts);
 
    // ── Ambient provenance internals ──────────────────────────────────
    void set_ambient_provenance_internal(Provenance p);
    Provenance current_ambient_provenance_internal() const;
 
    // ── Input recording dispatch ──────────────────────────────────────
    void dispatch_input_event(SampleEvent e);
 
private:
    Coordinator();
    ~Coordinator();
    Coordinator(const Coordinator&) = delete;
    Coordinator& operator=(const Coordinator&) = delete;
 
    void on_tick(float dt);
    int register_trace(std::shared_ptr<TraceBuilder::Spec> spec);
    friend class TraceBuilder;
 
    struct State;
    std::unique_ptr<State> state_;
};
 
} // namespace motion
} // namespace pulp::view