From 6715225c7aacc00225eacc65281040d306c16e24 Mon Sep 17 00:00:00 2001 From: Davide Faconti Date: Wed, 18 Nov 2026 23:17:38 +0100 Subject: [PATCH] feat(manifest): per_file_config_keys, the config members chosen for one file (1.2.0) A host pre-fills a file loader's dialog with the config its dialog saved last, with only "filepath" pointed at the new file. Members chosen for that one file (a time column picked by index from its header, a timestamp mode forced for its data) then apply silently to the next file: the wrong column becomes the time axis, or samples reorder. A data source now lists those members in its manifest as JSON Pointers: "per_file_config_keys": ["/time_column_index"]. decodeManifest validates them (an array of strings, each a pointer to a member) into PluginDescriptor::per_file_config_keys, empty when absent. A host drops them when the saved config names another file and keeps them when the same file is reopened. Declarative, like badge: no ABI or capability change, and a host built before 1.2.0 ignores the key, so a plugin declares it without raising min_sdk_required. The data-source guide states the pre-fill rule next to the other config rules and adds the manifest table row; VERSION and the changelog say 1.2.0. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01ME1hnPiFTsKdcGM3RDixoG --- .claude/skills/plotjuggler-plugin/SKILL.md | 4 +++- CHANGELOG.md | 13 +++++++++++ VERSION | 2 +- .../include/pj_base/data_source_protocol.h | 5 ++++ pj_plugins/docs/data-source-guide.md | 12 ++++++++++ .../pj_plugins/host/plugin_catalog.hpp | 8 +++++++ pj_plugins/src/plugin_catalog.cpp | 19 +++++++++++++++ pj_plugins/tests/plugin_catalog_test.cpp | 23 +++++++++++++++++++ 8 files changed, 84 insertions(+), 2 deletions(-) diff --git a/.claude/skills/plotjuggler-plugin/SKILL.md b/.claude/skills/plotjuggler-plugin/SKILL.md index 13155a8c..3a0cef5b 100644 --- a/.claude/skills/plotjuggler-plugin/SKILL.md +++ b/.claude/skills/plotjuggler-plugin/SKILL.md @@ -186,7 +186,9 @@ The host routes payloads by these case-sensitive names, and admits only the registered ones: `PJ::registeredParserEncodings()` in `pj_plugins/host/parser_claim_catalog.hpp` is the list. A parser claiming any other name is refused when its claims are admitted. -DataSource may add `"file_extensions": [".csv"]`. A Widget manifest needs +DataSource may add `"file_extensions": [".csv"]`, and `"per_file_config_keys": +["/time_column"]` for config members chosen for one file (see the data-source +guide's config rules). A Widget manifest needs `widgets` and `qt_modules` (see `references/widget.md`). `pj_emit_plugin_manifest` (the pre-0.25 name) still works but is deprecated. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a717c66..710c8227 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,19 @@ All notable changes to `plotjuggler_sdk` are recorded here. Versioning policy is in [`CLAUDE.md`](./CLAUDE.md) → "Release Versioning". +## [1.2.0] — Unreleased + +Host contract: unchanged (no floor impact). +Declarative, like `badge`: no ABI, vtable or capability change. A plugin declares the key in its +manifest without a new `min_sdk_required`; a host built before 1.2.0 ignores it. + +- Manifest: optional `per_file_config_keys`, an array of JSON Pointers (RFC 6901) to the config + members that describe one particular file, e.g. `["/time_column_index"]`. Decoded into + `PluginDescriptor::per_file_config_keys` (empty when absent); a non-array, a non-string entry or + an entry that is not a pointer to a member invalidates the manifest. A host that pre-fills the + loader dialog with the config saved for another file drops these members. +- Data-source guide: the pre-fill rule next to the other config rules, and the manifest table row. + ## [1.1.0] Host contract: extended: PJ_widget_host_vtable_t::notify_config_changed (floor 1.1.0). The slot is diff --git a/VERSION b/VERSION index 9084fa2f..26aaba0e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.1.0 +1.2.0 diff --git a/pj_base/include/pj_base/data_source_protocol.h b/pj_base/include/pj_base/data_source_protocol.h index 7a79dfb8..a2b552b1 100644 --- a/pj_base/include/pj_base/data_source_protocol.h +++ b/pj_base/include/pj_base/data_source_protocol.h @@ -572,6 +572,11 @@ typedef struct PJ_data_source_vtable_t { * FINITE_IMPORT SHOULD include this so the host * can build file-dialog filters without * instantiating the plugin. + * "per_file_config_keys" — array of JSON Pointers (RFC 6901) to the + * config members that describe one particular + * file. A host pre-filling the dialog with the + * config saved for another file drops them first. + * Since 1.2.0; older hosts ignore it. */ const char* manifest_json; /** [main-thread] Return capability bitmask (PJ_DATA_SOURCE_CAPABILITY_* flags). */ diff --git a/pj_plugins/docs/data-source-guide.md b/pj_plugins/docs/data-source-guide.md index 174f8c79..38b48f53 100644 --- a/pj_plugins/docs/data-source-guide.md +++ b/pj_plugins/docs/data-source-guide.md @@ -607,6 +607,17 @@ The config is a UTF-8 JSON object. The rules (normative text on - `saveConfig()` may return `"filepath"` and `"_parser_config"` (a file layout replays `saveConfig()` output, so that is how its parser config survives), never `"__pj_saved_filepath"` (the reference host strips it). +- The host pre-fills a file loader's dialog with the config its dialog saved + last, with `"filepath"` set to the new file. Members that only make sense for + the file they were chosen for (a time column picked by index from its header, + a mode forced for its data) would then apply to a different file. List them + in the manifest's `per_file_config_keys` as JSON Pointers + (`["/time_column_index"]`): the reference host drops them when the saved + `"filepath"` names another file (or none), and keeps them when the same file + is opened again. `loadConfig()` must accept the config without them and fall + back to its defaults. Layout replay and the Reload action apply the config + recorded for that file and drop nothing. A host older than 1.2.0 ignores the + key and pre-fills the whole config. ### Progress reporting @@ -702,6 +713,7 @@ it without instantiating the plugin. | `version` | string | yes | Semver version string. | | `description` | string | no | Short description of the plugin. | | `file_extensions` | string[] | no | File extensions this source handles, e.g. `[".csv", ".tsv"]`. Plugins declaring `kCapabilityFiniteImport` SHOULD include this so the host can build file-dialog filters. | +| `per_file_config_keys` | string[] | no | JSON Pointers to the config members that describe one particular file, e.g. `["/time_column_index"]` (1.2.0). A host pre-filling the dialog for a different file drops them; see the config rules above. A malformed pointer invalidates the manifest. Read as `PluginDescriptor::per_file_config_keys`. | `min_sdk_required`, `suggested_sdk_version` (with a `floor_test`) and the deprecated `min_plotjuggler_version` are optional compatibility keys common to diff --git a/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp b/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp index 12becaaa..13b838ff 100644 --- a/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp +++ b/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp @@ -77,6 +77,14 @@ struct PluginDescriptor { /// nothing) is host policy. At most 8 characters are advised; a host may truncate. /// @since 0.38.0 std::string badge; + /// Data sources: JSON Pointers (RFC 6901, e.g. "/time_column") to the members of the + /// plugin's config that describe one particular file, such as a column picked from its + /// header or a mode forced for its data; empty when undeclared. A host that pre-fills the + /// loader dialog with the config saved for another file drops these members first, so the + /// plugin falls back to its defaults; reopening the same file keeps them. Declarative: a + /// host built before 1.2.0 ignores it. + /// @since 1.2.0 + std::vector per_file_config_keys; /// Widget plugins only: the widget types the library offers (non-empty for kWidget). /// @since 0.39.0 std::vector widgets; diff --git a/pj_plugins/src/plugin_catalog.cpp b/pj_plugins/src/plugin_catalog.cpp index 55d27c2c..e66dd2c8 100644 --- a/pj_plugins/src/plugin_catalog.cpp +++ b/pj_plugins/src/plugin_catalog.cpp @@ -349,6 +349,24 @@ Expected decodeManifest( if (!capabilities) { return unexpected(capabilities.error()); } + auto per_file_config_keys = readStringArray(j, "per_file_config_keys"); + if (!per_file_config_keys) { + return unexpected(per_file_config_keys.error()); + } + for (const auto& key : *per_file_config_keys) { + // "" is the whole config, not a member a host could drop. + bool member_pointer = !key.empty(); + try { + (void)nlohmann::json::json_pointer(key); + } catch (const nlohmann::json::exception&) { + member_pointer = false; + } + if (!member_pointer) { + return unexpected( + fmt::format( + "plugin embedded manifest per_file_config_keys entry is not a JSON pointer to a member: \"{}\"", key)); + } + } d.description = *description; d.category = *category; @@ -358,6 +376,7 @@ Expected decodeManifest( d.badge = *badge; d.file_extensions = *file_extensions; d.capabilities = *capabilities; + d.per_file_config_keys = std::move(*per_file_config_keys); auto encoding = readStringArray(j, "encoding"); if (!encoding) { diff --git a/pj_plugins/tests/plugin_catalog_test.cpp b/pj_plugins/tests/plugin_catalog_test.cpp index e90db44f..fdbb5a14 100644 --- a/pj_plugins/tests/plugin_catalog_test.cpp +++ b/pj_plugins/tests/plugin_catalog_test.cpp @@ -407,6 +407,29 @@ TEST_F(PluginCatalogTest, BadgeRejectsNonString) { EXPECT_NE(descriptor.error().find("badge"), std::string::npos); } +TEST_F(PluginCatalogTest, PerFileConfigKeysDecodeAndDefaultToEmpty) { + auto declared = decodeManifest( + "static:csv", PluginFamily::kDataSource, + R"({"id":"csv","name":"CSV","version":"1.0.0","per_file_config_keys":["/time_column","/a~1b/c"]})"); + ASSERT_TRUE(declared.has_value()) << declared.error(); + EXPECT_EQ(declared->per_file_config_keys, (std::vector{"/time_column", "/a~1b/c"})); + + auto absent = + decodeManifest("static:csv", PluginFamily::kDataSource, R"({"id":"csv","name":"CSV","version":"1.0.0"})"); + ASSERT_TRUE(absent.has_value()) << absent.error(); + EXPECT_TRUE(absent->per_file_config_keys.empty()); +} + +TEST_F(PluginCatalogTest, PerFileConfigKeysRejectWhatIsNotAMemberPointer) { + for (const char* keys : {R"("time_column")", R"(["time_column"])", R"([""])", R"(["/a~2"])", R"([3])"}) { + const std::string manifest = + std::string(R"({"id":"csv","name":"CSV","version":"1.0.0","per_file_config_keys":)") + keys + "}"; + auto descriptor = decodeManifest("static:csv", PluginFamily::kDataSource, manifest); + ASSERT_FALSE(descriptor.has_value()) << keys; + EXPECT_NE(descriptor.error().find("per_file_config_keys"), std::string::npos) << descriptor.error(); + } +} + TEST_F(PluginCatalogTest, CapabilityTagsAreDeclarativeWithEmptyFallback) { auto editor = decodeManifest( "static:editor", PluginFamily::kToolbox,