@discord-player/plugin-host 0.0.0-stage → 8.0.0-dev.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Androz2091
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# @discord-player/plugin-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standalone source execution for Discord Player v8, built on the published
+`@remedia/plugin-host`. Requires Node.js 22.18 or newer.
+
+```text
+discord-player → @discord-player/plugin-host → @remedia/plugin-host
+```
+
+`discord-player` installs this package as a regular dependency and re-exports its
+canonical `BaseExtractor`, `Track`, `Playlist`, `SearchResult`, plugin declarations,
+registry, and serialization classes. Constructor identity and `instanceof` work
+across package imports. No Player, queue manager, Discord client, native audio
+binding, or Remedia audio engine is initialized by importing or creating a host.
+The `@remedia/client` dependency supplies source descriptor types only.
+
+The official `@discord-player/extractor` collection is an optional, separate package.
+It is neither bundled nor automatically registered.
+
+## Registration and direct execution
+
+```ts
+import { createSourcePluginHost, SOURCE_PLUGIN_ID } from '@discord-player/plugin-host';
+import { MyExtractor } from './my-extractor.js';
+import { mySourcePlugin } from './my-source-plugin.js';
+
+const host = createSourcePluginHost({ name: 'My Source Host' });
+await host.extractors.register(MyExtractor);
+await host.plugins.register(mySourcePlugin());
+
+const response = await host.handle({
+  pluginId: SOURCE_PLUGIN_ID,
+  operation: 'source.search',
+  input: { query: 'example' },
+});
+if (response.handled) console.log(response.result);
+// Or use typed source APIs directly:
+const result = await host.runtime.search('example');
+const track = result.first();
+if (track) {
+  const source = await host.plugins.resolveStream(track);
+  // Caller owns consumption and destruction of returned Readables.
+  console.log(source);
+}
+await host.close();
+```
+
+Direct execution preserves model and stream references. It needs no public URL,
+listener, or serialization. `host.remedia` exposes the actual generic Remedia host
+for discovery and lifecycle inspection; use `host.handle` and `host.fetch` as the
+application entrypoints, so the boundary conversion remains active.
+
+Both Player and standalone execution use `SourcePluginRuntime`. There is one
+registry with the existing `first`, `collect`, `pipe`, and `broadcast` policies,
+provider priorities, protocol matching, bridging, registration cancellation,
+post-stream transforms, and cleanup ownership. Player retains all queue, voice,
+Gateway, crossfade, and playback orchestration.
+
+## Hono
+
+```ts
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { createSourcePluginHost } from '@discord-player/plugin-host';
+import { MyExtractor } from './my-extractor.js';
+
+const host = createSourcePluginHost({ name: 'Sources', publicUrl: 'http://localhost:3000' });
+await host.extractors.register(MyExtractor);
+const app = new Hono();
+app.all('*', (c) => host.fetch(c.req.raw));
+const server = serve({ fetch: app.fetch, port: 3000 });
+process.once('SIGTERM', () => {
+  server.close();
+  void host.close();
+});
+```
+
+## Express
+
+Mount Remedia's existing middleware at the origin root before body parsers.
+
+```ts
+import express from 'express';
+import { createNodeMiddleware } from '@remedia/plugin-host/node';
+import { createSourcePluginHost } from '@discord-player/plugin-host';
+import { MyExtractor } from './my-extractor.js';
+
+const host = createSourcePluginHost({ name: 'Sources', publicUrl: 'http://localhost:3000' });
+await host.extractors.register(MyExtractor);
+const app = express();
+app.use(createNodeMiddleware(host));
+app.use(express.json());
+const server = app.listen(3000);
+process.once('SIGTERM', () => {
+  server.close();
+  void host.close();
+});
+```
+
+No listener starts automatically. Remedia owns HTTP routing, authorization,
+request limits, media tokens, backpressure, stream cancellation, and disposal.
+Configure `token`, `mediaTtlMs`, and `maxMediaTokens` through the host options.
+`publicUrl` is a trusted HTTP(S) origin and is needed only for HTTP media results.
+
+## HTTP source contract
+
+One aggregate registration, `discord-player.source`, advertises:
+
+| Operation        | Input                           | Result                                     |
+| ---------------- | ------------------------------- | ------------------------------------------ |
+| `source.search`  | `{ query, options? }`           | Metadata through normal provider matching  |
+| `source.resolve` | `{ query, pluginId, options? }` | Metadata from an explicit provider         |
+| `source.related` | `{ track }`                     | Related metadata from the track's provider |
+| `source.stream`  | `{ track }`                     | Deferred Remedia media descriptor          |
+
+`source.stream` includes normal bridge fallback and post-stream transformations;
+internal operation handlers are not separate Remedia registrations. HTTP options
+accept portable plugin/source/searchEngine hints, limit, requester ID, and blocked
+provider IDs. Local HTTP request options, functions and Discord objects do not
+cross the boundary. The transport validates input before source execution.
+
+```ts
+import { SOURCE_PLUGIN_ID, deserializeSourceResult, type PortableSourceResult } from '@discord-player/plugin-host';
+
+const response = await fetch('http://localhost:3000/remedia/v1/execute', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ pluginId: SOURCE_PLUGIN_ID, operation: 'source.search', input: { query: 'example' } }),
+});
+if (!response.ok) throw new Error(`Source search failed: ${response.status}`);
+const search = (await response.json()) as { handled: boolean; result: PortableSourceResult };
+if (!search.handled) throw new Error('Unhandled search');
+const localModels = deserializeSourceResult(search.result);
+console.log(localModels.first());
+
+// Send the original portable representation back, including its optional state hint.
+const mediaResponse = await fetch('http://localhost:3000/remedia/v1/execute', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    pluginId: SOURCE_PLUGIN_ID,
+    operation: 'source.stream',
+    input: { track: search.result.tracks[0] },
+  }),
+});
+if (!mediaResponse.ok) throw new Error(`Source stream failed: ${mediaResponse.status}`);
+const media = (await mediaResponse.json()) as { handled: boolean; result: { url: string; expiresAtMs: number } };
+if (!media.handled) throw new Error('Unhandled media');
+// Redeem media.result.url before expiresAtMs; this is a short-lived, single-use grant.
+const bytes = await fetch(media.result.url);
+console.log(bytes.body);
+```
+
+Media resolution starts when the grant is redeemed, using that request's
+cancellation signal rather than the completed JSON request's signal. Readables,
+files, buffers, and upstream HTTP(S) URLs become encoded byte streams before
+post-stream transforms. URLs are proxied inside the host so provider resolution
+and transforms remain there. The adapter never buffers complete media files.
+Direct calls retain native descriptors; HTTP never returns nested Readables.
+
+## Portable metadata and process-local state
+
+HTTP results contain version 1 Track and Playlist data. A `PortableSourceTrack`
+adds an optional opaque `sourceState` field. `deserializeSourceResult()` removes
+that transport extension before strict versioned deserialization and links the
+shared Track instances to their Playlist. For raw `deserialize()`, remove the
+`sourceState` extension first. Provider identity remains in `sourceReference`.
+
+The host retains original Track objects (including `raw.engine`, extractor
+identity and metadata callbacks) in a bounded cache: 10000 tracks and one hour by
+default, configurable with `maxTrackStates` and `trackStateTtlMs`. Expiration is
+checked on use; eviction releases references. Cache entries are invalidated by
+provider removal and host shutdown. No media streams are retained by this cache.
+
+After eviction, expiration, or restart, modern plugins receive reconstructed
+Track metadata and their portable sourceReference. Legacy extractors re-run
+`handle()` through their original provider using the public Track URL, select the
+matching URL, and then receive the newly constructed Track in `stream()`. If the
+provider is unavailable or cannot reconstruct the track, execution fails with an
+explicit diagnostic. This means queued tracks can survive cache loss when their
+provider supports URL reconstruction; ephemeral-only sources must be searched
+again. A serialized Track is never a promise of permanent source availability.
+
+Raw engines, credentials, functions, live streams, circular objects and legacy
+metadata callbacks are never serialized. Modern metadata and sourceReference
+must follow the existing JSON-safe contract; plugins must put only public source
+identifiers there, never secrets. Invalid metadata fails serialization rather
+than being silently removed. Credentials belong to host-local plugin options.
+
+## Legacy compatibility
+
+The audited v7 extractors use `this.context.player` for Track/Playlist construction,
+source lookup/bridging, diagnostics and `probeTimeout`. `LegacyPlayerContext` is a
+structural source API, backed by the runtime when standalone and by the actual
+Player when embedded. It supports plugins, extractors, search, debug/error events,
+source options, and legacy constructors. Optional `getRemedia(false)` returns
+null standalone; required audio access and queue/voice operations fail explicitly.
+It never instantiates a dummy Player, queue or voice connection.
+
+Legacy raw PCM/Opus override streams remain unsupported: return encoded media.
+Queue history, Discord clients and other process-local playback objects are not
+part of HTTP requests. An extractor that needs arbitrary Player/voice APIs or
+cannot reconstruct private state after expiration requires migration; the source
+compatibility surface does not emulate the whole Player API.
+
+## Remedia server integration boundary
+
+The inspected Remedia Rust sources do not implement plugin-host discovery or
+source operation routing. Creating a remote Remedia client does not register this
+host with an audio server. A bot can call this HTTP protocol explicitly and redeem
+the media descriptor, or pass a reachable descriptor URL to supported playback
+APIs before the grant expires. Automatic Rust-side routing still requires host
+configuration/discovery, authenticated operation execution, sourceReference
+round-tripping, cancellation, and timely media-grant redemption. No new Rust API,
+custom IPC transport or automatic remote registry is claimed by this package.
+
+## Validation
+
+`pnpm build`, `pnpm typecheck`, `pnpm test`, `pnpm lint`, and `pnpm format:check`
+cover the workspace. Source tests use synthetic encoded bytes and local fixtures,
+without public media-provider access. CI builds the host before discord-player,
+includes its dist artifacts, and publishes it before dependent packages using the
+shared release inventory.

package/dist/compat/base-extractor.d.ts

@@ -0,0 +1,88 @@
+import type { Readable } from 'node:stream';
+import type { SourceRuntimeEvents } from '../legacy-player.js';
+import type { Track } from '../structures/track.js';
+import type { Playlist } from '../structures/playlist.js';
+import type { ExtractorExecutionContext } from './extractor-execution-context.js';
+import type { SearchQueryType } from './query-types.js';
+import type { ExtractorInfo, ExtractorSearchContext, ExtractorStreamable, NextFunction } from './extractor-types.js';
+/** Minimal v7 lifecycle and source API, adapted to the source operation registry. */
+export declare class BaseExtractor<Options extends object = object> {
+    /** Owning legacy registration context. */
+    context: ExtractorExecutionContext;
+    /** Original local extractor configuration. */
+    options: Options;
+    /** Default identifier; subclasses should override. */
+    static identifier: string;
+    /** Higher priority wins before match confidence. */
+    priority: number;
+    /** Supported explicit query protocols. */
+    protocols: string[];
+    /** Create a compatibility instance; use player.extractors.register to own it.
+     * @param context Owning compatibility context.
+     * @param options Original extractor options.
+     */
+    constructor(
+    /** Owning legacy registration context. */
+    context: ExtractorExecutionContext, 
+    /** Original local extractor configuration. */
+    options?: Options);
+    /** Subclass static identifier. */
+    get identifier(): string;
+    /** Obsolete demux support is unavailable. */
+    get supportsDemux(): boolean;
+    /** Acquire extractor resources. */
+    activate(): Promise<void>;
+    /** Release extractor resources. */
+    deactivate(): Promise<void>;
+    /** Recreate the owned registration with new options.
+     * @param options Replacement options.
+     */
+    reconfigure(options: Options): Promise<void>;
+    /** Test whether this extractor accepts a query.
+     * @param query Search text.
+     * @param type Query hint.
+     */
+    validate(query: string, type?: SearchQueryType | null): Promise<boolean>;
+    /** Resolve metadata.
+     * @param query Search text.
+     * @param context Search hints.
+     */
+    handle(query: string, context: ExtractorSearchContext): Promise<ExtractorInfo>;
+    /** Resolve media, or decline to enable bridging.
+     * @param track Track to stream.
+     */
+    stream(track: Track): Promise<ExtractorStreamable | undefined>;
+    /** Resolve related metadata.
+     * @param track Seed track.
+     * @param history Optional queue history; local execution only.
+     */
+    getRelatedTracks(track: Track, history?: unknown): Promise<ExtractorInfo>;
+    /** Explicit fallback for another source.
+     * @param track Track needing a stream.
+     * @param sourceExtractor Original extractor, if legacy.
+     */
+    bridge(track: Track, sourceExtractor: BaseExtractor<any> | null): Promise<ExtractorStreamable | null>;
+    /** Transform an encoded local Readable. Raw codec overrides are unsupported.
+     * @param stream Encoded input.
+     * @param next Completion callback.
+     */
+    handlePostStream(stream: Readable, next: NextFunction): void;
+    /** Build an anonymous bridge query.
+     * @param track Track metadata.
+     */
+    createBridgeQuery(track: Track): string;
+    /** Construct a metadata response.
+     * @param playlist Optional playlist.
+     * @param tracks Ordered tracks, defaulting to playlist entries.
+     */
+    createResponse(playlist?: Playlist | null, tracks?: Track[]): ExtractorInfo;
+    /** Publish a diagnostic.
+     * @param message Diagnostic text.
+     */
+    debug(message: string): void;
+    /** Forward supported Player events.
+     * @param event Player event.
+     * @param args Event arguments.
+     */
+    emit<K extends keyof SourceRuntimeEvents>(event: K, ...args: SourceRuntimeEvents[K]): boolean;
+}

package/dist/compat/base-extractor.js

@@ -0,0 +1,118 @@
+/** Minimal v7 lifecycle and source API, adapted to the source operation registry. */
+export class BaseExtractor {
+    context;
+    options;
+    /** Default identifier; subclasses should override. */
+    static identifier = 'org.example.extractor';
+    /** Higher priority wins before match confidence. */
+    priority = 1;
+    /** Supported explicit query protocols. */
+    protocols = [];
+    /** Create a compatibility instance; use player.extractors.register to own it.
+     * @param context Owning compatibility context.
+     * @param options Original extractor options.
+     */
+    constructor(
+    /** Owning legacy registration context. */
+    context, 
+    /** Original local extractor configuration. */
+    options = {}) {
+        this.context = context;
+        this.options = options;
+    }
+    /** Subclass static identifier. */
+    get identifier() {
+        return this.constructor.identifier;
+    }
+    /** Obsolete demux support is unavailable. */
+    get supportsDemux() {
+        return false;
+    }
+    /** Acquire extractor resources. */
+    async activate() { }
+    /** Release extractor resources. */
+    async deactivate() { }
+    /** Recreate the owned registration with new options.
+     * @param options Replacement options.
+     */
+    async reconfigure(options) {
+        await this.context.reconfigure(this.identifier, options);
+    }
+    /** Test whether this extractor accepts a query.
+     * @param query Search text.
+     * @param type Query hint.
+     */
+    async validate(query, type) {
+        void query;
+        void type;
+        return false;
+    }
+    /** Resolve metadata.
+     * @param query Search text.
+     * @param context Search hints.
+     */
+    async handle(query, context) {
+        void query;
+        void context;
+        return this.createResponse();
+    }
+    /** Resolve media, or decline to enable bridging.
+     * @param track Track to stream.
+     */
+    async stream(track) {
+        void track;
+        return undefined;
+    }
+    /** Resolve related metadata.
+     * @param track Seed track.
+     * @param history Optional queue history; local execution only.
+     */
+    async getRelatedTracks(track, history) {
+        void track;
+        void history;
+        return this.createResponse();
+    }
+    /** Explicit fallback for another source.
+     * @param track Track needing a stream.
+     * @param sourceExtractor Original extractor, if legacy.
+     */
+    async bridge(track, sourceExtractor) {
+        void track;
+        void sourceExtractor;
+        return null;
+    }
+    /** Transform an encoded local Readable. Raw codec overrides are unsupported.
+     * @param stream Encoded input.
+     * @param next Completion callback.
+     */
+    handlePostStream(stream, next) {
+        next(null, stream);
+    }
+    /** Build an anonymous bridge query.
+     * @param track Track metadata.
+     */
+    createBridgeQuery(track) {
+        return `${track.title} by ${track.author}`;
+    }
+    /** Construct a metadata response.
+     * @param playlist Optional playlist.
+     * @param tracks Ordered tracks, defaulting to playlist entries.
+     */
+    createResponse(playlist = null, tracks = playlist?.tracks ?? []) {
+        return { playlist, tracks };
+    }
+    /** Publish a diagnostic.
+     * @param message Diagnostic text.
+     */
+    debug(message) {
+        this.context.player.debug(message);
+    }
+    /** Forward supported Player events.
+     * @param event Player event.
+     * @param args Event arguments.
+     */
+    emit(event, ...args) {
+        return this.context.player.emit(event, ...args);
+    }
+}
+//# sourceMappingURL=base-extractor.js.map

package/dist/compat/base-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-extractor.js","sourceRoot":"","sources":["../../src/compat/base-extractor.ts"],"names":[],"mappings":"AAQA,qFAAqF;AACrF,MAAM,OAAO,aAAa;IAgBf,OAAO;IAEP,OAAO;IAjBhB,sDAAsD;IAC/C,MAAM,CAAC,UAAU,GAAG,uBAAuB,CAAC;IAEnD,oDAAoD;IAC7C,QAAQ,GAAG,CAAC,CAAC;IAEpB,0CAA0C;IACnC,SAAS,GAAa,EAAE,CAAC;IAEhC;;;OAGG;IACH;IACE,0CAA0C;IACnC,OAAkC;IACzC,8CAA8C;IACvC,OAAO,GAAY,EAAa;uBAFhC,OAAO;uBAEP,OAAO;IACb,CAAC;IAEJ,kCAAkC;IAClC,IAAW,UAAU;QACnB,OAAQ,IAAI,CAAC,WAAoC,CAAC,UAAU,CAAC;IAC/D,CAAC;IAED,6CAA6C;IAC7C,IAAW,aAAa;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mCAAmC;IAC5B,KAAK,CAAC,QAAQ,KAAmB,CAAC;IAEzC,mCAAmC;IAC5B,KAAK,CAAC,UAAU,KAAmB,CAAC;IAE3C;;OAEG;IACI,KAAK,CAAC,WAAW,CAAC,OAAgB;QACvC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,IAA6B;QAChE,KAAK,KAAK,CAAC;QACX,KAAK,IAAI,CAAC;QAEV,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAA+B;QAChE,KAAK,KAAK,CAAC;QACX,KAAK,OAAO,CAAC;QAEb,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,MAAM,CAAC,KAAY;QAC9B,KAAK,KAAK,CAAC;QAEX,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,gBAAgB,CAAC,KAAY,EAAE,OAAiB;QAC3D,KAAK,KAAK,CAAC;QACX,KAAK,OAAO,CAAC;QAEb,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM,CAAC,KAAY,EAAE,eAA0C;QAC1E,KAAK,KAAK,CAAC;QACX,KAAK,eAAe,CAAC;QAErB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACI,gBAAgB,CAAC,MAAgB,EAAE,IAAkB;QAC1D,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACI,iBAAiB,CAAC,KAAY;QACnC,OAAO,GAAG,KAAK,CAAC,KAAK,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACI,cAAc,CAAC,QAAQ,GAAoB,IAAI,EAAE,MAAM,GAAY,QAAQ,EAAE,MAAM,IAAI,EAAE;QAC9F,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,OAAe;QAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,IAAI,CAAsC,KAAQ,EAAE,GAAG,IAA4B;QACxF,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,GAAI,IAAc,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/compat/extractor-execution-context.d.ts

@@ -0,0 +1,69 @@
+import type { LegacyPlayerContext } from '../legacy-player.js';
+import type { Track } from '../structures/track.js';
+import type { SourceStream } from '../plugins/types.js';
+import { BaseExtractor } from './base-extractor.js';
+import type { ExtractorConstructor } from './extractor-types.js';
+/** Small legacy ownership adapter; all execution goes through player.plugins. */
+export declare class ExtractorExecutionContext {
+    /** Player owning legacy registrations. */
+    readonly player: LegacyPlayerContext;
+    private bridgeAttempts;
+    private instances;
+    /** Read-only view of registered legacy instances. */
+    get store(): ReadonlyMap<string, BaseExtractor<any>>;
+    /** Number of legacy registrations. */
+    get size(): number;
+    /** Create an adapter owned by one Player.
+     * @param player Owning Player.
+     */
+    constructor(
+    /** Player owning legacy registrations. */
+    player: LegacyPlayerContext);
+    /** Look up a legacy registration.
+     * @param id Extractor identifier.
+     */
+    get(id: string): BaseExtractor<any> | undefined;
+    /** Test legacy registration membership.
+     * @param id Extractor identifier.
+     */
+    isRegistered(id: string): boolean;
+    /** Check the Player block list.
+     * @param id Extractor identifier.
+     */
+    isDisabled(id: string): boolean;
+    /** Check whether a source is allowed.
+     * @param id Extractor identifier.
+     */
+    isEnabled(id: string): boolean;
+    /** Register a legacy class through a source plugin.
+     * @param Extractor Legacy BaseExtractor subclass constructor.
+     * @param options Original options passed to the instance.
+     * @returns The owned compatibility instance.
+     */
+    register<C extends ExtractorConstructor>(Extractor: C, ...args: {} extends ConstructorParameters<C>[1] ? [options?: ConstructorParameters<C>[1]] : [options: ConstructorParameters<C>[1]]): Promise<InstanceType<C>>;
+    /** Remove an extractor and its source subscriptions.
+     * @param extractor ID or owned instance.
+     */
+    unregister(extractor: string | BaseExtractor<any>): Promise<boolean>;
+    /** Remove all legacy registrations. */
+    unregisterAll(): Promise<void>;
+    /** Replace an instance through the same registration path.
+     * @param id Legacy ID.
+     * @param options Replacement options.
+     */
+    reconfigure(id: string, options: object): Promise<BaseExtractor<any>>;
+    /** Register a bundle sequentially with deterministic precedence.
+     * @param bundle Legacy constructors.
+     * @param options Options keyed by identifier.
+     */
+    loadMulti(bundle: readonly ExtractorConstructor[], options?: Record<string, object>): Promise<void>;
+    /** Request explicit bridge fallback using the shared registry.
+     * @param track Track needing a bridge.
+     * @param sourceExtractor Original provider.
+     */
+    requestBridge(track: Track, sourceExtractor?: BaseExtractor<any> | null): Promise<{
+        result: SourceStream;
+        error: null;
+        extractor: BaseExtractor<any> | null;
+    }>;
+}

package/dist/compat/extractor-execution-context.js

@@ -0,0 +1,121 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Collection } from '@discordjs/collection';
+import { BaseExtractor } from './base-extractor.js';
+import { createExtractorPlugin } from './extractor-plugin.js';
+/** Small legacy ownership adapter; all execution goes through player.plugins. */
+export class ExtractorExecutionContext {
+    player;
+    bridgeAttempts = new AsyncLocalStorage();
+    instances = new Collection();
+    /** Read-only view of registered legacy instances. */
+    get store() {
+        return this.instances;
+    }
+    /** Number of legacy registrations. */
+    get size() {
+        return this.instances.size;
+    }
+    /** Create an adapter owned by one Player.
+     * @param player Owning Player.
+     */
+    constructor(
+    /** Player owning legacy registrations. */
+    player) {
+        this.player = player;
+    }
+    /** Look up a legacy registration.
+     * @param id Extractor identifier.
+     */
+    get(id) {
+        return this.instances.get(id);
+    }
+    /** Test legacy registration membership.
+     * @param id Extractor identifier.
+     */
+    isRegistered(id) {
+        return this.instances.has(id);
+    }
+    /** Check the Player block list.
+     * @param id Extractor identifier.
+     */
+    isDisabled(id) {
+        return this.player.options.blockExtractors?.includes(id) ?? false;
+    }
+    /** Check whether a source is allowed.
+     * @param id Extractor identifier.
+     */
+    isEnabled(id) {
+        return !this.isDisabled(id);
+    }
+    /** Register a legacy class through a source plugin.
+     * @param Extractor Legacy BaseExtractor subclass constructor.
+     * @param options Original options passed to the instance.
+     * @returns The owned compatibility instance.
+     */
+    async register(Extractor, ...args) {
+        if (typeof Extractor !== 'function' ||
+            !(Extractor.prototype instanceof BaseExtractor) ||
+            typeof Extractor.identifier !== 'string') {
+            throw new TypeError('extractors.register expects a BaseExtractor subclass constructor.');
+        }
+        const instance = new Extractor(this, args[0] ?? {});
+        const plugin = createExtractorPlugin(instance, this, () => this.bridgeAttempts.getStore(), () => {
+            this.instances.set(instance.identifier, instance);
+        }, () => {
+            if (this.instances.get(instance.identifier) === instance) {
+                this.instances.delete(instance.identifier);
+            }
+        });
+        await this.player.plugins.register(plugin());
+        return instance;
+    }
+    /** Remove an extractor and its source subscriptions.
+     * @param extractor ID or owned instance.
+     */
+    async unregister(extractor) {
+        return this.player.plugins.unregister(typeof extractor === 'string' ? extractor : extractor.identifier);
+    }
+    /** Remove all legacy registrations. */
+    async unregisterAll() {
+        for (const id of this.instances.keys()) {
+            await this.unregister(id);
+        }
+    }
+    /** Replace an instance through the same registration path.
+     * @param id Legacy ID.
+     * @param options Replacement options.
+     */
+    async reconfigure(id, options) {
+        const instance = this.get(id);
+        if (!instance) {
+            throw new Error(`Unknown extractor: ${id}`);
+        }
+        const Constructor = instance.constructor;
+        await this.unregister(id);
+        return this.register(Constructor, options);
+    }
+    /** Register a bundle sequentially with deterministic precedence.
+     * @param bundle Legacy constructors.
+     * @param options Options keyed by identifier.
+     */
+    async loadMulti(bundle, options = {}) {
+        for (const Constructor of bundle) {
+            await this.register(Constructor, options[Constructor.identifier] ?? {});
+        }
+    }
+    /** Request explicit bridge fallback using the shared registry.
+     * @param track Track needing a bridge.
+     * @param sourceExtractor Original provider.
+     */
+    async requestBridge(track, sourceExtractor = track.extractor) {
+        const dispatch = () => this.player.plugins.execute('track.bridge', { track, sourcePluginId: sourceExtractor?.identifier }, { blocked: this.player.options.blockExtractors });
+        const result = this.bridgeAttempts.getStore()
+            ? await dispatch()
+            : await this.bridgeAttempts.run(new Set(), dispatch);
+        if (result === undefined) {
+            throw new Error('No source plugin handled track.bridge');
+        }
+        return { result, error: null, extractor: track.bridgedExtractor };
+    }
+}
+//# sourceMappingURL=extractor-execution-context.js.map

package/dist/compat/extractor-execution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor-execution-context.js","sourceRoot":"","sources":["../../src/compat/extractor-execution-context.ts"],"names":[],"mappings":"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"}

package/dist/compat/extractor-plugin.d.ts

@@ -0,0 +1 @@
+export {};