homebridge-plugin-utils 2.0.0 → 2.1.0

package/dist/ui/webUi-featureOptions.mjs

@@ -4,10 +4,10 @@
  */
 "use strict";
 
+import { delay, 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.")
@@ -197,8 +207,8 @@ export class webUiFeatureOptions {
    *   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.
+   *  10. Once devices resolve: dispatch devices:loaded. If a controller is selected and the result carried a connection-failure error, dispatch connection:error
+   *      with that message and return; otherwise set 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
@@ -221,15 +231,15 @@ export class webUiFeatureOptions {
     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
+    // 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 surfaces as a toast and bails rather than rejecting into a dropped-promise menu handler.
+    // below, so both derive from the re-read config. A read failure surfaces as a toast and bails, so the page never renders against a config the session could not read.
     try {
 
       await this.#session.sync();
     } catch(err) {
 
-      homebridge.toast.error(err?.message ?? String(err), "Error");
+      toastError(err);
 
       return;
     }
@@ -342,28 +352,23 @@ 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" });
+    this.#store.dispatch({ controllerId: initialController?.serialNumber ?? null, 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)) {
-
-      const message = String(await homebridge.request("/getErrorMessage") ?? "");
-
-      if(signal.aborted) {
-
-        return;
-      }
+    // Connection-error short-circuit: a selected controller whose probe reported a failure. The failure message arrives with the device-list response - it travels
+    // back on the DeviceListResult rather than through a separate request - so a non-empty error is the failure signal and dispatching connection:error hands the
+    // header to the connection-error view. A zero-device result with an empty error is a legitimately empty controller and falls through to the scope logic below,
+    // never the connection-error view. Do not transition the scope to a device-view here (there are no devices); leave it at global so any subsequent retry re-shows
+    // from a known scope.
+    if((initialController !== null) && error.length) {
 
-      this.#store.dispatch({ message, type: "connection:error" });
+      this.#store.dispatch({ message: error, type: "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
@@ -488,7 +493,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 +518,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 +541,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,
@@ -574,7 +588,6 @@ export class webUiFeatureOptions {
       mountNavView({
 
         getDevices: (controller) => this.#devicesFor(controller),
-        host: homebridge,
         labelControllers: this.#config.labelControllers,
         labelDevices: this.#config.labelDevices,
         rootControllers: controllersContainer,
@@ -585,12 +598,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;
   }
 }
 

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,10 +81,9 @@ 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();
@@ -94,7 +94,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 +137,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 +153,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 +259,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

package/dist/util.d.ts

@@ -8,8 +8,8 @@ import type { Logging } from "homebridge";
  * The canonical set of abort reasons used across `homebridge-plugin-utils`.
  *
  * Every long-lived resource class in the library exposes an {@link AbortSignal} whose abort reason is normally an {@link HbpuAbortError} carrying one of these names.
- * Consumers discriminate on the `.name` field. Platform errors produced by `AbortSignal.timeout()` and bare `controller.abort()` interoperate by matching names:
- * `TimeoutError` and `AbortError` from the platform both flow through the same discrimination paths unchanged.
+ * Consumers branch on the `.name` field. Platform errors produced by `AbortSignal.timeout()` and bare `controller.abort()` interoperate by matching names:
+ * `TimeoutError` and `AbortError` from the platform both flow through the same branching paths unchanged.
  *
  * @remarks When to use each reason:
  *
@@ -34,7 +34,7 @@ export interface HbpuAbortErrorOptions {
      */
     cause?: unknown;
     /**
-     * Optional human-readable message. When omitted, the error's `message` defaults to the reason name, which is sufficient for discrimination-based handling.
+     * Optional human-readable message. When omitted, the error's `message` defaults to the reason name, which is sufficient for name-based handling.
      */
     message?: string;
 }
@@ -73,7 +73,7 @@ export interface HbpuAbortErrorOptions {
  */
 export declare class HbpuAbortError extends Error {
     /**
-     * The discriminator. Matches one of {@link HbpuAbortReason}.
+     * The tag. Matches one of {@link HbpuAbortReason}.
      */
     readonly name: HbpuAbortReason;
     /**
@@ -87,7 +87,7 @@ export declare class HbpuAbortError extends Error {
 /**
  * Type guard: returns `true` if `error` is an {@link HbpuAbortError}.
  *
- * Use this to discriminate HBPU's canonical abort errors from arbitrary thrown values, without nesting `instanceof` checks.
+ * Use this to distinguish HBPU's canonical abort errors from arbitrary thrown values, without nesting `instanceof` checks.
  *
  * @param error - The value to test.
  *
@@ -101,7 +101,7 @@ export declare function isHbpuAbortError(error: unknown): error is HbpuAbortErro
  * `error.cause` and related fields without further casts.
  *
  * Collapses the common "is this an HBPU abort, and was it this specific reason?" question into a single call, avoiding the `instanceof` + `.name` nesting that appears
- * throughout consuming code. The generic parameter `R` preserves the specific reason string in the narrowed type so callers that discriminate further by name get the
+ * throughout consuming code. The generic parameter `R` preserves the specific reason string in the narrowed type so callers that distinguish further by name get the
  * literal narrowed form automatically.
  *
  * @typeParam R - The specific reason being matched. Defaulted by inference from `reason`.
@@ -118,7 +118,7 @@ export declare function isHbpuAbortReason<R extends HbpuAbortReason>(error: unkn
 /**
  * Test whether an abort reason indicates a timeout. Matches both the canonical {@link HbpuAbortError} with `"timeout"` name - produced by project watchdogs
  * ({@link Watchdog}, the inactivity monitors on `FfmpegProcess` / `RtpDemuxer` / `Mp4SegmentAssembler`) - and the platform {@link DOMException}/`Error` whose
- * `.name === "TimeoutError"` - produced by `AbortSignal.timeout()`. Consumers discriminate on a single predicate regardless of which code path originated the timeout.
+ * `.name === "TimeoutError"` - produced by `AbortSignal.timeout()`. Consumers branch on a single predicate regardless of which code path originated the timeout.
  *
  * Exists because every long-lived resource class exposes an `isTimedOut` getter with identical branching logic; routing all of them through this single predicate
  * enforces one taxonomy and eliminates drift if the project ever needs to add, say, a third timeout shape (e.g., an upstream-framework cancellation).
@@ -185,7 +185,7 @@ export declare function isTimeoutReason(reason: unknown): boolean;
  *     // Abort-driven action goes here.
  *   });
  *
- *   // `return await promise` (not a bare `return promise`) is load-bearing inside an async function. `using` disposes when the enclosing function body finishes
+ *   // `return await promise` (not a bare `return promise`) is required inside an async function. `using` disposes when the enclosing function body finishes
  *   // executing, and without an `await` the body finishes synchronously at the `return` statement - even though the returned promise is still pending. The
  *   // listener would therefore be removed the instant the function returned, well before the promise settles. Adding `await` creates a suspension point that
  *   // keeps the `using` scope alive until the promise actually settles, which is what the "scope-bound registration" pattern relies on.
@@ -590,9 +590,9 @@ export declare function composeSignals(...signals: (AbortSignal | undefined)[]):
  * Supervise a detached, signal-bound async loop: run the loop, resolve quietly when it ends or its signal aborts, and route any genuine fault to a caller-supplied
  * handler exactly once.
  *
- * Resilient background loops - membership observers, reachability probes, telemetry firehoses - all share one subtle, correctness-critical invariant: a throw is a
+ * Resilient background loops - membership observers, reachability probes, telemetry firehoses - all share one subtle, correctness-critical rule: a throw is a
  * *fault* only when we did not cause it. When the bound signal is aborted, a throw is the orderly unwinding of a loop the caller already tore down, so it is swallowed
- * silently. Any other throw is a genuine fault and is handed to `onError` exactly once. Hand-copying that swallow-on-abort-versus-surface-once discrimination across
+ * silently. Any other throw is a genuine fault and is handed to `onError` exactly once. Hand-copying that swallow-on-abort-versus-surface-once distinction across
  * call sites that share no ancestor is how it drifts apart; owning it in one generic primitive is how it stays consistent.
  *
  * The home is here, beside {@link composeSignals}, because the envelope is fully generic - it carries no logging policy, no message wording, and makes no detachment
@@ -674,6 +674,83 @@ export declare function superviseLoop(options: {
  * @category Utilities
  */
 export declare function loopFaultReporter(log: HomebridgePluginLogging, label: string): (error: unknown) => void;
+/**
+ * The minimal completion-callback shape {@link guardedDispatch} guards. HomeKit's camera-delegate callbacks (snapshot, prepare-stream, stream-request) each answer with
+ * an optional leading `Error` and, in some cases, an optional trailing payload; every one is structurally assignable to this error-first shape, so `guardedDispatch`
+ * serves them all without importing any HomeKit or hap-nodejs type. A richer callback that also carries a success payload is preserved through the generic parameter on
+ * {@link guardedDispatch}, which keeps the caller's exact signature while still guarding it.
+ *
+ * @category Utilities
+ */
+export type DispatchCallback = (error?: Error) => void;
+/**
+ * Run an async handler that HomeKit invokes without awaiting - a camera-delegate method whose interface return type is `void` - so a rejection can never float as an
+ * unhandled rejection and the delegate's completion callback is answered exactly once.
+ *
+ * HomeKit's camera-delegate methods (snapshot, prepare-stream, stream-request) are declared to return `void` yet are naturally written as `async`. Calling an async
+ * method in that position discards its promise: a rejection surfaces as a process-level unhandled rejection, and if the method faulted before answering its callback,
+ * HomeKit waits forever for a response that never comes. `guardedDispatch` closes both gaps. It owns a once-guard around the real callback and hands the guarded callback
+ * to `handler`, so however the handler behaves - answered then faulted, faulted before answering, or answered twice by mistake - the real callback fires exactly once:
+ * the first answer wins; a fault after an answer is logged and the earlier answer stands; a fault before any answer is delivered to HomeKit through the callback itself.
+ * The handler's promise is marked observed through {@link markHandled}, so nothing floats.
+ *
+ * @typeParam C          - The caller's exact callback signature. Constrained to {@link DispatchCallback} (error-first) so any HomeKit delegate callback fits, while
+ *                         preserving a richer signature - one that also passes a snapshot buffer or stream response - for the handler to answer with.
+ * @param options          - Dispatch inputs.
+ * @param options.callback - The real completion callback HomeKit supplied. It is wrapped in a once-guard and never invoked more than once.
+ * @param options.handler  - The async work, given the guarded callback to answer with. A rejection, or a synchronous throw, is caught: while the callback is still open
+ *                           it receives the error, otherwise the error is logged.
+ * @param options.label    - A short human-readable name for the operation (for example `"snapshot request"`), interpolated into the failure log line.
+ * @param options.log      - The logger a post-answer fault is reported through.
+ *
+ * @example
+ *
+ * ```ts
+ * import { guardedDispatch } from "homebridge-plugin-utils";
+ *
+ * // A snapshot delegate HomeKit calls without awaiting. The method itself returns void; the async work and its one-shot callback are handed to guardedDispatch.
+ * public handleSnapshotRequest(request: SnapshotRequest, callback: SnapshotRequestCallback): void {
+ *
+ *   guardedDispatch({ callback, handler: (answer) => this.snapshot(request, answer), label: "snapshot request", log: this.log });
+ * }
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function guardedDispatch<C extends DispatchCallback>(options: {
+    callback: C;
+    handler: (callback: C) => Promise<void>;
+    label: string;
+    log: Logger;
+}): void;
+/**
+ * Run an async, callback-less handler that HomeKit (or any caller) invokes without awaiting, so a rejection can never float as an unhandled rejection. With no callback
+ * to carry a failure back, a fault is simply logged.
+ *
+ * @param options         - Dispatch inputs.
+ * @param options.handler - The async work to run. A rejection, or a synchronous throw, is caught and logged.
+ * @param options.label   - A short human-readable name for the operation (for example `"recording activation"`), interpolated into the failure log line.
+ * @param options.log     - The logger a fault is reported through.
+ *
+ * @example
+ *
+ * ```ts
+ * import { guardedDispatch } from "homebridge-plugin-utils";
+ *
+ * // A recording-state update HomeKit calls without awaiting. There is no callback, so a fault is logged rather than reported back to HomeKit.
+ * public updateRecordingActive(active: boolean): void {
+ *
+ *   guardedDispatch({ handler: () => this.applyRecordingActive(active), label: "recording activation", log: this.log });
+ * }
+ * ```
+ *
+ * @category Utilities
+ */
+export declare function guardedDispatch(options: {
+    handler: () => Promise<void>;
+    label: string;
+    log: Logger;
+}): void;
 /**
  * Options for {@link runWithAbort}. At least one of `signal` or `timeout` must be provided so there is always an abort mechanism. TypeScript enforces this at compile
  * time through a discriminated union - the "no abort mechanism" case is unrepresentable.
@@ -790,12 +867,12 @@ export declare class Watchdog implements Disposable {
     arm(): void;
     /**
      * Cancel any pending fire without aborting anything and without marking the watchdog as permanently dead. Subsequent `arm()` calls continue to work. Safe to call
-     * when no arm is pending - the method is idempotent.
+     * when no arm is pending - repeat calls are no-ops.
      */
     clear(): void;
     /**
      * `Disposable` implementation. Clears any pending fire AND permanently disables the watchdog: after this runs, `arm()` is a no-op and no further `onFire` calls can
-     * occur. This is the contract `using watchdog = new Watchdog(...)` relies on - the resource is dead when the block exits, not merely quiescent. Idempotent; repeated
+     * occur. This is the contract `using watchdog = new Watchdog(...)` relies on - the resource is dead when the block exits, not merely quiescent. Repeated
      * disposal is a no-op. Because the class does not own an abort controller, disposal does not signal anything to the rest of the system.
      */
     [Symbol.dispose](): void;