Repository navigation
Conversation
window.floorplanStudio.registerPlugin({id, apiVersion, provides}) lets
third-party integrations contribute device sources, toolbar actions and
style defaults without integration-specific code in this repo:
- deviceSources: live fetch(ws)/offline parse providers shown in the
generic Devices modal (was the RAMSES modal). The bundled ramses
source registers through the same public API as the reference impl.
- actions: toolbar items emitting floorplan-studio:action CustomEvents
({pluginId, actionId, projectId, floorId, selection}) — documented,
bubbles+composed so they escape the card shadow root.
- iconMap / markerDefaults / stateRulePresets (role-bound): merged as
plugin < user opts < device hints; css injected once, re-attached to
the card's shadow root in HACS mode.
- apiVersion + ignored-unknown-provides-keys for independent versioning.
importProject() merges a project fragment in one undo step and
projects.* (active/list/get/save/remove/open) replace the direct
IndexedDB pokes integrations needed before. callWS() exposes the active
HA link; documented events: action / project-imported / plugins-changed.
Also: registry fallback now reads parent_device_id alongside via_device
(HA 2026.9 child devices), and devices carry suggested=false for
gateways instead of a hardcoded group check in the planner.
|
I'll keep it draft for a bit so i can test it properly first. |
|
Checked out this branch and ran the test plan against it (dev server + Playwright, plus the actual Automated checks — all clean, matching the PR description:
Test plan checkboxes — all verified working:
No issues found. Looks ready whenever you're done with your own pass. Generated by Claude Code |
The editor ships zero integration-specific code — the plugin API is the contract, and integrations own their mapping in their own repo. Ramses Extras ships its provider as a Lovelace resource from floorplan_helper (wimpie70/ramses_extras), registered under the same plugin id so it supersedes nothing and is versioned with the integration it talks to. src/examples/mqtt.ts is the new bundled reference implementation: entity-registry platform filter → device grouping → neutral ImportDevice shape. It is deliberately generic — change PLATFORM and it is a zwave/zigbee/ble source. haimport's WsCall/liveWsCaller imports move to ../ha/wsCaller where the helper actually lives (fetch.ts only re-exported it).
Flat per-action toolbar buttons do not scale once several integrations register — one "Integrations" dropdown now lists every toolbar-located plugin action grouped by plugin id. The location contract stays: 'toolbar' renders here, 'marker-menu'/'room-menu' remain reserved for contextual menus.
|
I'm still working on some tweaks... |
Scope note — apologies for pushing aheadWhile validating the plugin architecture on a live instance we found a few things that really belonged inside this PR rather than as follow-ups, so we folded them in. We also went ahead and built out the stacked follow-up PRs (each with its own issue) so everything is ready for you to review or cherry-pick whenever you have time. Happy to split or reshape anything — the changes are in separate branches/commits. What's now in this PR (PR 7), beyond the original manifest API + generic device import:
Stacked follow-up Issues & Draft PRs (in merge order after PR 7):
Feedback welcome on any piece of the stack! |
The example source now reads the device + entity registries — every HA instance has devices, so the reference implementation always has something to show, even where mqtt/zwave/etc. aren't configured. Devices are grouped by integration (entity platform), which doubles as the foundation for a "coverage map" showing which integrations have registered providers.
Implements the plugin-manifest direction discussed on #4 — integrations register
{id, apiVersion, provides}viawindow.floorplanStudio.registerPlugininstead of carrying their domain knowledge in this repo.What changed
src/plugins/— the API surfaceregisterPlugin/unregisterPlugin: manifest is data + functions the editor calls; unknownprovideskeys ignored (independent versioning); same-id re-registration replaces, so an external module can supersede the bundled oneimportProject(json, {mode:'merge'|'replace'})— merges a project fragment in one undo step, replacing the direct IndexedDB pokes integrations needed beforeprojects.*(active/list/get/save/remove/open),callWS()for the active HA link,registry.*introspection +subscribe(cb)floorplan-studio:action,floorplan-studio:project-imported,floorplan-studio:plugins-changed) —bubbles+composedso they escape the card shadow rootsrc/import/— generic device import (wassrc/ramses/)plan.tsunchanged in behaviour, now operates on the neutralImportDevice/DeviceTopologycontract: devices carryicon/color/kind/suggested, plusactions/style/visibilitypassthrough (e.g. a FAN's double-tap opening a custom card — users can still edit per-marker afterwards; re-import never rewrites a placed marker)DeviceImportModallists registered sources, tries each source'sparseon pasted input, generates select-buttons from the topology's own group tokenssrc/ramses/— bundled providerprovider.tsself-registers through the public API only — it imports nothing from editor internals, making it the reference implementation for a second integration author. Also readsparent_device_idalongsidevia_device(HA 2026.9 child devices).Toolbar: RAMSES → Devices button + plugin action buttons emitting
floorplan-studio:actionwith{pluginId, actionId, projectId, floorId, selection}.Capability slots
deviceSources(fetch(ws)/parse(text)),actions(toolbar;marker-menu/room-menureserved),iconMap,markerDefaults,stateRulePresets(role-bound rules appended to imported markers),css(injected once, re-attached to the card's shadow root in HACS mode).Docs & tests
USER_GUIDE→ Plugin API for integrations documents the manifest, the neutral topology contract, the event names/payloads and theimportProject/projectssurface — enough for a second integration author without reading the provider sourcesrc/plugins/registry.test.tscovers registration, same-id replace, source dedupe and the action event payloadtsc --noEmitclean, 46 vitest tests pass,vite buildandbuild:hacscleanTest plan
registerPlugincall adds a toolbar action; clicking it emits the documented CustomEventimportProjectmerges a seed response in one undo stepcsslands inside the card's shadow root in HACS mode