homebridge-plugin-utils 2.0.0 → 2.2.0

package/dist/ui/webUi-featureOptions.mjs

@@ -4,10 +4,10 @@
  */
 "use strict";
 
+import { delay, errorMessage, toastError } from "./webUi-featureOptions/utils.mjs";
 import { initialState, reducer } from "./webUi-featureOptions/state.mjs";
 import { FeatureOptionsStore } from "./webUi-featureOptions/store.mjs";
 import { buildCatalogIndex } from "./featureOptions.js";
-import { delay } from "./webUi-featureOptions/utils.mjs";
 import { mountConnectionErrorView } from "./webUi-featureOptions/views/connectionError.mjs";
 import { mountDeviceInfoView } from "./webUi-featureOptions/views/deviceInfo.mjs";
 import { mountHeaderView } from "./webUi-featureOptions/views/header.mjs";
@@ -44,10 +44,19 @@ const FLUSH_TEARDOWN_TIMEOUT_MS = 2000;
  * @property {string} serialNumber - The unique serial number of the controller.
  */
 
+/**
+ * The resolved shape of a `getDevices` hook: the single contract every device fetch crosses. It carries the device list and the connection outcome together, so a
+ * failure travels back with the response it belongs to rather than through a separate side-channel a concurrent probe could rewrite.
+ *
+ * @typedef {Object} DeviceListResult
+ * @property {Object[]} devices - The devices for the requested controller; empty when the probe failed or when the controller legitimately has none.
+ * @property {string} error - The user-facing connection-failure message: empty when the fetch succeeded, the failure text when the fetch failed and `devices` is empty.
+ */
+
 /**
  * @typedef {Object} FeatureOptionsConfig
  * @property {Function} [getControllers] - Handler to retrieve available controllers.
- * @property {Function} [getDevices] - Handler to retrieve devices for a controller.
+ * @property {(controller: (Controller|null)) => Promise<DeviceListResult>} [getDevices] - Handler resolving a controller's {@link DeviceListResult}.
  * @property {Function} [infoPanel] - Handler to display device information.
  * @property {Object} [sidebar] - Sidebar configuration options.
  * @property {string} [sidebar.controllerLabel="Controllers"] - Label for the controllers section.
@@ -68,7 +77,8 @@ const FLUSH_TEARDOWN_TIMEOUT_MS = 2000;
  *
  * Public API: constructor takes the same options shape, `show()` reveals the UI, `hide()` is the navigate-away (it flushes any pending edit, then tears down),
  * `cleanup()` is immediate destructive teardown (may drop an unsaved debounced edit; for forced/synchronous disposal), `getHomebridgeDevices()` is the default
- * device source. Plugins consuming the library see no change to this surface.
+ * device source. The device-list contract is rich: a `getDevices` hook resolves a {@link DeviceListResult} carrying both the device array and the connection
+ * outcome, and `getHomebridgeDevices` resolves the same shape.
  *
  * Internally, the store owns per-show state, effects own side effects, views own DOM, and the orchestrator is the lifecycle seam that boots and tears them down. The one
  * piece of state it keeps itself is #initialOptions - the revert-to-saved snapshot - which must outlive the store's per-show() reset; all else flows through the store.
@@ -79,7 +89,7 @@ const FLUSH_TEARDOWN_TIMEOUT_MS = 2000;
  * const session = await PluginConfigSession.open({ host: homebridge, name: "My Plugin" });
  * const featureOptionsUI = new webUiFeatureOptions({
  *   getControllers: ({ config }) => myPlugin.controllersFrom(config),
- *   getDevices: async (controller, { config }) => controller ? myPlugin.getDevices(controller, config) : [],
+ *   getDevices: async (controller, { config }) => controller ? { devices: await myPlugin.getDevices(controller, config), error: "" } : { devices: [], error: "" },
  *   ui: {
  *     isController: (device) => device?.type === "controller",
  *     validOption: (device, option) => device?.type !== "controller" || !option.name.startsWith("Video.")
@@ -187,18 +197,20 @@ export class webUiFeatureOptions {
    *
    *   1. Synchronous page-shell setup: hide schema form, update menu state, reveal the feature-options page. The user sees the layout immediately; the async I/O
    *      below populates each region against the visible shell.
-   *   2. Tear down any prior show() cycle via hide() (it flushes any pending edit before tearing down), then re-sync the session against the host config; a sync
-   *      failure toasts the error message and bails.
-   *   3. Create the page abort controller. Every effect and view registers listeners with this signal so cleanup() tears them all down in one operation.
-   *   4. Fire the plugin I/O requests in parallel: controllers (if configured) and the feature catalog. The plugin config is already held by the session, so there
+   *   2. Tear down any prior show() cycle via hide() (it flushes any pending edit before tearing down).
+   *   3. Create the page abort controller, clear stale containers, create the store, and mount every view. The views mount here - before any data loads, against the
+   *      loading placeholder - so the connection-error view already exists to render a config-sync failure into the visible shell.
+   *   4. Re-sync the session against the host config. A read failure routes into the connection-error view (with the config-read copy) and bails, so a failed sync
+   *      shows the retry affordance rather than stranding a blank frame; the sync also lands before getControllers and the options read below, so both see fresh config.
+   *   5. Fire the plugin I/O requests in parallel: controllers (if configured) and the feature catalog. The plugin config is already held by the session, so there
    *      is no config fetch to overlap here - the base options come from the session's primary entry.
-   *   5. Adopt the design tokens. Synchronous - tokens are static declarations with no I/O dependencies.
-   *   6. Fire the theme effect, persist effect, keyboard effect in parallel. The theme effect's I/O (Bootstrap probe) runs in the background.
+   *   6. Adopt the design tokens (synchronous), then fire the theme, persist, and keyboard effects. The theme effect's I/O (Bootstrap probe) runs in the background.
    *   7. Once controllers resolves: if controller-based mode with empty controllers, show the no-controllers message and return.
-   *   8. Pre-fire the devices fetch for the initial controller so it overlaps with the feature catalog.
-   *   9. Once the feature catalog resolves: build the catalog, dispatch model:loaded, mount all views.
-   *  10. Once devices resolve: dispatch devices:loaded. If a controller is selected but no devices were returned, fetch the error message, dispatch
-   *      connection:error, and return; otherwise set the initial scope.
+   *   8. Record and pre-fire the initial controller's devices fetch (a `devices:requested` mints its sequence) so it overlaps with the feature catalog.
+   *   9. Once the feature catalog resolves: build the catalog and dispatch model:loaded - the mounted views transition off their loading placeholder and render.
+   *  10. Once devices resolve: dispatch devices:loaded carrying the outcome and its sequence. The reducer applies it only when it still answers the pending request and
+   *      folds a fetch failure into the connection-error transition; the orchestrator gates its follow-ups on that verdict - a superseded outcome or a connection-error
+   *      status returns without revealing, otherwise it sets the initial scope.
    *  11. Reveal regions that views render into.
    *
    * @param {import("./pluginConfigSession.mjs").PluginConfigSession} session - The config session supplied by the orchestrator; the page's single source of
@@ -220,20 +232,6 @@ export class webUiFeatureOptions {
     // the menu or the connection-error retry must drain the previous cycle's debounced edit before this cycle's store replaces it.
     await this.hide();
 
-    // Re-read the host config into the session before the page renders against it. show() is the single entry chokepoint (launch, first-run, the menu, and the
-    // connection-error retry), so re-syncing here makes "every show is fresh" an unconditional invariant: an edit made in the Settings tab while this page was hidden
-    // is reflected on return rather than rendering against a frozen snapshot. The sync lands before getControllers reads session.platform and before the options read
-    // below, so both derive from the re-read config. A read failure surfaces as a toast and bails rather than rejecting into a dropped-promise menu handler.
-    try {
-
-      await this.#session.sync();
-    } catch(err) {
-
-      homebridge.toast.error(err?.message ?? String(err), "Error");
-
-      return;
-    }
-
     // Fresh page-level abort controller for this show() cycle.
     this.#pageAbort = new AbortController();
 
@@ -245,6 +243,32 @@ export class webUiFeatureOptions {
     // Initialize the store with empty state. The reducer transitions through loading -> ready once model:loaded dispatches.
     this.#store = new FeatureOptionsStore({ initialState: initialState(), reducer });
 
+    // Mount every view before any data loads. Each view registers its effects against the loading placeholder and yields until model:loaded fires, so mounting
+    // here renders nothing yet - but the connection-error view exists from this point on, so a config-sync failure below renders its retry affordance instead of
+    // stranding a blank frame. Each mount is a no-op if its required page element is missing, so the orchestrator does not need to validate the page skeleton up front.
+    this.#mountViews(signal);
+
+    // Re-read the host config into the session before the page renders against it. show() is the single entry chokepoint (launch, first-run, the menu, and the
+    // connection-error retry), so re-syncing here makes "every show is fresh" an unconditional guarantee: an edit made in the Settings tab while this page was hidden
+    // is reflected on return rather than rendering against a frozen snapshot. The sync lands before getControllers reads session.platform and before the options read
+    // below, so both derive from the re-read config. A read failure routes into the already-mounted connection-error view rather than a bare toast: the store and
+    // views exist by now, so the page shows the retry affordance instead of stranding a blank frame.
+    try {
+
+      await this.#session.sync();
+    } catch(err) {
+
+      this.#store.dispatch({
+
+        guidance: "Retry once the Homebridge server is reachable again.",
+        headline: "Unable to read the plugin configuration.",
+        message: errorMessage(err),
+        type: "connection:error"
+      });
+
+      return;
+    }
+
     // Fire every independent I/O in parallel. The independent sources: controllers (optional), the /getOptions catalog, and the Homebridge lighting mode (via the
     // theme effect's host). The plugin config is not fetched here - the session already holds it - so getControllers receives the injected platform config rather
     // than reaching for it. None depend on each other; firing them concurrently means total wall-clock time is bounded by the slowest.
@@ -292,6 +316,12 @@ export class webUiFeatureOptions {
     }
 
     const initialController = controllers?.[0] ?? null;
+
+    // Record this fetch at the store's chokepoint before firing it, then read back the minted sequence - the store's ticket for this fetch. The sequence, not the
+    // controller, is the fetch identity, so a controller click racing this initial fetch resolves last-request-wins at the reducer.
+    this.#store.dispatch({ controllerId: initialController?.serialNumber ?? null, type: "devices:requested" });
+
+    const devicesSeq = this.#store.state.devicesRequest.seq;
     const devicesPromise = this.#devicesFor(initialController);
 
     // Wait for the feature catalog. Build the catalog (catalog index + validators) and dispatch model:loaded so the store transitions to "ready" and views can mount
@@ -329,9 +359,6 @@ export class webUiFeatureOptions {
       type: "model:loaded"
     });
 
-    // Mount every view. Each mount is a no-op if its required page element is missing, so the orchestrator does not need to validate the page skeleton up front.
-    this.#mountViews(signal);
-
     // Wait for the theme's matchMedia listener registration before any user interaction can trigger a theme change. By this point, themeInitPromise has almost
     // always already resolved - it ran in parallel with every other fetch above.
     await themeInitPromise;
@@ -342,37 +369,35 @@ export class webUiFeatureOptions {
     }
 
     // Wait for devices. The fetch overlapped with config + features; typically already resolved by now.
-    const devices = await devicesPromise;
+    const { devices, error } = await devicesPromise;
 
     if(signal.aborted) {
 
       return;
     }
 
-    this.#store.dispatch({ controllerId: initialController?.serialNumber ?? null, devices: devices ?? [], type: "devices:loaded" });
-
-    // Connection-error short-circuit: controller-based mode with a selected controller but no devices returned means the controller is configured but unreachable.
-    // Fetch the user-facing error message from the host and dispatch connection:error so the connection-error view takes over the header. Do not transition the
-    // scope to a device-view (there are no devices); leave it at global so any subsequent retry re-shows from a known scope.
-    if((initialController !== null) && (devices.length === 0)) {
+    this.#store.dispatch({ controllerId: initialController?.serialNumber ?? null, devices, error, seq: devicesSeq, type: "devices:loaded" });
 
-      const message = String(await homebridge.request("/getErrorMessage") ?? "");
+    // Gate every follow-up on the reducer's own verdict: my outcome applied only when the sequence I carried is the one the reducer recorded. A controller click that
+    // raced this initial fetch would have superseded it - its outcome owns the store, and this stale continuation must neither reveal the page over it nor overwrite
+    // its scope.
+    if(this.#store.state.devicesAppliedSeq !== devicesSeq) {
 
-      if(signal.aborted) {
-
-        return;
-      }
+      return;
+    }
 
-      this.#store.dispatch({ message, type: "connection:error" });
+    // My outcome applied and it turned the store to connection-error: a selected controller whose probe reported a failure. The failure message travelled back on the
+    // DeviceListResult rather than through a separate request, and the reducer folded it into the connection-error transition. The connection-error view reveals
+    // #headerInfo itself when it renders the error block (it is the sole owner of the error display, content and reveal together), so the orchestrator only returns
+    // here. The sidebar, search panel, and config table stay hidden - hide() set them so at show() start and the success-path revealRegions() never runs on this
+    // branch - because the user has no devices to navigate to.
+    if(this.#store.state.status.kind === "connection-error") {
 
-      // The connection-error view reveals #headerInfo itself when it renders the error block (it is the sole owner of the error display, content and reveal together),
-      // so the orchestrator only transitions state here and returns. The sidebar, search panel, and config table stay hidden - hide() set them so at show() start and
-      // the success-path revealRegions() never runs on this branch - because the user has no devices to navigate to.
       return;
     }
 
-    // Set the initial scope. Controller-based mode lands on the first controller's controller-as-device entry (devices[0]). Device-only mode lands on global so
-    // the user sees the global options first.
+    // Set the initial scope. My outcome applied, so the local `devices` is the applied list. Controller-based mode lands on the first controller's controller-as-device
+    // entry (devices[0]). Device-only mode lands on global so the user sees the global options first.
     if((initialController !== null) && (devices.length > 0)) {
 
       this.#store.dispatch({
@@ -488,7 +513,9 @@ export class webUiFeatureOptions {
    * Used as the default `getDevices`, it is extracted unbound and later invoked with `#config` as the receiver, so its body must never reference `this` - it reads only
    * the global `homebridge` object. A future edit that needs instance state must bind it explicitly (or stop using it as the bare default).
    *
-   * @returns {Promise<Device[]>} The list of devices sorted alphabetically by name.
+   * The device-only default always succeeds against the local accessory cache, so the {@link DeviceListResult} it resolves carries an empty error.
+   *
+   * @returns {Promise<DeviceListResult>} The device list sorted alphabetically by name, paired with an empty error.
    * @public
    */
   async getHomebridgeDevices() {
@@ -511,7 +538,7 @@ export class webUiFeatureOptions {
       });
     }
 
-    return devices.toSorted((a, b) => (a.name ?? "").toLowerCase().localeCompare((b.name ?? "").toLowerCase()));
+    return { devices: devices.toSorted((a, b) => (a.name ?? "").toLowerCase().localeCompare((b.name ?? "").toLowerCase())), error: "" };
   }
 
   // Mount every view against the active store and page DOM. Each view registers its own listeners with the page signal; nothing here references the views after
@@ -534,9 +561,16 @@ export class webUiFeatureOptions {
 
         // Retry routes through show(), which owns teardown: its internal `await this.hide()` flushes any debounced edit before aborting the page signal, so a retry
         // cannot drop a pending write. We deliberately do not call cleanup() here - cleanup() aborts the signal without flushing, which is exactly the drop we avoid.
+        // The retry button fires this as `void onRetry()`, so a rejection is otherwise unobserved; the try/catch surfaces a failed re-show as an error toast instead.
         onRetry: async () => {
 
-          await this.show(this.#session);
+          try {
+
+            await this.show(this.#session);
+          } catch(err) {
+
+            toastError(err);
+          }
         },
         retryDelayMs: this.#config.controllerRetryEnableDelayMs,
         root: headerInfo,
@@ -565,8 +599,10 @@ export class webUiFeatureOptions {
 
     if(configTable) {
 
-      // The localStorage namespace key is the Homebridge platform identifier - the primary entry's `platform` field, read from the session.
-      mountOptionsView({ configTable, platform: this.#session?.platform?.platform, signal, store });
+      // The localStorage namespace key is the Homebridge platform identifier - the primary entry's `platform` field. Passed as a thunk, not a frozen string: the
+      // views mount before the session re-syncs, so the options view reads the identifier through the thunk inside its model:loaded effect (post-sync) rather
+      // than capturing a possibly pre-sync value here.
+      mountOptionsView({ configTable, platform: () => this.#session?.platform?.platform, signal, store });
     }
 
     if(controllersContainer && devicesContainer) {
@@ -574,7 +610,6 @@ export class webUiFeatureOptions {
       mountNavView({
 
         getDevices: (controller) => this.#devicesFor(controller),
-        host: homebridge,
         labelControllers: this.#config.labelControllers,
         labelDevices: this.#config.labelDevices,
         rootControllers: controllersContainer,
@@ -585,12 +620,24 @@ export class webUiFeatureOptions {
     }
   }
 
-  // Resolve the device list for a controller, injecting the live platform config the plugin's getDevices needs to recover the controller's credentials. Centralizing
-  // the injection here means both the initial fetch in show() and the on-click fetch in the nav view call the same config-fed seam, and the config is read fresh from
-  // the session on every call - never captured - so a credential change is always reflected. The default device-only getDevices ignores the injected config.
-  #devicesFor(controller) {
+  // Resolve a controller's DeviceListResult, injecting the live platform config the plugin's getDevices needs to recover the controller's credentials. This is the
+  // single seam every device fetch crosses - the initial fetch in show() and the on-click fetch in the nav view both route through it - and the config is read fresh
+  // from the session on every call, never captured, so a credential change is always reflected. The default device-only getDevices ignores the injected config.
+  //
+  // The full rich contract is enforced here with a fail-fast guard: the hook must resolve an object carrying a `devices` array and a string `error`. The error half
+  // is what guarantees every downstream reader (the connection-error view's DOM construction, whose createElement child loop passes a non-string message straight to
+  // appendChild) receives a string. A resolved value that does not match trips a TypeError naming the contract, so a shape mistake surfaces loudly at the seam rather
+  // than as a corrupted render deeper in.
+  async #devicesFor(controller) {
+
+    const result = await this.#config.getDevices(controller, { config: this.#session?.platform });
+
+    if(!result || !Array.isArray(result.devices) || (typeof result.error !== "string")) {
+
+      throw new TypeError("getDevices must resolve to { devices, error }.");
+    }
 
-    return this.#config.getDevices(controller, { config: this.#session?.platform });
+    return result;
   }
 }
 
@@ -664,7 +711,8 @@ const sameOptionsSet = (a, b) => {
 };
 
 // Show the "no controllers configured" helper text when the plugin operates in controller-based mode but getControllers returns an empty result. Replaces the
-// header content in place; the orchestrator returns from show() without dispatching model:loaded so views never mount.
+// header content in place; the orchestrator returns from show() without dispatching model:loaded, so the already-mounted views stay on their loading placeholder and
+// never render over this message.
 const showNoControllersMessage = () => {
 
   const headerInfo = document.getElementById("headerInfo");

package/dist/ui/webUi.mjs

@@ -5,6 +5,7 @@
 "use strict";
 
 import { PluginConfigSession } from "./pluginConfigSession.mjs";
+import { toastError } from "./webUi-featureOptions/utils.mjs";
 import { webUiFeatureOptions } from "./webUi-featureOptions.mjs";
 
 /**
@@ -80,13 +81,17 @@ export class webUi {
       await this.#launchWebUI();
     } catch(err) {
 
-      // Outermost user-facing diagnostic seam in the webUI. Caller-supplied first-run handlers and other extension points can throw any shape (strings, plain
-      // objects, primitives), so normalize before reaching the toast: `err?.message` extracts the message field when present, the nullish coalesce falls back
-      // to a string coercion of the whole value otherwise. This keeps the toast text useful regardless of what bubbled out of `#launchWebUI`.
-      homebridge.toast.error(err?.message ?? String(err), "Error");
+      // Outermost user-facing diagnostic seam in the webUI. Caller-supplied first-run handlers and other extension points can throw any shape, so the shared
+      // toastError normalization extracts a useful message regardless of what bubbled out of `#launchWebUI`.
+      toastError(err);
     } finally {
 
       homebridge.hideSpinner();
+
+      // Stand the boot monitor down. Once show() settles the app owns the surface either way - on success the UI rendered, on failure the toast above displayed the
+      // diagnostic - so any earlier boot-phase error the monitor may have caught was non-fatal, and it should retract any panel it raised. The optional chain tolerates
+      // a stamped region that carries no boot monitor.
+      globalThis.webUiBoot?.ready?.();
     }
   }
 
@@ -94,7 +99,10 @@ export class webUi {
    * Show the first-run user experience.
    *
    * Wires the submit button to run the caller-supplied submit handler, swap the page from first-run to feature-options, and hand off to the feature-options view.
-   * The save button stays disabled until the user completes the first-run flow so a partially-configured plugin cannot be written back to disk.
+   * The save button stays disabled until the user completes the first-run flow so a partially-configured plugin cannot be written back to disk. A submit failure
+   * surfaces as an error toast, and where the failure landed decides what the user is left looking at: a rejected submit throws before the page swap and leaves the
+   * first-run page fully visible for another attempt, while a failure during the feature-options handoff after a successful submit leaves the main shell visible with
+   * the menu still usable for recovery.
    *
    * @returns {Promise<void>}
    * @private
@@ -134,6 +142,13 @@ export class webUi {
         await this.featureOptions.show(this.#session);
 
         homebridge.enableSaveButton();
+      } catch(err) {
+
+        // A first-run submit can throw from two places, and where it threw decides what the user is left looking at. A rejected onSubmit (a failed login or
+        // configuration validation) throws before the page swap, so the first-run page stays fully visible for another attempt. A rejection from
+        // featureOptions.show() after a successful submit throws after the swap, so the main shell is visible with the menu still usable for recovery. In both cases
+        // the toast is the diagnostic, and the finally below brings the spinner down.
+        toastError(err);
       } finally {
 
         homebridge.hideSpinner();
@@ -143,6 +158,27 @@ export class webUi {
     document.getElementById("pageFirstRun").style.display = "block";
   }
 
+  /**
+   * Show the feature-options tab from the menu.
+   *
+   * The menuFeatureOptions button re-enters the feature-options view. `featureOptions.show()` can reject - a plugin `getDevices` hook that resolves the wrong shape
+   * trips the device-list contract guard, for one - and the click listener drops the returned promise, so this method brackets the re-entry in a try/catch that
+   * surfaces a failed re-show as an error toast rather than an unobserved rejection.
+   *
+   * @returns {Promise<void>}
+   * @private
+   */
+  async #showFeatureOptions() {
+
+    try {
+
+      await this.featureOptions.show(this.#session);
+    } catch(err) {
+
+      toastError(err);
+    }
+  }
+
   /**
    * Show the main plugin configuration tab.
    *
@@ -228,13 +264,14 @@ export class webUi {
     // later reader sees.
     this.#session = await PluginConfigSession.open({ host: homebridge, name: this.#name });
 
-    // Menu click listeners use a uniform shape: an arrow expression that calls the handler and returns its result. addEventListener discards the return value, so an
-    // async handler's promise is dropped either way; wrapping `featureOptions.show()` in `async () => await ...` would add a microtask hop and break the visual
-    // symmetry across the three sibling registrations for no behavioral benefit. All three handlers are async (show() syncs; #showSettings / #showSupport await
-    // the navigate-away flush before revealing the next tab), and the dropped promise is a deliberate fire-and-forget: each handler's own try/finally reveals the tab
-    // and drains the spinner on every path, and the flush drain's failure surfaces internally via persist:failed's toast - so there is no unobserved rejection here.
+    // Menu click listeners use a uniform shape: an arrow expression that calls a handler and returns its result. addEventListener discards the return value, so each
+    // async handler's promise is dropped; the handlers own their error handling so the drop carries no unobserved rejection. #showFeatureOptions wraps
+    // featureOptions.show() in a try/catch that toasts a failed re-entry - the show pipeline can reject (a plugin getDevices hook that resolves the wrong shape trips
+    // the device-list contract guard, for one), and without the wrapper that rejection would surface nowhere. #showSettings and #showSupport each bracket their
+    // navigate-away flush in a try/finally that reveals the next tab and drains the spinner on every path (the flush drain's own failure surfaces via persist:failed's
+    // toast).
     document.getElementById("menuHome").addEventListener("click", () => this.#showSupport());
-    document.getElementById("menuFeatureOptions").addEventListener("click", () => this.featureOptions.show(this.#session));
+    document.getElementById("menuFeatureOptions").addEventListener("click", () => this.#showFeatureOptions());
     document.getElementById("menuSettings").addEventListener("click", () => this.#showSettings());
 
     // The caller's first-run gate decides routing against the injected platform config. No separate "is there any config?" test is needed: a plugin with a first-run