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. 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).

The pj_filter_sdk INTERFACE target is declared inline in
pj_plugins/CMakeLists.txt (alongside dialog_protocol). It's a
header-only sub-module with one target, so a dedicated
filter_protocol/CMakeLists.txt was overhead — kept the layout to
match dialog_protocol/ for header organisation, but the build wiring
is now where it belongs.

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

@@ -17,6 +17,23 @@ target_link_libraries(pj_plugin_loader_detail PUBLIC pj_base)
 
 add_subdirectory(dialog_protocol)
 
+# Filter Editor transform contract (header-only) — plugins implement the 12
+# concrete strategies and self-register with the factory at load time. See
+# pj_plugins/filter_protocol/include/pj_plugins/sdk/filter_transform.hpp.
+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}/filter_protocol/include>
+  $<INSTALL_INTERFACE:include>
+)
+# Builtin strategies (in the plugin) use nlohmann/json for saveParams /
+# loadParams; propagate the dep so consumers get it transitively.
+target_link_libraries(pj_filter_sdk INTERFACE nlohmann_json::nlohmann_json)
+set_target_properties(pj_filter_sdk PROPERTIES EXPORT_NAME filter_sdk)
+add_library(plotjuggler_sdk::filter_sdk ALIAS pj_filter_sdk)
+install(DIRECTORY filter_protocol/include/ DESTINATION include)
+install(TARGETS pj_filter_sdk EXPORT plotjuggler_sdkTargets ARCHIVE DESTINATION lib LIBRARY DESTINATION lib INCLUDES DESTINATION include)
+
 # ---------------------------------------------------------------------------
 # pj_plugin_sdk — umbrella INTERFACE library that exposes the full plugin-author
 # SDK surface: C++ SDK headers (MessageParserPluginBase, ObjectIngestPolicy,
@@ -29,7 +46,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/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); \
+  }

pj_plugins/include/pj_plugins/host/plugin_catalog.hpp

@@ -49,6 +49,7 @@ struct PluginDescriptor {
   std::vector<std::string> encoding;         ///< for message parsers (one or more)
   std::vector<std::string> file_extensions;  ///< for data sources
   std::vector<std::string> capabilities;     ///< optional capability tags
+  std::vector<std::string> tags;  ///< manifest `tags` — free-form labels (category, role flags like "plot_action", …)
 };
 
 /// Diagnostic for a candidate DSO that could not produce a valid descriptor.

pj_plugins/include/pj_plugins/host/plugin_runtime_catalog.hpp

@@ -56,6 +56,7 @@ struct RuntimeToolboxPlugin {
   std::string id;
   std::string version;
   uint64_t capabilities = 0;
+  std::vector<std::string> tags;  ///< from manifest `tags` (e.g. "plot_action" — host routes by role)
   std::filesystem::file_time_type loaded_mtime;
 };
 

pj_plugins/src/plugin_catalog.cpp

@@ -252,11 +252,16 @@ Expected<PluginDescriptor> decodeManifest(
   if (!capabilities) {
     return unexpected(capabilities.error());
   }
+  auto tags = readStringArray(j, "tags");
+  if (!tags) {
+    return unexpected(tags.error());
+  }
 
   d.description = *description;
   d.category = *category;
   d.file_extensions = *file_extensions;
   d.capabilities = *capabilities;
+  d.tags = *tags;
 
   auto encoding = readStringArray(j, "encoding");
   if (!encoding) {

pj_plugins/src/plugin_runtime_catalog.cpp

@@ -247,6 +247,7 @@ bool PluginRuntimeCatalog::loadAndRegisterToolbox(const PluginDescriptor& descri
   loaded.name = descriptor.name;
   loaded.version = descriptor.version;
   loaded.capabilities = loaded.library.createHandle().capabilities();
+  loaded.tags = descriptor.tags;
 
   // Same fail-fast contract as DataSource above: kToolboxCapabilityHasDialog
   // requires an exported dialog vtable.