@scarlett-player/ui 1.2.0 → 1.4.0

package/dist/index.cjs

@@ -23,9 +23,13 @@ __export(index_exports, {
   default: () => index_default,
   formatLiveTime: () => formatLiveTime,
   formatTime: () => formatTime,
+  getControlFactory: () => getControlFactory,
   icons: () => icons,
+  registerControl: () => registerControl,
+  resetControlRegistry: () => resetControlRegistry,
   styles: () => styles,
-  uiPlugin: () => uiPlugin
+  uiPlugin: () => uiPlugin,
+  unregisterControl: () => unregisterControl
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -2615,6 +2619,32 @@ var BandwidthIndicator = class {
   }
 };
 
+// src/control-registry.ts
+var registry = /* @__PURE__ */ new Map();
+var listeners = /* @__PURE__ */ new Set();
+function registerControl(id, factory) {
+  registry.set(id, factory);
+  for (const listener of listeners) {
+    listener(id);
+  }
+}
+function unregisterControl(id) {
+  return registry.delete(id);
+}
+function getControlFactory(id) {
+  return registry.get(id) ?? null;
+}
+function onControlRegistered(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function resetControlRegistry() {
+  registry.clear();
+  listeners.clear();
+}
+
 // src/index.ts
 var DEFAULT_LAYOUT = [
   "play",
@@ -2644,6 +2674,7 @@ function uiPlugin(config = {}) {
   let controls = [];
   let hideTimeout = null;
   let stateUnsubscribe = null;
+  let controlRegistryUnsubscribe = null;
   let errorUnsubscribe = null;
   let reconnectingUnsubscribe = null;
   let recoveredUnsubscribe = null;
@@ -2685,10 +2716,43 @@ function uiPlugin(config = {}) {
         return new FullscreenButton(api);
       case "spacer":
         return new Spacer();
-      default:
+      default: {
+        const factory = getControlFactory(slot);
+        if (factory) {
+          try {
+            return factory(api);
+          } catch (error) {
+            api.logger.error(`Control factory for "${slot}" threw`, { error });
+            return null;
+          }
+        }
+        api.logger.warn(`Unknown control slot: ${slot}`);
         return null;
+      }
     }
   };
+  const populateControlBar = () => {
+    if (!controlBar) {
+      return;
+    }
+    for (const slot of layout) {
+      const control = createControl(slot);
+      if (control) {
+        controls.push(control);
+        controlBar.appendChild(control.render());
+      }
+    }
+  };
+  const rebuildControlBar = () => {
+    if (!controlBar) {
+      return;
+    }
+    controls.forEach((c) => c.destroy());
+    controls = [];
+    controlBar.replaceChildren();
+    populateControlBar();
+    updateControls();
+  };
   const updateControls = () => {
     controls.forEach((c) => c.update());
     progressBar?.update();
@@ -2861,14 +2925,15 @@ function uiPlugin(config = {}) {
       controlBar.className = isPlaying ? "sp-controls sp-controls--hidden" : "sp-controls sp-controls--visible";
       controlBar.setAttribute("role", "toolbar");
       controlBar.setAttribute("aria-label", "Video controls");
-      for (const slot of layout) {
-        const control = createControl(slot);
-        if (control) {
-          controls.push(control);
-          controlBar.appendChild(control.render());
-        }
-      }
+      populateControlBar();
       container.appendChild(controlBar);
+      controlRegistryUnsubscribe = onControlRegistered((id) => {
+        if (!layout.includes(id)) {
+          return;
+        }
+        api.logger.debug(`Control "${id}" registered after init, rebuilding control bar`);
+        rebuildControlBar();
+      });
       container.addEventListener("mousemove", handleInteraction);
       container.addEventListener("mouseenter", handleInteraction);
       container.addEventListener("mouseleave", handleMouseLeave);
@@ -2914,6 +2979,8 @@ function uiPlugin(config = {}) {
       }
       document.removeEventListener("keydown", handleKeyDown);
       document.removeEventListener("fullscreenchange", scheduleUpdate);
+      controlRegistryUnsubscribe?.();
+      controlRegistryUnsubscribe = null;
       controls.forEach((c) => c.destroy());
       controls = [];
       progressBar?.destroy();
@@ -2970,7 +3037,11 @@ var index_default = uiPlugin;
 0 && (module.exports = {
   formatLiveTime,
   formatTime,
+  getControlFactory,
   icons,
+  registerControl,
+  resetControlRegistry,
   styles,
-  uiPlugin
+  uiPlugin,
+  unregisterControl
 });

package/dist/index.d.cts

@@ -1,13 +1,26 @@
-import { Plugin } from '@scarlett-player/core';
+import { Plugin, IPluginAPI } from '@scarlett-player/core';
 
 /**
  * UI Controls Plugin Types
  */
 
 /**
- * Available control slot identifiers.
+ * Control slots this package implements itself.
  */
-type ControlSlot = 'play' | 'skip-backward' | 'skip-forward' | 'volume' | 'progress' | 'time' | 'live-indicator' | 'quality' | 'settings' | 'captions' | 'airplay' | 'chromecast' | 'pip' | 'fullscreen' | 'spacer' | 'bandwidth-indicator';
+type BuiltinControlSlot = 'play' | 'skip-backward' | 'skip-forward' | 'volume' | 'progress' | 'time' | 'live-indicator' | 'quality' | 'settings' | 'captions' | 'airplay' | 'chromecast' | 'pip' | 'fullscreen' | 'spacer' | 'bandwidth-indicator';
+/**
+ * A control slot: a built-in, or any id a plugin registered through
+ * {@link registerControl}.
+ *
+ * `string & {}` keeps editor autocomplete listing the built-ins while still
+ * accepting custom ids — a plain `| string` would collapse the union and lose
+ * the suggestions.
+ */
+type ControlSlot = BuiltinControlSlot | (string & {});
+/**
+ * Builds a control instance. Receives the same plugin API the built-ins get.
+ */
+type ControlFactory = (api: IPluginAPI) => Control;
 /**
  * Layout configuration for the control bar.
  */
@@ -65,6 +78,65 @@ interface IUIPlugin extends Plugin {
     getControlBar(): HTMLElement | null;
 }
 
+/**
+ * Custom control registry.
+ *
+ * The built-in controls are created by a switch in the UI plugin. Anything a
+ * plugin package contributes is registered here instead, so a control-bar
+ * button no longer requires editing this package.
+ *
+ * The registry is module-level and therefore shared by every player instance on
+ * the page. That matches how plugin packages register — once, at import time or
+ * in `init()` — and the factory receives the per-instance `IPluginAPI`, so the
+ * controls themselves stay properly scoped to their player.
+ */
+
+/**
+ * Register a control factory under a slot id.
+ *
+ * The id only takes effect for players whose layout lists it — registering
+ * alone never adds a button anywhere. Hosts opt controls in through
+ * `uiPlugin({ controls: [...] })`.
+ *
+ * Registering an id that already exists replaces the factory and re-notifies,
+ * which keeps hot-reload workable.
+ *
+ * @param id - Slot id, conventionally the plugin's own name
+ * @param factory - Builds the control for a given player
+ *
+ * @example
+ * ```ts
+ * registerControl('share', (api) => new ShareButton(api));
+ * ```
+ */
+declare function registerControl(id: string, factory: ControlFactory): void;
+/**
+ * Remove a registered control factory.
+ *
+ * Players already showing the control keep their existing instance until they
+ * rebuild; this only stops future ones being created.
+ *
+ * @param id - Slot id to remove
+ * @returns Whether a factory was registered under that id
+ */
+declare function unregisterControl(id: string): boolean;
+/**
+ * Look up a registered factory.
+ *
+ * @param id - Slot id
+ * @returns The factory, or null when nothing is registered for that id
+ */
+declare function getControlFactory(id: string): ControlFactory | null;
+/**
+ * Clear all registrations and listeners.
+ *
+ * Test-support only — the registry is module-level, so without this a
+ * registration in one test leaks into the next.
+ *
+ * @internal
+ */
+declare function resetControlRegistry(): void;
+
 /**
  * SVG Icons for UI Controls
  *
@@ -148,4 +220,4 @@ declare function formatLiveTime(behindLive: number): string;
  */
 declare function uiPlugin(config?: UIPluginConfig): IUIPlugin;
 
-export { type Control, type ControlSlot, type IUIPlugin, type LayoutConfig, type ThemeConfig, type UIPluginConfig, uiPlugin as default, formatLiveTime, formatTime, icons, styles, uiPlugin };
+export { type BuiltinControlSlot, type Control, type ControlFactory, type ControlSlot, type IUIPlugin, type LayoutConfig, type ThemeConfig, type UIPluginConfig, uiPlugin as default, formatLiveTime, formatTime, getControlFactory, icons, registerControl, resetControlRegistry, styles, uiPlugin, unregisterControl };

package/dist/index.d.ts

@@ -1,13 +1,26 @@
-import { Plugin } from '@scarlett-player/core';
+import { Plugin, IPluginAPI } from '@scarlett-player/core';
 
 /**
  * UI Controls Plugin Types
  */
 
 /**
- * Available control slot identifiers.
+ * Control slots this package implements itself.
  */
-type ControlSlot = 'play' | 'skip-backward' | 'skip-forward' | 'volume' | 'progress' | 'time' | 'live-indicator' | 'quality' | 'settings' | 'captions' | 'airplay' | 'chromecast' | 'pip' | 'fullscreen' | 'spacer' | 'bandwidth-indicator';
+type BuiltinControlSlot = 'play' | 'skip-backward' | 'skip-forward' | 'volume' | 'progress' | 'time' | 'live-indicator' | 'quality' | 'settings' | 'captions' | 'airplay' | 'chromecast' | 'pip' | 'fullscreen' | 'spacer' | 'bandwidth-indicator';
+/**
+ * A control slot: a built-in, or any id a plugin registered through
+ * {@link registerControl}.
+ *
+ * `string & {}` keeps editor autocomplete listing the built-ins while still
+ * accepting custom ids — a plain `| string` would collapse the union and lose
+ * the suggestions.
+ */
+type ControlSlot = BuiltinControlSlot | (string & {});
+/**
+ * Builds a control instance. Receives the same plugin API the built-ins get.
+ */
+type ControlFactory = (api: IPluginAPI) => Control;
 /**
  * Layout configuration for the control bar.
  */
@@ -65,6 +78,65 @@ interface IUIPlugin extends Plugin {
     getControlBar(): HTMLElement | null;
 }
 
+/**
+ * Custom control registry.
+ *
+ * The built-in controls are created by a switch in the UI plugin. Anything a
+ * plugin package contributes is registered here instead, so a control-bar
+ * button no longer requires editing this package.
+ *
+ * The registry is module-level and therefore shared by every player instance on
+ * the page. That matches how plugin packages register — once, at import time or
+ * in `init()` — and the factory receives the per-instance `IPluginAPI`, so the
+ * controls themselves stay properly scoped to their player.
+ */
+
+/**
+ * Register a control factory under a slot id.
+ *
+ * The id only takes effect for players whose layout lists it — registering
+ * alone never adds a button anywhere. Hosts opt controls in through
+ * `uiPlugin({ controls: [...] })`.
+ *
+ * Registering an id that already exists replaces the factory and re-notifies,
+ * which keeps hot-reload workable.
+ *
+ * @param id - Slot id, conventionally the plugin's own name
+ * @param factory - Builds the control for a given player
+ *
+ * @example
+ * ```ts
+ * registerControl('share', (api) => new ShareButton(api));
+ * ```
+ */
+declare function registerControl(id: string, factory: ControlFactory): void;
+/**
+ * Remove a registered control factory.
+ *
+ * Players already showing the control keep their existing instance until they
+ * rebuild; this only stops future ones being created.
+ *
+ * @param id - Slot id to remove
+ * @returns Whether a factory was registered under that id
+ */
+declare function unregisterControl(id: string): boolean;
+/**
+ * Look up a registered factory.
+ *
+ * @param id - Slot id
+ * @returns The factory, or null when nothing is registered for that id
+ */
+declare function getControlFactory(id: string): ControlFactory | null;
+/**
+ * Clear all registrations and listeners.
+ *
+ * Test-support only — the registry is module-level, so without this a
+ * registration in one test leaks into the next.
+ *
+ * @internal
+ */
+declare function resetControlRegistry(): void;
+
 /**
  * SVG Icons for UI Controls
  *
@@ -148,4 +220,4 @@ declare function formatLiveTime(behindLive: number): string;
  */
 declare function uiPlugin(config?: UIPluginConfig): IUIPlugin;
 
-export { type Control, type ControlSlot, type IUIPlugin, type LayoutConfig, type ThemeConfig, type UIPluginConfig, uiPlugin as default, formatLiveTime, formatTime, icons, styles, uiPlugin };
+export { type BuiltinControlSlot, type Control, type ControlFactory, type ControlSlot, type IUIPlugin, type LayoutConfig, type ThemeConfig, type UIPluginConfig, uiPlugin as default, formatLiveTime, formatTime, getControlFactory, icons, registerControl, resetControlRegistry, styles, uiPlugin, unregisterControl };

package/dist/index.js

@@ -2584,6 +2584,32 @@ var BandwidthIndicator = class {
   }
 };
 
+// src/control-registry.ts
+var registry = /* @__PURE__ */ new Map();
+var listeners = /* @__PURE__ */ new Set();
+function registerControl(id, factory) {
+  registry.set(id, factory);
+  for (const listener of listeners) {
+    listener(id);
+  }
+}
+function unregisterControl(id) {
+  return registry.delete(id);
+}
+function getControlFactory(id) {
+  return registry.get(id) ?? null;
+}
+function onControlRegistered(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function resetControlRegistry() {
+  registry.clear();
+  listeners.clear();
+}
+
 // src/index.ts
 var DEFAULT_LAYOUT = [
   "play",
@@ -2613,6 +2639,7 @@ function uiPlugin(config = {}) {
   let controls = [];
   let hideTimeout = null;
   let stateUnsubscribe = null;
+  let controlRegistryUnsubscribe = null;
   let errorUnsubscribe = null;
   let reconnectingUnsubscribe = null;
   let recoveredUnsubscribe = null;
@@ -2654,10 +2681,43 @@ function uiPlugin(config = {}) {
         return new FullscreenButton(api);
       case "spacer":
         return new Spacer();
-      default:
+      default: {
+        const factory = getControlFactory(slot);
+        if (factory) {
+          try {
+            return factory(api);
+          } catch (error) {
+            api.logger.error(`Control factory for "${slot}" threw`, { error });
+            return null;
+          }
+        }
+        api.logger.warn(`Unknown control slot: ${slot}`);
         return null;
+      }
     }
   };
+  const populateControlBar = () => {
+    if (!controlBar) {
+      return;
+    }
+    for (const slot of layout) {
+      const control = createControl(slot);
+      if (control) {
+        controls.push(control);
+        controlBar.appendChild(control.render());
+      }
+    }
+  };
+  const rebuildControlBar = () => {
+    if (!controlBar) {
+      return;
+    }
+    controls.forEach((c) => c.destroy());
+    controls = [];
+    controlBar.replaceChildren();
+    populateControlBar();
+    updateControls();
+  };
   const updateControls = () => {
     controls.forEach((c) => c.update());
     progressBar?.update();
@@ -2830,14 +2890,15 @@ function uiPlugin(config = {}) {
       controlBar.className = isPlaying ? "sp-controls sp-controls--hidden" : "sp-controls sp-controls--visible";
       controlBar.setAttribute("role", "toolbar");
       controlBar.setAttribute("aria-label", "Video controls");
-      for (const slot of layout) {
-        const control = createControl(slot);
-        if (control) {
-          controls.push(control);
-          controlBar.appendChild(control.render());
-        }
-      }
+      populateControlBar();
       container.appendChild(controlBar);
+      controlRegistryUnsubscribe = onControlRegistered((id) => {
+        if (!layout.includes(id)) {
+          return;
+        }
+        api.logger.debug(`Control "${id}" registered after init, rebuilding control bar`);
+        rebuildControlBar();
+      });
       container.addEventListener("mousemove", handleInteraction);
       container.addEventListener("mouseenter", handleInteraction);
       container.addEventListener("mouseleave", handleMouseLeave);
@@ -2883,6 +2944,8 @@ function uiPlugin(config = {}) {
       }
       document.removeEventListener("keydown", handleKeyDown);
       document.removeEventListener("fullscreenchange", scheduleUpdate);
+      controlRegistryUnsubscribe?.();
+      controlRegistryUnsubscribe = null;
       controls.forEach((c) => c.destroy());
       controls = [];
       progressBar?.destroy();
@@ -2939,7 +3002,11 @@ export {
   index_default as default,
   formatLiveTime,
   formatTime,
+  getControlFactory,
   icons,
+  registerControl,
+  resetControlRegistry,
   styles,
-  uiPlugin
+  uiPlugin,
+  unregisterControl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/ui",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "UI Controls Plugin for Scarlett Player",
   "type": "module",
   "main": "dist/index.cjs",
@@ -29,7 +29,7 @@
     "typescript": "^5.3.0",
     "vitest": "^1.6.0",
     "jsdom": "^24.0.0",
-    "@scarlett-player/core": "1.2.0"
+    "@scarlett-player/core": "1.4.0"
   },
   "keywords": [
     "video",