docs: Add Plotter Extensions API specification (proposed)#2773
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds comprehensive documentation for a new Plotter Extensions API: a ChangesPlotter Extensions API Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/develop/rest-api/proposed/README.md (1)
5-15: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winRe-run Prettier before merge.
CI is already failing on Markdown formatting in this file, so the new nav entry/table row needs a format pass before this lands.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/develop/rest-api/proposed/README.md` around lines 5 - 15, Re-run Prettier (or your project's Markdown formatter) on docs/develop/rest-api/proposed/README.md to fix the Markdown formatting CI error; specifically reformat the newly added table row/entry for "Plotter Extensions" (the link text plotter-extensions-api.md and the Endpoint `resources/plotterExtensions`) so the table columns and code inline formatting match the project's Markdown style, then save and push the formatted file.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/develop/rest-api/proposed/plotter-extensions-api.md`:
- Around line 502-553: The section currently mixes contract-level spec with
implementation guidance; extract the Express mounting recipe and route warnings
(the examples referencing app.registerResourceProvider with type
'plotterExtensions', the ASSET_BASE mounting example, the warnings about
'/plugins/*' and the 'signalk-webapp' keyword and registerWithRouter) plus the
planned filter-chain/future-roadmap notes into a separate how-to or reference
document, and replace this part of the spec with a concise, version-stable
contract statement describing only the required behaviors (e.g., that providers
must register the 'plotterExtensions' resource and that manifest URLs are
server-relative and must be publicly reachable), leaving implementation details
and roadmap material out of the spec.
- Around line 401-403: The phrase "see Connection establishment" is a stale
reference; update the text in the sentence that mentions connection-level
notifications to point to the correct existing section title "Connection" (or
remove the parenthetical entirely), so replace "see Connection establishment"
with "see Connection" (or delete the parenthetical) in the sentence handling
connection-level notifications (`bus.ready` and `bus.handshake`) so the document
no longer references a non-existent section.
---
Outside diff comments:
In `@docs/develop/rest-api/proposed/README.md`:
- Around line 5-15: Re-run Prettier (or your project's Markdown formatter) on
docs/develop/rest-api/proposed/README.md to fix the Markdown formatting CI
error; specifically reformat the newly added table row/entry for "Plotter
Extensions" (the link text plotter-extensions-api.md and the Endpoint
`resources/plotterExtensions`) so the table columns and code inline formatting
match the project's Markdown style, then save and push the formatted file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 2b07f88e-2436-441a-8fa9-bca038349853
📒 Files selected for processing (2)
docs/develop/rest-api/proposed/README.mddocs/develop/rest-api/proposed/plotter-extensions-api.md
joelkoz
force-pushed
the
plotterext-api-spec
branch
from
d9a2e8a to
bbb8260
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/develop/plugins/plotter_extension_provider_plugins.md`:
- Around line 70-87: The docs currently describe `app` as a plain Express
instance and show mounting with `app.use`, which is misleading because the
plugin startup surface exposes a server API with `registerResourceProvider`;
update the text to state that plugins receive the server API (not raw Express),
explain that you should call the server API's `registerResourceProvider` to
serve static assets, and keep the ASSET_BASE and PUBLIC_DIR identifiers as the
example asset path and directory while replacing the `app.use` reference with a
brief note pointing readers to use `registerResourceProvider` (or the server's
equivalent) to mount `${ASSET_BASE}` for the plugin manifest URLs.
In `@docs/develop/rest-api/proposed/README.md`:
- Around line 12-15: The index table in docs/develop/rest-api/proposed/README.md
omits "headless background runtimes" as a first-class contribution type; update
the Proposed API table so the Overview row for contributions includes headless
background runtimes (either by adding a new row labeled "Headless Background
Runtimes" or by appending "and headless background runtimes" to the Description
cell for the existing relevant entry such as _[`Plotter
Extensions`](plotter-extensions-api.md)_), and include a concise Endpoint value
or placeholder to match the other rows so the index reflects the spec and PR
summary.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 46334976-897f-467e-81af-2e2e5fa35df7
📒 Files selected for processing (4)
docs/develop/plugins/README.mddocs/develop/plugins/plotter_extension_provider_plugins.mddocs/develop/rest-api/proposed/README.mddocs/develop/rest-api/proposed/plotter-extensions-api.md
joelkoz
force-pushed
the
plotterext-api-spec
branch
from
bbb8260 to
88e8d8d
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/develop/rest-api/proposed/plotter-extensions-api.md (1)
412-414:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate the section reference to match the actual heading.
Line 413 references "the Connection section," but the section is titled "## Communication" (line 337). This is a stale reference that will confuse readers. As per coding guidelines, leftover crumbs from intermediate commits should be removed.
✏️ Suggested fix
- connection-level notifications `bus.ready` and `bus.handshake` (see the Connection section) are the only other host/extension events and are + connection-level notifications `bus.ready` and `bus.handshake` (see Communication) are the only other host/extension events and are🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/develop/rest-api/proposed/plotter-extensions-api.md` around lines 412 - 414, The reference "the Connection section" is stale and should be updated to the actual heading; change the mention in the sentence that lists connection-level notifications `bus.ready` and `bus.handshake` to reference "the Communication section" (or update to a matching anchor/title if you use anchors) so it correctly points readers to the "## Communication" section; locate the sentence containing `bus.ready` and `bus.handshake` and replace "the Connection section" with "the Communication section" (or the proper section anchor).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@docs/develop/rest-api/proposed/plotter-extensions-api.md`:
- Around line 412-414: The reference "the Connection section" is stale and
should be updated to the actual heading; change the mention in the sentence that
lists connection-level notifications `bus.ready` and `bus.handshake` to
reference "the Communication section" (or update to a matching anchor/title if
you use anchors) so it correctly points readers to the "## Communication"
section; locate the sentence containing `bus.ready` and `bus.handshake` and
replace "the Connection section" with "the Communication section" (or the proper
section anchor).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 98a2fad7-45e2-4ad0-a53e-8c098aa672a2
📒 Files selected for processing (4)
docs/develop/plugins/README.mddocs/develop/plugins/plotter_extension_provider_plugins.mddocs/develop/rest-api/proposed/README.mddocs/develop/rest-api/proposed/plotter-extensions-api.md
joelkoz
changed the title
joelkoz
force-pushed
the
plotterext-api-spec
branch
from
88e8d8d to
00bbd9e
Compare
|
I'll preface the following with these are my initial thoughts after a first cold read. There is quite a lot to digest here, but on first read it appears this is "instrument panel" on steroids. I get what this is trying to achieve and I think it has a lot of merit, so to ensure adoption (and make sure it doesn't end up being a FSK only kind of thing) some examples of what constitutes a good candidate use case and what may not be an appropriate use case would be beneficial. There are a lot of new terms to come to grips with and it wasn't abundantly clear to me the:
I think the manifest attributes deserve a more detailed description than they get, my measure is "can I build a working solution from the documentation" and I'm not sure I could. Am I correct in thinking that it also prescribes how the client should layout widgets.... why would we specify that? I will continue to review and will update accoringly as the penny drops a little further. |
|
@panaaj - Thanks for taking the time to engage. Yes, there is a lot to the spec (and the associated PRs), but I think it is well worth it. First and foremost - this is way more than just "complex iframes". Hidden in the lowest layer of the spec is a message broker like feature built on simple postMessage() that gives MQTT like publish/subscribe to all of the iframes and the "host" (aka Freeboard). While it is currently used as the transport layer for the API calls to the host layer, it enables both the ability for individual panels and widgets to communicate with each other, even if they come from different plugins. It also enables an event system where the host app announces events like "new route created" or "waypoint added", where the panels could respond. One of the iframe types is a "background" process that is headless, allowing it to listen and respond to such events. Expand this with a few more host API calls (like "create route", and "add waypoint to route" and you get the ability to implement stand alone functionality like a route optimizer as requested in SignalK/freeboard-sk#396 The other thing it does is is allow someone to create an entirely new type of resource and all of the supporting functionality around it. This all started with my desire to have a "dive site log" where I could mark various scuba spots and rate them by difficulty and depth. With the extension mechanism in place, I could make a single plugin that:
This would be a VERY niche plugin that some would find awesome, and others would find useless. Install it if you want. Un-install it if you don't like it. No special version of Freeboard required. With so many users now able to use AI agents, a well thought out system I think would be a huge unlock for the community without bloating the host (Freeboard). I actually am already about to submit a PR to @NearlCrews Binnacle project (just finishing it up now), so I can already prove it works well in two different chart plotters. That should overcome the "it only works in Freeboard". I can easily generate more documentation. I just need to find out where it should go (I've been asking around Discord, but there aren't a lot of pre-existing places to park it). This spec had more implementation examples, and Code Rabbit complained that the spec was not an appropriate place for it. To be frank, in the age of AI agents, I think it is a lot more effective to have a good To get a real feel for what it can do, spin up a dev server and apply my "unified" PR to it: joelkoz/freeboard-sk#2 . Or you can just clone that branch https://github.com/joelkoz/freeboard-sk/tree/plotter-ext-unified . Then install the following plugins from the app store:
and the already existing
The first three plugins serve as the reference code that Claude or Codex can take and run with to make a new one. I would love to get a larger discussion started re: what kinds of events and API calls would be the most valuable for the host to supply. To answer your questions directly:
Re: the layout: the spec calls for the HOST to specify where it wants to park its widgets. The "clients" are the widgets themselves. They have no control over where they can be positioned. In the Freeboard PR, the end user gets to pick from one of five areas (three of the four corners, and the center top and bottom). |
|
@panaaj - Based on our conversation above, I rewrote the user documentation to be a lot more informative. The second commit completely re-writes |
joelkoz
force-pushed
the
plotterext-api-spec
branch
from
743cde7 to
5b46775
Compare
|
I think this is much improved. I found it a lot clearer.. |
Add the `routes` capability throughout both documents: - Capability table entry and handshake example - 8 route.* host API methods (list/create/show/hide/delete/get/replace/save) - 4 route lifecycle/mutation events (visible/dirty/saved/hidden) - Background runtimes: add route.* to callable host API list - New "Live routes" narrative section covering the visible-set model, opaque routeId handles, saved/dirty state machine, editing semantics, and per-error codes - Provider guide: add routes capability to capability table, update good-candidates list, add "Example: editing a route" worked example Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2 participants
What & why
Chartplotter web apps (Freeboard-SK and others) cannot be extended with plugin-specific UI without forking the application, which fragments the ecosystem. This proposes a host-agnostic Plotter Extensions API: a
plotterExtensionsresource type through which any server plugin can offer optional widgets, panels, toolbar buttons, resource filters and background runtimes to chartplotter applications. Contributions are discovered at runtime from the resource provider and run sandboxed in iframes over a small JSON-RPC-over-postMessage bus, so no chartplotter needs to know about any specific plugin.This PR
Docs only — adds the draft specification under
docs/develop/rest-api/proposed/and registers it in the proposed-API index. No code or version changes.Reference implementations
signalk-plotterext-bussignalk-instrument-widgets,signalk-poi-searchOpening as a draft for early feedback on the approach before the host PR lands.
Overview
This PR adds documentation-only, host-agnostic specifications for a proposed Plotter Extensions API. The specification enables chartplotter server plugins to expose optional UI components—widgets, panels, toolbar buttons, resource filters, and background runtimes—to chartplotter web apps without requiring host-specific UI integration.
Changes
docs/develop/rest-api/proposed/README.mdresources/plotterExtensionsendpoint.docs/develop/rest-api/proposed/plotter-extensions-api.md(new)apiVersion1) and defines a newplotterExtensionsresource type, including runtime host discovery via/signalk/v2/api/resources/plotterExtensions.requires/optional), and contribution sections for widgets, panels, background runtimes, and toolbar buttons.ui.openConfigPanel/ui.toggleConfigPanel) and removal affordances.background.iframe, including allowed host API access and topic-driven triggering usingevents.subscribe, plus button publishing semantics.togglePanel,openPanel,sendMessage) and semantics including subscription-gated forwarding and topic-namespacing conventions.postMessageusing aplotterExt/1routing envelope (callswith request IDs andeventsas notifications), including readiness/handshake (bus.ready→bus.handshake) and call vs event semantics with subscription-gated forwarding of host-delivered events.events.subscribe/unsubscribe,state.get/set,signalk.subscribe/unsubscribe/put,units.get,resources.listplusresources.setFilter/clearFilter, and related map/panel controls, along with host-emitted events such asstate.changed,sk.<path>,filters.changed, andbus.*.state.*(instance vs extension), and unit preference vocabulary/behavior.plotterExtensionsresource registration and how they serve publicly readable (non-admin-gated) asset routes.callRuntime).signalk-plotterext-bus,signalk-instrument-widgets, andsignalk-poi-search(with a Freeboard-SK host reference noted as forthcoming).docs/develop/plugins/README.mdplotter_extension_provider_plugins.mdto the sidebar under the Plugins documentation section.docs/develop/plugins/plotter_extension_provider_plugins.md(new)plotterExtensionsresource.plotterExtensionsresource (with definedlistResources/getResourcebehavior and rejection ofsetResource/deleteResource), and/plugins/*and omittingsignalk-webappauto-mount behavior).signalk-plotterext-bus/extension, including example widget variants, config-panel behavior, a panel that performs resource queries and drives filters/map, and background runtime concepts.signalk.recommends.Scope
This PR remains documentation-only: it introduces no runtime code, no version updates, and no changes to the main server behavior, and it targets early feedback before host implementation.