Skip to content

feat(plugins): plugin manifest API + generic device import - #7

Open
wimpie70 wants to merge 5 commits into
tinkersoder:mainfrom
wimpie70:feat/plugin-manifest
Open

wimpie70 wants to merge 5 commits into
tinkersoder:mainfrom
wimpie70:feat/plugin-manifest

Conversation

@wimpie70

@wimpie70 wimpie70 commented Nov 4, 2026

Copy link
Copy Markdown

Implements the plugin-manifest direction discussed on #4 — integrations register {id, apiVersion, provides} via window.floorplanStudio.registerPlugin instead of carrying their domain knowledge in this repo.

What changed

src/plugins/ — the API surface

  • registerPlugin / unregisterPlugin: manifest is data + functions the editor calls; unknown provides keys ignored (independent versioning); same-id re-registration replaces, so an external module can supersede the bundled one
  • importProject(json, {mode:'merge'|'replace'}) — merges a project fragment in one undo step, replacing the direct IndexedDB pokes integrations needed before
  • projects.* (active/list/get/save/remove/open), callWS() for the active HA link, registry.* introspection + subscribe(cb)
  • Documented events (floorplan-studio:action, floorplan-studio:project-imported, floorplan-studio:plugins-changed) — bubbles+composed so they escape the card shadow root

src/import/ — generic device import (was src/ramses/)

  • plan.ts unchanged in behaviour, now operates on the neutral ImportDevice/DeviceTopology contract: devices carry icon/color/kind/suggested, plus actions/style/visibility passthrough (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)
  • DeviceImportModal lists registered sources, tries each source's parse on pasted input, generates select-buttons from the topology's own group tokens

src/ramses/ — bundled provider

  • provider.ts self-registers through the public API only — it imports nothing from editor internals, making it the reference implementation for a second integration author. Also reads parent_device_id alongside via_device (HA 2026.9 child devices).

Toolbar: RAMSES → Devices button + plugin action buttons emitting floorplan-studio:action with {pluginId, actionId, projectId, floorId, selection}.

Capability slots

deviceSources (fetch(ws)/parse(text)), actions (toolbar; marker-menu/room-menu reserved), 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 the importProject/projects surface — enough for a second integration author without reading the provider source
  • src/plugins/registry.test.ts covers registration, same-id replace, source dedupe and the action event payload
  • tsc --noEmit clean, 46 vitest tests pass, vite build and build:hacs clean

Test plan

  • Devices modal lists the bundled RAMSES source and imports as before (live + paste)
  • A third-party registerPlugin call adds a toolbar action; clicking it emits the documented CustomEvent
  • importProject merges a seed response in one undo step
  • Plugin css lands inside the card's shadow root in HACS mode

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.
@wimpie70

wimpie70 commented Nov 4, 2026

Copy link
Copy Markdown
Author

I'll keep it draft for a bit so i can test it properly first.

Copy link
Copy Markdown
Owner

Checked out this branch and ran the test plan against it (dev server + Playwright, plus the actual dist-hacs bundle for the shadow-root check).

Automated checks — all clean, matching the PR description:

  • tsc --noEmit — clean
  • vitest run — 46/46 pass
  • vite build — clean
  • vite build --config vite.hacs.config.ts — clean

Test plan checkboxes — all verified working:

  • Devices modal lists the bundled RAMSES source and imports via paste — pasted a ramses_extras/floorplan_helper/get_topology-shaped payload, got a correctly parsed device table (Controller + TRV, right device class/icon, right HA area). (Live WS path not exercised — no HA instance available here.)
  • A third-party registerPlugin() call adds a toolbar action; clicking it emits floorplan-studio:action with the documented payload shape ({pluginId, actionId, projectId, floorId, selection}) — confirmed via window.floorplanStudio.registerPlugin(...) in-browser.
  • importProject(seed, {mode:'merge'}) merges in one undo step — marker count went 0 → 1 on import, then a single Ctrl+Z brought it back to 0.
  • Plugin css lands inside the card's shadow root in HACS mode — loaded the real dist-hacs/floorplan-studio.js in a standalone harness; the injected <link data-fp-plugin-css> ends up under card.shadowRoot, not document.head.

No issues found. Looks ready whenever you're done with your own pass.


Generated by Claude Code

Willem added 2 commits November 5, 2026 10:19
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.
@wimpie70

wimpie70 commented Nov 5, 2026

Copy link
Copy Markdown
Author

I'm still working on some tweaks...

@wimpie70

wimpie70 commented Nov 5, 2026 •

Copy link
Copy Markdown
Author

Scope note — apologies for pushing ahead

While 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:

  • src/ramses/ removed — the PR's goal is "editor owns generic planning; integrations contribute domain data". Keeping ramses mapping logic in-tree undercut that, and it had already drifted from the canonical copy in ramses_extras. Studio now ships zero integration-specific code.
  • New bundled reference source src/examples/ha-devices.ts — reads the HA device + entity registries and groups devices by integration (entity platform). Unlike an integration-specific example it produces output on every HA instance, and it powers the integration coverage map below.
  • Plugin actions render in one grouped "Integrations ▾" overflow — flat toolbar buttons don't scale past 1–2 plugins. marker-menu/room-menu stay reserved for contextual actions.
  • haimport's liveWsCaller moved to ../ha/wsCaller (part of the de-ramses'd import path).

Stacked follow-up Issues & Draft PRs (in merge order after PR 7):

Order Issue Draft PR Summary & Decision Tackled
1 (PR A) #8 #9 Devices palette & preview gestures: moves Devices into the left sidebar (Entities | Devices | Layers), moves Import card into Projects (New from HA card…), and dispatches tap/hold/double gestures in Preview mode.
2 (PR B) #10 #11 roomSources capability: integrations return floor/room polygons only (provides.roomSources); Studio merges new rooms (planRoomSourceMerge) and runs its single client-side marker placement planner over them (Also import rooms from source in the Devices tab).
3 (PR E) #12 #13 Integration coverage map + spin animation: DeviceSourceProvider.coversIntegrations + Integrations (N) list in Devices tab badging plugin vs registry integrations; speed-proportional spin animation for fan/motor markers.
4 (PR F) #14 #15 Update card in HA: ExportModal scans Lovelace dashboards and writes exported ha-floorplan / picture-elements YAML back in place via lovelace/config/save on storage-mode dashboards.
Extras — wimpie70/ramses_extras#337 Canonical Ramses provider: shipped in ramses_extras and auto-registered as a Lovelace module resource (uses deviceSources, roomSources, coversIntegrations, stateRulePresets with spin, and marker gestures).

Feedback welcome on any piece of the stack!

Willem added 2 commits November 5, 2026 18:52
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants