@scarlett-player/embed 1.2.0 → 1.4.0

package/dist/embed.audio.js

@@ -148,6 +148,7 @@ class StateManager {
   constructor(initialState) {
     this.signals = /* @__PURE__ */ new Map();
     this.changeSubscribers = /* @__PURE__ */ new Set();
+    this.definedDefaults = /* @__PURE__ */ new Map();
     this.initializeSignals(initialState);
   }
   /**
@@ -157,13 +158,51 @@ class StateManager {
   initializeSignals(overrides) {
     const initialState = { ...DEFAULT_STATE, ...overrides };
     for (const [key, value] of Object.entries(initialState)) {
-      const stateKey = key;
-      const stateSignal = signal(value);
-      stateSignal.subscribe(() => {
-        this.notifyChangeSubscribers(stateKey);
-      });
-      this.signals.set(stateKey, stateSignal);
+      this.createSignal(key, value);
+    }
+  }
+  /**
+   * Create and register a signal, wired to the global change subscribers.
+   *
+   * Shared by initializeSignals() and define() so a plugin-defined key behaves
+   * exactly like a built-in one and the two paths cannot drift apart.
+   *
+   * @private
+   */
+  createSignal(key, value) {
+    const stateSignal = signal(value);
+    stateSignal.subscribe(() => {
+      this.notifyChangeSubscribers(key);
+    });
+    this.signals.set(key, stateSignal);
+  }
+  /**
+   * Register a state key at runtime, for state a plugin owns.
+   *
+   * Core cannot know every plugin's keys, and {@link get} deliberately throws
+   * for unregistered ones — that throw is a useful typo-catcher and is worth
+   * keeping — so a plugin declares its keys before first use.
+   *
+   * Idempotent by design: re-defining an existing key leaves the current value
+   * untouched. Plugins commonly re-run setup after a source change, and that
+   * must not reset state that is already live.
+   *
+   * Namespace plugin keys with the plugin's own name to avoid collisions.
+   *
+   * @param key - State property key
+   * @param initialValue - Value used only when the key is new
+   *
+   * @example
+   * ```ts
+   * state.define('highlightSelection', null);
+   * ```
+   */
+  define(key, initialValue) {
+    if (this.signals.has(key)) {
+      return;
     }
+    this.definedDefaults.set(key, initialValue);
+    this.createSignal(key, initialValue);
   }
   /**
    * Get the signal for a state property.
@@ -307,7 +346,10 @@ class StateManager {
    * ```
    */
   reset() {
-    this.update(DEFAULT_STATE);
+    this.update({
+      ...DEFAULT_STATE,
+      ...Object.fromEntries(this.definedDefaults)
+    });
   }
   /**
    * Reset a specific state property to its default value.
@@ -320,7 +362,7 @@ class StateManager {
    * ```
    */
   resetKey(key) {
-    const defaultValue = DEFAULT_STATE[key];
+    const defaultValue = key in DEFAULT_STATE ? DEFAULT_STATE[key] : this.definedDefaults.get(key);
     this.set(key, defaultValue);
   }
   /**
@@ -1214,6 +1256,18 @@ class PluginAPI {
   setState(key, value) {
     this.stateManager.set(key, value);
   }
+  /**
+   * Register a state key this plugin owns, before first use.
+   *
+   * Idempotent — re-defining an existing key keeps its current value.
+   * See {@link IPluginAPI.defineState}.
+   *
+   * @param key - State property key
+   * @param initialValue - Value used only when the key is new
+   */
+  defineState(key, initialValue) {
+    this.stateManager.define(key, initialValue);
+  }
   /**
    * Subscribe to an event.
    *