@discord-player/plugin-host 8.0.0-dev.1 → 8.0.0-dev.3

package/dist/plugins/registry-internals.d.ts

@@ -1,4 +1,4 @@
-import type { DispatchPolicy, HandlerOptions, OperationInput, OperationContext, OperationName, OperationResult, PluginRegistration, SourcePluginContext } from './types.js';
+import type { DispatchPolicy, HandlerOptions, OperationInput, OperationContext, OperationName, OperationResult, PluginRegistration, PluginContext } from './types.js';
 import type { ExecuteOptions } from './execution-options.js';
 /** Internal registration ownership record. */
 export type Entry = {
@@ -7,11 +7,13 @@ export type Entry = {
     /** Registration-local declaration and options. */
     registration: PluginRegistration<any>;
     /** Registration-local setup context. */
-    context: SourcePluginContext<any>;
+    context: PluginContext<any>;
     /** Registration lifetime cancellation. */
     controller: AbortController;
     /** Owned cleanup callbacks in registration order. */
     cleanups: Array<() => void | Promise<void>>;
+    /** Subscriptions owned by this registration, including dynamic additions. */
+    handlers: Set<Handler>;
     /** Handler promises that teardown must drain. */
     pending: Set<Promise<unknown>>;
     /** Setup completion, including failed-setup cleanup. */
@@ -48,7 +50,7 @@ export type OperationRunner = <K extends OperationName>(operation: K, input: Ope
 /** Host state read by operation dispatch. */
 export interface DispatchState {
     /** Subscriptions visible to the current dispatch. */
-    handlers: Handler[];
+    handlers: ReadonlyMap<OperationName, readonly Handler[]>;
     /** Operation dispatch policies. */
     definitions: Map<OperationName, DispatchPolicy>;
     /** Owning Player's disabled provider IDs. */

package/dist/plugins/registry.d.ts

@@ -1,20 +1,47 @@
+import { type SerializedEntityUnion } from '../utils/serde.js';
+import type { Playlist } from '../structures/playlist.js';
+import { type RemotePluginHostOptions } from '../remote.js';
 import type { MediaSource } from '@remedia/client';
 import type { Track } from '../structures/track.js';
 import type { ExecuteOptions, StreamResolutionOptions } from './execution-options.js';
-import type { OperationInput, OperationName, OperationResult, PluginRegistration, SourceOperationMap } from './types.js';
+import type { OperationInput, OperationName, OperationResult, PluginRegistration, ProviderReference, OperationMap, ProviderMap } from './types.js';
 import type { LegacyPlayerContext } from '../legacy-player.js';
 export { PluginError } from './plugin-error.js';
 export type { ExecuteOptions, StreamResolutionOptions } from './execution-options.js';
-/** Context-owned source execution registry. Removal aborts and drains calls before teardown. */
+/** Context-owned capability registry. Removal aborts and drains calls before teardown. */
 export declare class PluginRegistry {
     readonly player: LegacyPlayerContext;
     private readonly blocked;
     private readonly hostId?;
+    private providerNames;
+    private sealedProviders;
+    private providersIndex;
+    /** Enable a local singleton capability before setup. Source hosts do not enable playback providers.
+     * @param name Provider capability name.
+     */
+    defineProvider<K extends keyof ProviderMap>(name: K): void;
+    /** Read the selected provider registration lifetime.
+     * @param name Provider capability name.
+     * @returns Registration cancellation signal, absent for the default implementation.
+     */
+    providerSignal<K extends keyof ProviderMap>(name: K): AbortSignal | undefined;
+    /** Select and seal a provider before resource initialization. Later replacement registrations fail.
+     * @param name Provider capability name.
+     * @param dispose Release owned framework resources before plugin teardown.
+     * @returns The active implementation, or undefined for the framework default.
+     */
+    selectProvider<K extends keyof ProviderMap>(name: K, dispose: () => Promise<void>): ProviderMap[K] | undefined;
+    private advertisements;
     private entries;
     private handlers;
+    private synchronous;
+    private dispatching;
+    private calls;
+    private initializing;
     private order;
     private resultOwners;
     private destroyed;
+    private readonly lifetime;
     /** Create an independent host.
      * @param player Structural source context.
      * @param blocked Default disabled source IDs supplied by the owning Player.
@@ -25,17 +52,61 @@ export declare class PluginRegistry {
     /** Define a declaration-merged operation before registering handlers.
      * @param name Operation name.
      * @param policy Dispatch policy matching its contract.
+     * @param synchronous Whether callbacks must complete before returning; required for interception.
      */
-    defineOperation<K extends OperationName>(name: K, policy: SourceOperationMap[K]['policy']): void;
+    defineOperation<K extends OperationName>(name: K, policy: OperationMap[K]['policy'], synchronous?: boolean): void;
     /** Whether an ID is reserved or active.
      * @param id Plugin ID.
+     * @param hostId Optional deployment constraint.
+     */
+    has(id: string, hostId?: string): boolean;
+    /** List active provider/deployment references in priority and registration order.
+     * @param operation Capability to inspect.
+     * @returns Unique eligible provider/deployment references.
+     */
+    providers(operation: OperationName): ProviderReference[];
+    /** Check whether a deployment has an owned registration.
+     * @param hostId Deployment identity.
+     */
+    hasHost(hostId: string): boolean;
+    /** Advertise only active local operation handlers and supplied provider capabilities.
+     * @returns Serializable provider capability descriptions.
      */
-    has(id: string): boolean;
+    describe(): {
+        id: string;
+        provides: never[];
+        operations: (keyof OperationMap)[];
+        protocols: string[];
+        priorities: {
+            [k: string]: number;
+        };
+        subscriptions: {
+            operation: keyof OperationMap;
+            priority: number;
+            guildIds: readonly string[] | undefined;
+            order: number;
+        }[];
+    }[];
+    /** Register all advertised providers from an existing HTTP deployment.
+     * @param host Existing deployment and authentication.
+     * @param signal Caller lifetime.
+     */
+    registerHost(host: RemotePluginHostOptions, signal?: AbortSignal): Promise<void>;
     /** Whether an active matching handler explicitly accepts a protocol.
      * @param protocol Query prefix without punctuation.
      * @param options Source targeting and block list.
      */
     supportsProtocol(protocol: string, options?: ExecuteOptions): boolean;
+    /** Ordered owners of a custom query protocol.
+     * @param protocol Registered protocol prefix.
+     * @param options Targeting and block list.
+     * @returns Eligible provider identities, in dispatch order.
+     */
+    protocolMatches(protocol: string, options?: ExecuteOptions): {
+        pluginId: string;
+        hostId: string | undefined;
+        score: number;
+    }[];
     /** Register and initialize a source descriptor, reserving its ID synchronously.
      * @param registration Descriptor produced by definePlugin.
      */
@@ -43,13 +114,28 @@ export declare class PluginRegistry {
     private cleanup;
     /** Abort new and active work, drain handlers, and release resources. Handlers must cooperate with cancellation.
      * @param id Plugin ID.
+     * @param hostId Optional deployment identity when the provider exists on multiple hosts.
      * @returns Whether the registration existed.
      */
-    unregister(id: string): Promise<boolean>;
+    unregister(id: string, hostId?: string): Promise<boolean>;
     /** Initialize pending registrations before dispatch. */
     ready(): Promise<void>;
     /** Destroy all registrations, attempting every cleanup even when one fails. */
     destroy(): Promise<void>;
+    /** Whether an operation has active subscribers. Does not scan unrelated registrations.
+     * @param operation Capability name.
+     * @returns Whether at least one active handler exists.
+     */
+    hasCapability(operation: OperationName): boolean;
+    /** Reject reentrant application operations from synchronous capability handlers. */
+    assertNotDispatching(): void;
+    /** Dispatch a synchronous local capability without scheduling promises.
+     * @param operation Capability defined with synchronous execution.
+     * @param input Validated operation payload.
+     * @param options Scope and cancellation constraints.
+     * @returns The selected result, or transformed input for pipe operations.
+     */
+    executeSync<K extends OperationName>(operation: K, input: OperationInput<K>, options?: ExecuteOptions): OperationResult<K>;
     /** Execute using the operation's declared policy. Genuine failures reject immediately.
      * @param operation Typed operation name.
      * @param input Operation payload.
@@ -58,6 +144,18 @@ export declare class PluginRegistry {
      */
     execute<K extends OperationName>(operation: K, input: OperationInput<K>, options?: ExecuteOptions): Promise<OperationResult<K>>;
     private run;
+    /** Serialize using modern application-metadata transformations. Plain model serialization remains synchronous.
+     * @param entity Track or playlist to persist.
+     * @param options Cancellation and provider scope.
+     * @returns A validated JSON persistence payload, without playback grants or live streams.
+     */
+    serialize(entity: Track | Playlist, options?: ExecuteOptions): Promise<SerializedEntityUnion>;
+    /** Restore through modern metadata transformations and the existing schema validator.
+     * @param payload Untrusted persistence payload.
+     * @param options Cancellation and provider scope.
+     * @returns A restored entity without ephemeral playback state.
+     */
+    restore(payload: unknown, options?: ExecuteOptions): Promise<Track | Playlist>;
     /** Resolve and normalize a track for the already selected Remedia node.
      * @param track Data model with a portable provider reference.
      * @param options Target node mode and cancellation.