@nuclearplayer/plugin-sdk 0.0.9

package/README.md

@@ -0,0 +1,164 @@
+# Nuclear Plugin SDK
+
+Official toolkit for building Nuclear plugins.
+
+## 1. What Is A Nuclear Plugin?
+A small JavaScript/TypeScript bundle that exports lifecycle hooks and ships with a `package.json` describing metadata (display name, icon, permissions, etc.). The app reads the manifest for metadata, then loads and executes your exported hooks in-process.
+
+## 2. Quick Start
+```bash
+mkdir my-plugin && cd my-plugin
+pnpm init -y
+pnpm add @nuclearplayer/plugin-sdk
+# add dev tooling of your choice (vite, tsup, esbuild, rollup)
+```
+
+Create `src/index.ts`:
+```ts
+import { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';
+
+export default {
+  async onLoad(api: NuclearPluginAPI) {
+  },
+  async onEnable(api: NuclearPluginAPI) {
+  },
+  async onDisable() {
+  },
+  async onUnload() {
+  },
+};
+```
+
+Bundle to `dist/index.js` (or set a custom `main`). Ensure the output is a CommonJS style bundle (assigns to `module.exports` or `exports.default`).
+
+## 3. Manifest (package.json) Specification
+Required top-level fields:
+- `name`: Unique plugin id (used internally). Scoped names allowed.
+- `version`: Semver string.
+- `description`: One line summary shown to users.
+- `author`: Plain string.
+
+Optional standard fields:
+- `main`: Entry file path relative to package root. If omitted the loader tries `index.js` then `dist/index.js`.
+
+Optional Nuclear namespace (`nuclear`):
+- `displayName`: Friendly name (falls back to `name`).
+- `category`: Arbitrary grouping (examples: `source`, `integration`, `lyrics`, `utility`).
+- `icon`: See Icon spec below.
+- `permissions`: String array of declared capabilities (informational only right now).
+
+Example:
+```json
+{
+  "name": "@nuclear-plugin/lastfm",
+  "version": "0.1.0",
+  "description": "Scrobble tracks to Last.fm",
+  "author": "Nuclear Team",
+  "main": "dist/index.js",
+  "nuclear": {
+    "displayName": "Last.fm Scrobbler",
+    "category": "integration",
+    "icon": { "type": "link", "link": "https://example.com/icon.png" },
+    "permissions": ["scrobble", "network"]
+  }
+}
+```
+
+## 4. Icon Specification
+```ts
+type PluginIcon = { type: 'link'; link: string };
+```
+Link icons should point to a local file path or remote URL; keep them small (<= 64x64, optimized).
+
+## 5. Lifecycle Hooks
+All hooks are optional. Export a default object containing any of:
+- `onLoad(api)`: Runs after the plugin code is first evaluated and manifest metadata processed.
+- `onEnable(api)`: Runs when user enables the plugin (may happen multiple times across sessions).
+- `onDisable()`: Runs when disabled.
+- `onUnload()`: Runs before the plugin is fully removed from memory.
+
+Typical pattern:
+```ts
+export default {
+  async onLoad(api) {
+  },
+  async onEnable(api) {
+  },
+  async onDisable() {
+  },
+  async onUnload() {
+  },
+};
+```
+
+## 6. Permissions
+`permissions` is currently informational. Declare high-level capabilities your plugin intends to use (network, scrobble, playback-control, lyrics, search, storage, etc.). Future versions may expose UI around this.
+
+## 7. File Structure Example
+```text
+my-plugin/
+  package.json
+  README.md
+  src/
+    index.ts
+  dist/
+    index.js        (built output)
+  node_modules/
+```
+
+## 8. Building Your Plugin
+You can use any bundler that outputs a single JS file that the loader can evaluate in a CommonJS style environment.
+
+Example minimal `tsup` config (optional):
+```jsonc
+// package.json excerpt
+"devDependencies": { "tsup": "^8" },
+"scripts": { "build": "tsup src/index.ts --dts --format cjs --minify --out-dir dist" }
+```
+Run `pnpm build` to produce `dist/index.js`.
+
+Ensure the final bundle sets `module.exports = { ... }` or `exports.default = { ... }`. Default ESM output alone will not be picked up unless your bundler transpiles it to a CommonJS wrapper.
+
+## 9. Local Development Workflow
+1. Create your plugin folder somewhere accessible.
+2. Build to produce entry file.
+3. (Future) Place or symlink the folder into the Nuclear plugins directory once auto-discovery is implemented. For now loading is manual (loader API expects a path).
+4. Rebuild after changes; the app will need a reload or unload+load cycle when hot-reload support is added.
+
+## 10. Best Practices
+- Keep startup fast; defer heavy work until `onEnable`.
+- Avoid global state leakage; store state on a module-local object.
+- Validate network responses defensively.
+- Use permissions array to communicate scope clearly.
+- Keep dependencies minimal; smaller bundles load faster.
+
+## 11. Troubleshooting
+| Issue | Check |
+|-------|-------|
+| Loader cannot resolve entry | Is `main` correct or is there a built `index.js` / `dist/index.js`? |
+| Missing fields error | Confirm all required manifest fields: name, version, description, author. |
+| Hooks not firing | Ensure default export is an object, not a function or class. |
+
+## 12. Type Exports
+```ts
+import type { NuclearPlugin, PluginManifest, PluginIcon } from '@nuclearplayer/plugin-sdk';
+```
+
+## 13. Example Complete Minimal Plugin (TypeScript)
+```ts
+import { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';
+
+export default {
+  async onLoad(api: NuclearPluginAPI) {
+  },
+  async onEnable(api: NuclearPluginAPI) {
+  },
+  async onDisable() {
+  },
+  async onUnload() {
+  },
+};
+```
+
+## 14. License
+AGPL-3.0-only

package/dist/api/index.d.ts

@@ -0,0 +1,15 @@
+import { ProvidersHost } from '../types/providers';
+import { SettingsHost } from '../types/settings';
+import { Providers } from './providers';
+import { Settings } from './settings';
+export declare class NuclearAPI {
+    readonly Settings: Settings;
+    readonly Providers: Providers;
+    constructor(opts?: {
+        settingsHost?: SettingsHost;
+        providersHost?: ProvidersHost;
+    });
+}
+export declare class NuclearPluginAPI extends NuclearAPI {
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;gBAElB,IAAI,CAAC,EAAE;QACjB,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B;CAIF;AAED,qBAAa,gBAAiB,SAAQ,UAAU;CAAG"}

package/dist/api/providers.d.ts

@@ -0,0 +1,11 @@
+import { ProvidersHost } from '../types/providers';
+import { ProviderDescriptor, ProviderKind } from '../types/search';
+export declare class Providers {
+    #private;
+    constructor(host?: ProvidersHost);
+    register<T extends ProviderDescriptor>(p: T): string;
+    unregister(id: string): boolean;
+    list<K extends ProviderKind = ProviderKind>(kind?: K): ProviderDescriptor<K>[];
+    get<T extends ProviderDescriptor>(id: string): T | undefined;
+}
+//# sourceMappingURL=providers.d.ts.map

package/dist/api/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/api/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAExE,qBAAa,SAAS;;gBAGR,IAAI,CAAC,EAAE,aAAa;IAYhC,QAAQ,CAAC,CAAC,SAAS,kBAAkB,EAAE,CAAC,EAAE,CAAC;IAI3C,UAAU,CAAC,EAAE,EAAE,MAAM;IAIrB,IAAI,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC;IAIpD,GAAG,CAAC,CAAC,SAAS,kBAAkB,EAAE,EAAE,EAAE,MAAM;CAG7C"}

package/dist/api/settings.d.ts

@@ -0,0 +1,10 @@
+import { SettingDefinition, SettingsHost, SettingSource, SettingValue } from '../types/settings';
+export declare class Settings {
+    #private;
+    constructor(host?: SettingsHost);
+    register(defs: SettingDefinition[], source: SettingSource): Promise<import('..').SettingsRegistrationResult>;
+    get<T extends SettingValue = SettingValue>(id: string): Promise<T | undefined>;
+    set<T extends SettingValue = SettingValue>(id: string, value: T): Promise<void>;
+    subscribe<T extends SettingValue = SettingValue>(id: string, listener: (value: T | undefined) => void): () => void;
+}
+//# sourceMappingURL=settings.d.ts.map

package/dist/api/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/api/settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,QAAQ;;gBAGP,IAAI,CAAC,EAAE,YAAY;IAY/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,EAAE,EAAE,MAAM,EAAE,aAAa;IAIzD,GAAG,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAAE,EAAE,MAAM;IAIrD,GAAG,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAI/D,SAAS,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAC7C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI;CAI3C"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { NuclearPluginAPI, NuclearAPI } from './api';
+export * from './types';
+export * from './types/settings';
+export * from './types/search';
+export type { ProvidersHost } from './types/providers';
+export { useSetting } from './react/useSetting';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACrD,cAAc,SAAS,CAAC;AACxB,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,92 @@
+import { useState as a, useEffect as l, useMemo as g } from "react";
+class h {
+  #r;
+  constructor(t) {
+    this.#r = t;
+  }
+  #t(t) {
+    const r = this.#r;
+    if (!r)
+      throw new Error("Providers host not available");
+    return t(r);
+  }
+  register(t) {
+    return this.#t((r) => r.register(t));
+  }
+  unregister(t) {
+    return this.#t((r) => r.unregister(t));
+  }
+  list(t) {
+    return this.#t((r) => r.list(t));
+  }
+  get(t) {
+    return this.#t((r) => r.get(t));
+  }
+}
+class b {
+  #r;
+  constructor(t) {
+    this.#r = t;
+  }
+  #t(t) {
+    const r = this.#r;
+    if (!r)
+      throw new Error("Settings host not available");
+    return t(r);
+  }
+  register(t, r) {
+    return this.#t((s) => s.register(t, r));
+  }
+  get(t) {
+    return this.#t((r) => r.get(t));
+  }
+  set(t, r) {
+    return this.#t((s) => s.set(t, r));
+  }
+  subscribe(t, r) {
+    return this.#t((s) => s.subscribe(t, r));
+  }
+}
+class f {
+  Settings;
+  Providers;
+  constructor(t) {
+    this.Settings = new b(t?.settingsHost), this.Providers = new h(t?.providersHost);
+  }
+}
+class d extends f {
+}
+class w extends Error {
+  constructor(t) {
+    super(`Missing capability: ${t}`), this.name = "MissingCapabilityError";
+  }
+}
+const p = (e, t) => {
+  const [r, s] = a(void 0);
+  l(() => {
+    if (!e)
+      return;
+    let i = !0, u = !1;
+    const o = e.subscribe(t, (n) => {
+      i && (u = !0, s(n));
+    });
+    return e.get(t).then((n) => {
+      i && (u || s(n));
+    }), () => {
+      i = !1, o && o();
+    };
+  }, [t, e]);
+  const c = g(
+    () => (i) => {
+      e && e.set(t, i);
+    },
+    [t, e]
+  );
+  return [r, c];
+};
+export {
+  w as MissingCapabilityError,
+  f as NuclearAPI,
+  d as NuclearPluginAPI,
+  p as useSetting
+};

package/dist/react/useSetting.d.ts

@@ -0,0 +1,3 @@
+import { SettingsHost, SettingValue } from '../types/settings';
+export declare const useSetting: <T extends SettingValue = SettingValue>(host: SettingsHost | undefined, id: string) => readonly [T | undefined, (nextValue: T) => void];
+//# sourceMappingURL=useSetting.d.ts.map

package/dist/react/useSetting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSetting.d.ts","sourceRoot":"","sources":["../../src/react/useSetting.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEpE,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,YAAY,GAAG,YAAY,EAC9D,MAAM,YAAY,GAAG,SAAS,EAC9B,IAAI,MAAM,0CAkCU,CAAC,UAUtB,CAAC"}

package/dist/test/setup.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=setup.d.ts.map

package/dist/test/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/test/setup.ts"],"names":[],"mappings":"AAAA,OAAO,2BAA2B,CAAC"}

package/dist/test/utils/inMemorySettingsHost.d.ts

@@ -0,0 +1,16 @@
+import { SettingDefinition, SettingsHost, SettingSource, SettingValue } from '../../types/settings';
+export declare class InMemorySettingsHost implements SettingsHost {
+    private definitions;
+    private values;
+    private listeners;
+    private readonly source;
+    constructor(source: SettingSource);
+    private fullyQualified;
+    register(definitions: SettingDefinition[], _source: SettingSource): Promise<{
+        registered: string[];
+    }>;
+    get<T extends SettingValue = SettingValue>(id: string): Promise<T | undefined>;
+    set<T extends SettingValue = SettingValue>(id: string, value: T): Promise<void>;
+    subscribe<T extends SettingValue = SettingValue>(id: string, listener: (value: T | undefined) => void): () => void;
+}
+//# sourceMappingURL=inMemorySettingsHost.d.ts.map

package/dist/test/utils/inMemorySettingsHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemorySettingsHost.d.ts","sourceRoot":"","sources":["../../../src/test/utils/inMemorySettingsHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,sBAAsB,CAAC;AAE9B,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,WAAW,CAAwC;IAC3D,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,SAAS,CAGb;IACJ,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,MAAM,EAAE,aAAa;IAIjC,OAAO,CAAC,cAAc;IAOhB,QAAQ,CAAC,WAAW,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,aAAa;;;IAsBjE,GAAG,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAAE,EAAE,MAAM;IAKrD,GAAG,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAWrE,SAAS,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAC7C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI;CAmB3C"}

package/dist/types/providers.d.ts

@@ -0,0 +1,9 @@
+import { ProviderDescriptor, ProviderKind } from './search';
+export type ProvidersHost = {
+    register<T extends ProviderDescriptor>(provider: T): string;
+    unregister(providerId: string): boolean;
+    list<K extends ProviderKind = ProviderKind>(kind?: K): ProviderDescriptor<K>[];
+    get<T extends ProviderDescriptor>(providerId: string): T | undefined;
+    clear(): void;
+};
+//# sourceMappingURL=providers.d.ts.map

package/dist/types/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/types/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEjE,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,CAAC,SAAS,kBAAkB,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC;IAC5D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,IAAI,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EACxC,IAAI,CAAC,EAAE,CAAC,GACP,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3B,GAAG,CAAC,CAAC,SAAS,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IACrE,KAAK,IAAI,IAAI,CAAC;CACf,CAAC"}

package/dist/types/search.d.ts

@@ -0,0 +1,40 @@
+import { Album, AlbumRef, Artist, ArtistRef, PlaylistRef, Track, TrackRef } from '@nuclearplayer/model';
+export type SearchCategory = 'artists' | 'albums' | 'tracks' | 'playlists';
+export type SearchCapability = SearchCategory | 'unified';
+export type ArtistMetadataCapability = 'artistDetails' | 'artistAlbums' | 'artistTopTracks' | 'artistRelatedArtists';
+export type SearchParams = {
+    query: string;
+    types?: SearchCategory[];
+    limit?: number;
+};
+export type SearchResults = {
+    artists?: ArtistRef[];
+    albums?: AlbumRef[];
+    tracks?: Track[];
+    playlists?: PlaylistRef[];
+};
+export type ProviderKind = 'metadata' | 'streaming' | 'lyrics' | (string & {});
+export type ProviderDescriptor<K extends ProviderKind = ProviderKind> = {
+    id: string;
+    kind: K;
+    name: string;
+    pluginId?: string;
+};
+export type MetadataProvider = ProviderDescriptor<'metadata'> & {
+    searchCapabilities?: SearchCapability[];
+    artistMetadataCapabilities?: ArtistMetadataCapability[];
+    search?: (params: SearchParams) => Promise<SearchResults>;
+    searchArtists?: (params: Omit<SearchParams, 'types'>) => Promise<ArtistRef[]>;
+    searchAlbums?: (params: Omit<SearchParams, 'types'>) => Promise<AlbumRef[]>;
+    searchTracks?: (params: Omit<SearchParams, 'types'>) => Promise<Track[]>;
+    searchPlaylists?: (params: Omit<SearchParams, 'types'>) => Promise<PlaylistRef[]>;
+    fetchArtistDetails?: (query: string) => Promise<Artist>;
+    fetchAlbumDetails?: (query: string) => Promise<Album>;
+    fetchArtistAlbums?: (artistId: string) => Promise<AlbumRef[]>;
+    fetchArtistTopTracks?: (artistId: string) => Promise<TrackRef[]>;
+    fetchArtistRelatedArtists?: (artistId: string) => Promise<ArtistRef[]>;
+};
+export declare class MissingCapabilityError extends Error {
+    constructor(capability: string);
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/types/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/types/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,QAAQ,EACR,MAAM,EACN,SAAS,EACT,WAAW,EACX,KAAK,EACL,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;AAC3E,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,wBAAwB,GAChC,eAAe,GACf,cAAc,GACd,iBAAiB,GACjB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/E,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,UAAU,CAAC,GAAG;IAC9D,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACxC,0BAA0B,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC9E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACzE,eAAe,CAAC,EAAE,CAChB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,KAChC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE5B,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IACtD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9D,oBAAoB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACxE,CAAC;AAEF,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,UAAU,EAAE,MAAM;CAI/B"}

package/dist/types/settings.d.ts

@@ -0,0 +1,113 @@
+export type SettingSource = {
+    type: 'core';
+} | {
+    type: 'plugin';
+    pluginId: string;
+    pluginName?: string;
+};
+export type SettingCategory = string;
+export type BooleanWidget = {
+    type: 'toggle';
+};
+export type NumberWidget = {
+    type: 'slider';
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+} | {
+    type: 'number-input';
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+};
+export type StringWidget = {
+    type: 'text';
+    placeholder?: string;
+} | {
+    type: 'password';
+    placeholder?: string;
+} | {
+    type: 'textarea';
+    placeholder?: string;
+    rows?: number;
+};
+export type EnumWidget = {
+    type: 'select';
+} | {
+    type: 'radio';
+};
+export type BooleanSettingDefinition = {
+    id: string;
+    title: string;
+    description?: string;
+    category: SettingCategory;
+    kind: 'boolean';
+    default?: boolean;
+    hidden?: boolean;
+    source?: SettingSource;
+    widget?: BooleanWidget;
+};
+export type NumberSettingDefinition = {
+    id: string;
+    title: string;
+    description?: string;
+    category: SettingCategory;
+    kind: 'number';
+    default?: number;
+    hidden?: boolean;
+    source?: SettingSource;
+    widget?: NumberWidget;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+};
+export type StringFormat = 'text' | 'url' | 'path' | 'token' | 'language';
+export type StringSettingDefinition = {
+    id: string;
+    title: string;
+    description?: string;
+    category: SettingCategory;
+    kind: 'string';
+    default?: string;
+    hidden?: boolean;
+    source?: SettingSource;
+    widget?: StringWidget;
+    format?: StringFormat;
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+};
+export type EnumOption = {
+    value: string;
+    label: string;
+};
+export type EnumSettingDefinition = {
+    id: string;
+    title: string;
+    description?: string;
+    category: SettingCategory;
+    kind: 'enum';
+    options: EnumOption[];
+    default?: string;
+    hidden?: boolean;
+    source?: SettingSource;
+    widget?: EnumWidget;
+};
+export type SettingDefinition = BooleanSettingDefinition | NumberSettingDefinition | StringSettingDefinition | EnumSettingDefinition;
+export type SettingValue = boolean | number | string | undefined;
+export type SettingsRegistration = {
+    settings: SettingDefinition[];
+};
+export type SettingsRegistrationResult = {
+    registered: string[];
+};
+export type SettingsHost = {
+    register(defs: SettingDefinition[], source: SettingSource): Promise<SettingsRegistrationResult>;
+    get<T extends SettingValue = SettingValue>(id: string): Promise<T | undefined>;
+    set<T extends SettingValue = SettingValue>(id: string, value: T): Promise<void>;
+    subscribe<T extends SettingValue = SettingValue>(id: string, listener: (value: T | undefined) => void): () => void;
+};
+//# sourceMappingURL=settings.d.ts.map

package/dist/types/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/types/settings.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import { NuclearPluginAPI } from './api';
+export type PluginIcon = {
+    type: 'link';
+    link: string;
+};
+export type PluginManifest = {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    main?: string;
+    nuclear?: {
+        displayName?: string;
+        category?: string;
+        icon?: PluginIcon;
+        permissions?: string[];
+    };
+};
+export type NuclearPlugin = {
+    onLoad?(api: NuclearPluginAPI): void | Promise<void>;
+    onUnload?(): void | Promise<void>;
+    onEnable?(api: NuclearPluginAPI): void | Promise<void>;
+    onDisable?(): void | Promise<void>;
+};
+export type PluginMetadata = {
+    id: string;
+    name: string;
+    displayName: string;
+    version: string;
+    description: string;
+    author: string;
+    category?: string;
+    icon?: PluginIcon;
+    permissions: string[];
+};
+export type LoadedPlugin = {
+    metadata: PluginMetadata;
+    instance: NuclearPlugin;
+    path: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,UAAU,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,SAAS,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC"}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@nuclearplayer/plugin-sdk",
+  "version": "0.0.9",
+  "description": "Plugin SDK for Nuclear music player",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.542.0",
+    "react": "^18.3.1",
+    "tailwind-merge": "^3.3.1",
+    "@nuclearplayer/model": "0.0.9"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.11",
+    "@testing-library/jest-dom": "^6.6.4",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^18.3.23",
+    "@vitejs/plugin-react": "^5.0.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^26.1.0",
+    "react-dom": "^18.3.1",
+    "tailwindcss": "^4.1.11",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4",
+    "@nuclearplayer/eslint-config": "0.0.9",
+    "@nuclearplayer/tailwind-config": "0.0.9"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  },
+  "keywords": [
+    "nuclear",
+    "music",
+    "player",
+    "plugin",
+    "sdk",
+    "react"
+  ],
+  "author": {
+    "name": "nukeop",
+    "email": "12746779+nukeop@users.noreply.github.com"
+  },
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NuclearPlayer/nuclear-xrd.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/NuclearPlayer/nuclear-xrd#readme",
+  "bugs": {
+    "url": "https://github.com/NuclearPlayer/nuclear-xrd/issues"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:npm": "vite build --mode npm",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist build .turbo node_modules/.vite"
+  }
+}