Plugin Standard, v1.0

static readonly id: string;          // vendored: 'lyrics', 'fillz:viz'
static readonly version: string;     // semver: '1.0.0'
static readonly description: string; // one-line, shown in errors + listings
static readonly minCoreVersion?: string; // optional minimum core version

// Author-overridable hooks:
use(): void | Promise<void>                // wire listeners, mount DOM, fetch resources
dispose(): void                            // explicit teardown

// Internal (base class, never override, never call from your plugin):
initialize(player, opts, lifecycle): void  // core calls this before use() to inject player + opts + lifecycle

enabled(): boolean           // is the plugin active?
enable(): void               // re-activate. Idempotent.
disable(): void              // deactivate without unloading. Idempotent.
state(): PluginState<O>      // { id, version, enabled, opts, runtime }
options(): Readonly<O>       // current options (read)
options(partial): void       // shallow-merge patch (write), emits opts:changed

options(patch: Partial<O>) {
  super.options(patch);

  if ('endpoint' in patch) this.reconnect();
}

// Fire-and-forget, auto-namespaced to plugin:<id>:<name>:
this.emit('dataFetched', { count: 5 });

// Cancellable, mutable, async-aware:
const result = await this.dispatchBefore('beforeSetBand', { index, gain });
if (result.prevented) return;
this.applyBand(result.data.index, result.data.gain);
this.emit('band:changed', result.data);

export interface MyPluginEvents {
  'dataFetched': { count: number };
}
export class MyPlugin extends Plugin<..., MyPluginEvents> { ... }
export type { MyPluginEvents };

// Player / core events:
this.on('time', ({ time }) => {
  /* typed */
});

// Cross-plugin events, typed via imported class:
this.on(EqualizerPlugin, 'band:changed', ({ band }) => {
  // band is EqBand, typed from EqualizerPlugin's E generic
});

const result = await this.dispatchBefore('beforeSetBand', { index, gain });

interface BeforeEvent<TData> {
  data: TData; // mutable, player reads back after dispatch
  preventDefault(): void; // skip the default action
  isDefaultPrevented(): boolean;
  stopImmediatePropagation(): void; // skip remaining listeners
  isPropagationStopped(): boolean;
  delay(promise: Promise<unknown>): void; // async-gate the action
  isDelayed(): boolean;
}

// Fatal: surfaces the error and aborts the current flow. Does NOT auto-disable
// the plugin — map the code to 'disable' in static onError for that.
this.throw({
  severity: 'fatal',
  code: 'my-plugin/connection-lost',
  message: '...',
});

// Non-fatal: operation fails, plugin keeps running.
this.throw({
  severity: 'error',
  code: 'my-plugin/fetch-failed',
  message: '...',
});

// Degradation: plugin survives, caller continues.
this.report({
  severity: 'warning',
  code: 'my-plugin/rate-limited',
  message: '...',
});

// Observability.
this.report({
  severity: 'info',
  code: 'my-plugin/cache-hit',
  message: '...',
});

class MyPlugin extends Plugin {
  use() {
    super.use();
    this.addPlaybackHooks();
    this.addNavigationHooks();
  }
  protected addPlaybackHooks() {
    /* ... */
  }
  protected addNavigationHooks() {
    /* ... */
  }
}

class MediaSessionPlugin extends Plugin {
  protected getMetadata(item: T): MediaSessionMetadata { /* default */ }
}

class MyMediaSession extends MediaSessionPlugin {
  protected getMetadata(item: T): MediaSessionMetadata {
    return { title: item.localizedTitle };
  }
}

async use() {
  const config = await this.fetch(this.opts.configUrl, { responseType: 'json' });
  this.bindConfig(config);
}

class MyPlugin extends Plugin {
  static readonly requires = [
    AudioGraphPlugin, // required
    { plugin: MediaSessionPlugin, optional: true }, // optional
    { plugin: SpectrumPlugin, minVersion: '2.1.0' }, // version-pinned
  ];
}

async setBand(index: number, gain: number) {
  const result = await this.dispatchBefore('beforeSetBand', { index, gain });
  if (result.prevented) return;
  this.applyBand(result.data.index, result.data.gain);
  this.emit('band:changed', result.data);
}

static readonly advisories: PluginAdvisory[] = [
  {
    method: 'setCurrent',
    duringPhase: ['playing'],
    severity: 'warning',
    reason: 'crossfade-disrupt',
    message: 'Changing current track during playback skips the crossfade scheduler.',
  },
];

class CapacitorMediaSession extends Plugin {
  static readonly id = 'media-session';
  static readonly replaces = 'media-session';
}
player.addPlugin(CapacitorMediaSession);

class CriticalPlugin extends Plugin {
  static readonly priority = 100; // higher = earlier; default 0
}

use() {
  const root = this.mount('toast'); // returns a div appended to player.container
  // auto-removed on dispose
}

this.storage.get('volume'); // reads 'nmplayer-<plugin-id>-volume'
this.storage.set('volume', 0.8);

this.logger.debug('something'); // outputs [nmplayer][my-plugin] something

[]['beforePlay'][('beforePlay', 'beforeMutation')]; // no event in flight // inside a beforePlay listener // nested

interface PluginAdvisory {
  method: string;
  duringPhase?: PlayerPhase | PlayerPhase[];
  duringEvent?: string | string[];
  severity: 'info' | 'warning' | 'error';
  reason: string;
  message: string;
}

class MyPlugin extends Plugin {
  static readonly onError = {
    'core:cue/load-failed': 'retry-once',
    'core:auth/forbidden': 'disable',
  };
}

class CapacitorMediaSession extends Plugin {
  static readonly id = 'media-session';
  static readonly replaces = 'media-session';
}

class MyKeyHandler extends KeyHandlerPlugin {
  static readonly id = 'key-handler';
  protected addPlaybackKeys() {
    this.bind('p', (player) => player.play());
  }
}

const StrictMediaSession = MediaSessionPlugin.derive({ requireMetadata: true });

const restore = player.experimental.override('subtitles', () => mySubtitles);
// call restore() to undo — there is no auto-restore on dispose

import {
  assertNoListenerLeak,
  createStubPlayer,
} from '@nomercy-entertainment/nomercy-player-core/testing';
import { LifecycleRegistry } from '@nomercy-entertainment/nomercy-player-core';

// describePlugin auto-asserts no listener leak after every test.
// Use assertNoListenerLeak directly when you need an explicit stand-alone check:
test('no listener leak', async () => {
  const player = createStubPlayer();
  const plugin = new MyPlugin();
  const lifecycle = new LifecycleRegistry();

  await assertNoListenerLeak({
    subjectId: 'my-plugin',
    player,
    setup: async () => {
      plugin.initialize(player, {}, lifecycle);
      await plugin.use();
    },
    teardown: () => {
      plugin.dispose();
      lifecycle.dispose();
    },
  });
});

import { describePlugin } from '@nomercy-entertainment/nomercy-player-core/testing';

describePlugin(MyPlugin, ({ player, plugin }) => {
  test('emits dataFetched on track change', async () => {
    const events: unknown[] = [];
    player.on('plugin:my-plugin:dataFetched', (event) => events.push(event));
    // Trigger the event the plugin listens for to drive the behavior under test:
    player.emit('current', { item: { id: '1', name: 'Track', url: '...' } });
    await vi.waitFor(() => events.length > 0);
    expect(events[0]).toMatchObject({ count: expect.any(Number) });
  });
});