feat(filter_protocol): FilterTransform SDK contract + surface manifest tags

Add pj_plugins/filter_protocol/ — a header-only sub-module exposing
the Strategy contract for Filter Editor transforms. The SDK ships
only the abstract interface + registry; plugins provide the concrete
strategies and register them with the factory at load time.

Headers:

  - pj_plugins/sdk/filter_transform.hpp — abstract
    PJ::sdk::FilterTransform. Two streaming surfaces: calculateNextPoint
    (SISO, PJ3 mirror) and appendTail (chunked; default loops
    calculateNextPoint; override per-transform when running state
    makes it O(Δsamples)). Plus saveParams / loadParams JSON, and
    clone() for host hand-off across the plugin DSO boundary.

  - pj_plugins/sdk/filter_transform_factory.hpp — registry singleton,
    stable registration order, plus PJ_REGISTER_FILTER_TRANSFORM macro
    for auto-register at static init.

Lift PJ::sdk::Point2 to its own header:

  - pj_base/point2.hpp — generic 2D vocab type (double x, double y).
    Was defined inside image_annotations.hpp; promote so the Filter
    Editor transform contract can reuse it without an artificial
    coupling to image annotations. image_annotations.hpp now just
    includes the new header.

Surface manifest `tags`:

  - PluginDescriptor / RuntimeToolboxPlugin gain a `tags` field,
    parsed from the manifest's `tags` array (free-form labels:
    category, role flags like "plot_action", …). Lets the host route
    a generic action — e.g. the plot's right-click "Apply Filter…"
    slot — to whichever installed toolbox declares the matching tag,
    instead of hardcoding a plugin id in the host. Empty for plugins
    whose manifest omits the array (backward compatible).

Wires pj_filter_sdk into the plugin SDK umbrella so plugin authors
get the contract transitively from plotjuggler_sdk::plugin_sdk.

Additive surface — no existing header / struct / ABI changes
(Point2's struct definition + ABI layout are unchanged; only its
file location moved). Required release level when merged: MINOR.
Version bump kept out of this PR for release coordination.

Author: pabloinigoblasco

pj_base/include/pj_base/builtin/image_annotations.hpp

@@ -19,6 +19,7 @@
 #include <string>
 #include <vector>
 
+#include "pj_base/point2.hpp"
 #include "pj_base/types.hpp"
 
 namespace PJ {
@@ -32,12 +33,8 @@ enum class AnnotationTopology : uint8_t {
   kLineLoop,   ///< Like LineStrip but closes back to the first point. 4-point loop = rectangle.
 };
 
-/// 2D point in image-pixel coordinates (origin top-left).
-struct Point2 {
-  double x = 0.0;
-  double y = 0.0;
-  bool operator==(const Point2&) const = default;
-};
+// `Point2` lives in pj_base/point2.hpp (generic 2D vocab type). In this header
+// it's used in image-pixel coordinates (origin top-left).
 
 /// 8-bit per-channel RGBA color. a=0 means transparent / disabled.
 struct ColorRGBA {

pj_base/include/pj_base/point2.hpp

@@ -0,0 +1,18 @@
+// Copyright 2026 Davide Faconti
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+// Plain (x, y) 2D point. Generic double-precision vocab type — used by image
+// annotations (pixel coordinates), Filter Editor transforms (time/value
+// samples), and any other 2D context where a tagged shape would be overkill.
+// The semantic of x / y is owned by the caller.
+
+namespace PJ::sdk {
+
+struct Point2 {
+  double x = 0.0;
+  double y = 0.0;
+  bool operator==(const Point2&) const = default;
+};
+
+}  // namespace PJ::sdk

pj_plugins/CMakeLists.txt

@@ -16,6 +16,7 @@ set_target_properties(pj_plugin_loader_detail PROPERTIES
 target_link_libraries(pj_plugin_loader_detail PUBLIC pj_base)
 
 add_subdirectory(dialog_protocol)
+add_subdirectory(filter_protocol)
 
 # ---------------------------------------------------------------------------
 # pj_plugin_sdk — umbrella INTERFACE library that exposes the full plugin-author
@@ -29,7 +30,7 @@ target_include_directories(pj_plugin_sdk INTERFACE
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
   $<INSTALL_INTERFACE:include>
 )
-target_link_libraries(pj_plugin_sdk INTERFACE pj_base pj_dialog_sdk)
+target_link_libraries(pj_plugin_sdk INTERFACE pj_base pj_dialog_sdk pj_filter_sdk)
 set_target_properties(pj_plugin_sdk PROPERTIES EXPORT_NAME plugin_sdk)
 add_library(plotjuggler_sdk::plugin_sdk ALIAS pj_plugin_sdk)
 

pj_plugins/filter_protocol/CMakeLists.txt

@@ -0,0 +1,45 @@
+cmake_minimum_required(VERSION 3.20)
+project(pj_filter_protocol LANGUAGES CXX)
+
+# --- Filter Transform contract (SDK side) ---
+#
+# Header-only interface library. The plugin and the host both consume this
+# contract — there is no separate "host" target because everything lives in the
+# transform classes themselves (the host just calls FilterTransform::appendTail
+# / clone / saveParams via the abstract base).
+#
+# Pure C++20, no Qt. Concrete builtin transforms live under
+# include/pj_plugins/sdk/builtin_transforms/*.hpp and self-register at static
+# init time.
+
+find_package(nlohmann_json REQUIRED)
+
+add_library(pj_filter_sdk INTERFACE)
+target_compile_features(pj_filter_sdk INTERFACE cxx_std_20)
+target_include_directories(pj_filter_sdk INTERFACE
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>
+)
+# The contract surface (filter_transform.hpp + factory) does not need
+# nlohmann/json. The builtin transforms do (for saveParams / loadParams JSON),
+# so we propagate the dependency at the interface so consumers get it.
+target_link_libraries(pj_filter_sdk INTERFACE nlohmann_json::nlohmann_json)
+set_target_properties(pj_filter_sdk PROPERTIES EXPORT_NAME filter_sdk)
+
+# Public alias used by downstream consumers (plugin, PJ4 plotting host).
+add_library(plotjuggler_sdk::filter_sdk ALIAS pj_filter_sdk)
+
+# No tests at the SDK level: this module only ships the abstract contract +
+# factory registry. Concrete FilterTransform implementations — and the
+# bit-identity tests guarding their math — live with the plugins that provide
+# them (e.g. pj-official-plugins/toolbox_filter_editor).
+
+# --- Install ---
+install(DIRECTORY include/ DESTINATION include)
+
+install(TARGETS pj_filter_sdk
+  EXPORT plotjuggler_sdkTargets
+  ARCHIVE DESTINATION lib
+  LIBRARY DESTINATION lib
+  INCLUDES DESTINATION include
+)

pj_plugins/filter_protocol/include/pj_plugins/sdk/filter_transform.hpp

@@ -0,0 +1,78 @@
+// Copyright 2026 Davide Faconti
+// SPDX-License-Identifier: MPL-2.0
+#pragma once
+
+// Filter Editor transform contract. Plugins provide the concrete strategies;
+// the host consumes them by id through FilterTransformFactory.
+
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "pj_base/point2.hpp"
+
+namespace PJ::sdk {
+
+/// Strategy interface for a Filter Editor transform.
+///
+/// Two streaming surfaces:
+///  - `calculateNextPoint` — SISO, one input -> at most one output (PJ3 mirror).
+///  - `appendTail` — process a chunk; default loops `calculateNextPoint`. Override
+///    when running state (sliding sum, deque) makes it O(Δsamples) per call.
+///
+/// `clone()` is the host hand-off across the plugin DSO boundary.
+class FilterTransform {
+ public:
+  virtual ~FilterTransform() = default;
+
+  // Catalog identity used in saveConfig JSON, the factory registry, and the
+  // legend.
+  [[nodiscard]] virtual const char* id() const = 0;
+  [[nodiscard]] virtual const char* label() const = 0;
+  [[nodiscard]] virtual const char* bracketLabel() const = 0;
+
+  // True if the transform can extend its output as new samples arrive.
+  [[nodiscard]] virtual bool isStreamSafe() const = 0;
+
+  /// Drop accumulated state. Must be called before the first `calculateNextPoint`
+  /// after a series replace / clear.
+  virtual void reset() = 0;
+
+  /// One input -> optional output. Inputs MUST arrive in x-ascending order.
+  /// nullopt suppresses the output (e.g. Derivative drops the first sample).
+  [[nodiscard]] virtual std::optional<Point2> calculateNextPoint(const Point2& in) = 0;
+
+  /// Process the tail of points since the previous call. Default loops
+  /// `calculateNextPoint`; override per-transform when O(Δsamples) is possible.
+  virtual void appendTail(const std::vector<Point2>& new_raw, std::vector<Point2>& out) {
+    out.reserve(out.size() + new_raw.size());
+    for (const auto& p : new_raw) {
+      if (auto r = calculateNextPoint(p); r) {
+        out.push_back(*r);
+      }
+    }
+  }
+
+  /// Run from scratch over a whole series. Default: reset + appendTail.
+  virtual std::vector<Point2> applyBatch(const std::vector<Point2>& input) {
+    reset();
+    std::vector<Point2> out;
+    out.reserve(input.size());
+    appendTail(input, out);
+    return out;
+  }
+
+  /// JSON for the parameter set this transform owns (not the source binding).
+  [[nodiscard]] virtual std::string saveParams() const {
+    return "{}";
+  }
+  virtual void loadParams(const std::string& /*json_str*/) {}
+
+  /// Deep copy. The host calls this so the kept instance is independent of the
+  /// plugin DSO (the cloned vtable lives in the plugin's code, which stays
+  /// loaded for the app session).
+  [[nodiscard]] virtual std::unique_ptr<FilterTransform> clone() const = 0;
+};
+
+}  // namespace PJ::sdk

pj_plugins/filter_protocol/include/pj_plugins/sdk/filter_transform_factory.hpp

@@ -0,0 +1,78 @@
+// Copyright 2026 Davide Faconti
+// SPDX-License-Identifier: MPL-2.0
+#pragma once
+
+// Registry singleton for FilterTransform implementations. Plugins register
+// their concrete classes at load time; the host looks them up by id. Order
+// of registration is preserved (mirrors PJ3's dropdown order).
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+#include "pj_plugins/sdk/filter_transform.hpp"
+
+namespace PJ::sdk {
+
+class FilterTransformFactory {
+ public:
+  using CreateFn = std::function<std::unique_ptr<FilterTransform>()>;
+
+  [[nodiscard]] static FilterTransformFactory& instance() {
+    static FilterTransformFactory inst;
+    return inst;
+  }
+
+  /// Re-registering an existing `id` replaces the previous factory entry.
+  void registerTransform(const char* id, CreateFn fn) {
+    for (auto& e : entries_) {
+      if (e.id == id) {
+        e.fn = std::move(fn);
+        return;
+      }
+    }
+    entries_.push_back({id, std::move(fn)});
+  }
+
+  [[nodiscard]] std::vector<std::string> registeredIds() const {
+    std::vector<std::string> ids;
+    ids.reserve(entries_.size());
+    for (const auto& e : entries_) {
+      ids.push_back(e.id);
+    }
+    return ids;
+  }
+
+  /// Returns nullptr if `id` is not registered.
+  [[nodiscard]] std::unique_ptr<FilterTransform> create(std::string_view id) const {
+    for (const auto& e : entries_) {
+      if (e.id == id) {
+        return e.fn();
+      }
+    }
+    return nullptr;
+  }
+
+ private:
+  struct Entry {
+    std::string id;
+    CreateFn fn;
+  };
+  std::vector<Entry> entries_;
+};
+
+}  // namespace PJ::sdk
+
+/// Self-register `Class` at static-init. `Class{}` must be default-constructible
+/// and its `id()` must be unique.
+#define PJ_REGISTER_FILTER_TRANSFORM(Class)                                                                    \
+  namespace {                                                                                                  \
+  [[maybe_unused]] const bool _pj_register_##Class = ([] {                                                   \
+    PJ::sdk::FilterTransformFactory::instance().registerTransform(                                           \
+        (Class){}.id(), [] { return std::unique_ptr<PJ::sdk::FilterTransform>(new (Class)()); });            \
+    return true;                                                                                             \
+  }(), true); \
+  }