@shiqianjiang/ceru-plugin-sdk 0.3.15 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +14 -4
  2. package/dist/accounts.d.ts +107 -1
  3. package/dist/accounts.js +14 -0
  4. package/dist/catalog.d.ts +1 -1
  5. package/dist/catalog.js +23 -0
  6. package/dist/crypto-streams.d.ts +10 -0
  7. package/dist/crypto-streams.js +1 -0
  8. package/dist/events.d.ts +21 -0
  9. package/dist/events.js +14 -0
  10. package/dist/hooks.d.ts +211 -0
  11. package/dist/hooks.js +14 -0
  12. package/dist/index.d.ts +55 -22
  13. package/dist/index.js +46 -3
  14. package/dist/legacy-http.d.ts +1 -0
  15. package/dist/legacy-http.js +3 -0
  16. package/dist/lifecycle.d.ts +21 -0
  17. package/dist/lifecycle.js +1 -0
  18. package/dist/links.d.ts +2 -0
  19. package/dist/links.js +25 -0
  20. package/dist/manifest.d.ts +190 -131
  21. package/dist/music-api.d.ts +44 -0
  22. package/dist/music-api.js +1 -0
  23. package/dist/music.js +3 -0
  24. package/dist/navigation.d.ts +17 -0
  25. package/dist/navigation.js +45 -1
  26. package/dist/permissions.d.ts +92 -0
  27. package/dist/permissions.js +23 -0
  28. package/dist/plugins-api.d.ts +16 -0
  29. package/dist/plugins-api.js +1 -0
  30. package/dist/regions.d.ts +76 -0
  31. package/dist/regions.js +9 -0
  32. package/dist/server.d.ts +32 -0
  33. package/dist/server.js +4 -0
  34. package/dist/services.d.ts +48 -24
  35. package/dist/services.js +6 -22
  36. package/dist/streams.d.ts +35 -0
  37. package/dist/streams.js +51 -0
  38. package/dist/validate.d.ts +2 -1
  39. package/dist/validate.js +18 -0
  40. package/dist/view-bridge.d.ts +6 -0
  41. package/dist/view-bridge.js +1 -0
  42. package/dist/view-contracts.d.ts +136 -0
  43. package/dist/view-contracts.js +1 -0
  44. package/dist/vue/index.d.ts +17 -0
  45. package/dist/vue/index.js +74 -0
  46. package/dist/vue/region.d.ts +7 -0
  47. package/dist/vue/region.js +5 -0
  48. package/dist/wasm.d.ts +5 -0
  49. package/dist/wasm.js +1 -0
  50. package/package.json +14 -6
  51. package/dist/host-library.d.ts +0 -29
  52. package/dist/host-library.js +0 -69
@@ -0,0 +1,136 @@
1
+ import type { AllowedComponentProps, Ref, VNodeProps } from 'vue';
2
+ import type { JsonObject, JsonValue, HostIconName } from './index.js';
3
+ export interface HostMediaItem {
4
+ title: string;
5
+ key?: string;
6
+ ref?: {
7
+ id: string;
8
+ providerId: string;
9
+ kind?: string;
10
+ pluginId?: string;
11
+ connectionId?: string;
12
+ scope?: 'provider';
13
+ };
14
+ source?: string;
15
+ subtitle?: string;
16
+ playable?: boolean;
17
+ durationMs?: number;
18
+ metadata?: {
19
+ artists?: string[];
20
+ qualities?: string[];
21
+ durationMs?: number;
22
+ };
23
+ playlist?: {
24
+ author?: string;
25
+ trackCount?: number;
26
+ };
27
+ }
28
+ export type HostSongAction = 'play' | 'enqueue' | 'favorite' | 'download';
29
+ export type HostSongActions = Partial<Record<HostSongAction, string>>;
30
+ export interface HostTextProps {
31
+ title?: string;
32
+ text?: string;
33
+ name?: string;
34
+ }
35
+ export interface HostPalette {
36
+ readonly accent: string;
37
+ readonly foreground: string;
38
+ readonly background: string;
39
+ }
40
+ export interface HostVisualProps {
41
+ artwork?: string | null;
42
+ track?: {
43
+ title?: string;
44
+ artists?: readonly string[];
45
+ album?: string;
46
+ } | null;
47
+ palette?: HostPalette;
48
+ playing?: boolean;
49
+ alt?: string;
50
+ }
51
+ export interface HostVisualizerProps extends HostVisualProps {
52
+ spectrum?: Readonly<Float32Array> | readonly number[];
53
+ color?: string;
54
+ barCount?: number;
55
+ height?: number;
56
+ }
57
+ type ViewComponent<Props> = new () => {
58
+ $props: Props & VNodeProps & AllowedComponentProps;
59
+ };
60
+ export interface HostComponents {
61
+ LyricAdapter: ViewComponent<{
62
+ alignPosition?: number;
63
+ enableBlur?: boolean;
64
+ enableSpring?: boolean;
65
+ enableScale?: boolean;
66
+ textAlign?: 'left' | 'center' | 'right';
67
+ onLineClick?: (milliseconds: number) => void;
68
+ }>;
69
+ AmlLyricPlayer: ViewComponent<{
70
+ alignPosition?: number;
71
+ enableBlur?: boolean;
72
+ enableSpring?: boolean;
73
+ enableScale?: boolean;
74
+ onLineClick?: (milliseconds: number) => void;
75
+ }>;
76
+ SquareCover: ViewComponent<HostVisualProps>;
77
+ VinylRecord: ViewComponent<HostVisualProps>;
78
+ ShaderBackground: ViewComponent<HostVisualProps>;
79
+ AudioVisualizer: ViewComponent<HostVisualizerProps>;
80
+ SongList: ViewComponent<{
81
+ items?: readonly HostMediaItem[];
82
+ actions?: HostSongActions;
83
+ label?: string;
84
+ onPlay?: {
85
+ listener(item: HostMediaItem): void;
86
+ }['listener'];
87
+ }>;
88
+ PlaylistCard: ViewComponent<HostTextProps & {
89
+ item?: HostMediaItem;
90
+ onOpen?: (item: HostMediaItem) => void;
91
+ }>;
92
+ PlaylistGrid: ViewComponent<HostTextProps & {
93
+ items?: readonly HostMediaItem[];
94
+ onOpen?: (item: HostMediaItem) => void;
95
+ }>;
96
+ QualityBadge: ViewComponent<HostTextProps & {
97
+ quality?: string;
98
+ }>;
99
+ SourceIcon: ViewComponent<HostTextProps & {
100
+ source?: string;
101
+ }>;
102
+ PageHeader: ViewComponent<HostTextProps & {
103
+ description?: string;
104
+ }>;
105
+ EmptyState: ViewComponent<HostTextProps & {
106
+ description?: string;
107
+ }>;
108
+ LoadingState: ViewComponent<HostTextProps>;
109
+ }
110
+ export interface ViewBridge {
111
+ readonly region?: import('./regions.js').MountedRegion;
112
+ readonly root: ShadowRoot;
113
+ readonly instanceId: string;
114
+ readonly viewId: string;
115
+ readonly props: Readonly<JsonObject>;
116
+ readonly state: Readonly<Ref<JsonObject>>;
117
+ readonly theme: Readonly<Ref<'light' | 'dark'>>;
118
+ readonly overlay: HTMLElement;
119
+ readonly components: HostComponents;
120
+ readonly icons: {
121
+ url(name: HostIconName): string;
122
+ };
123
+ invoke<Input extends JsonValue = JsonValue, Output extends JsonValue = JsonValue>(action: string, input?: Input): Promise<Output>;
124
+ close(): Promise<void>;
125
+ onDispose(cleanup: () => void): void;
126
+ }
127
+ export type RegionTransitionHook = (context: {
128
+ readonly root: ShadowRoot;
129
+ readonly signal: AbortSignal;
130
+ readonly reason: 'skin' | 'track';
131
+ }) => void | Promise<void>;
132
+ export type ViewEntry = ((bridge: ViewBridge) => void | (() => void)) & {
133
+ onEnter?: RegionTransitionHook;
134
+ onLeave?: RegionTransitionHook;
135
+ };
136
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,17 @@
1
+ import { type Component, type Ref } from 'vue';
2
+ import type { JsonObject, JsonValue } from '../manifest.js';
3
+ import type { ViewBridge, ViewEntry } from '../view-bridge.js';
4
+ import type { PlayerRegion, RegionContext } from '../regions.js';
5
+ export type { ViewBridge, ViewEntry, ViewDeps, RegionTransitionHook, HostComponents, HostMediaItem, HostSongAction, HostSongActions } from '../view-bridge.js';
6
+ export declare const defineView: (setup: ViewEntry) => ViewEntry;
7
+ export declare const ViewDialog: import("vue").DefineComponent<{}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
8
+ [key: string]: any;
9
+ }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
10
+ export declare function mountComponent(component: Component, bridge: ViewBridge): () => void;
11
+ export declare function useView(): ViewBridge;
12
+ export declare function useAction<Input extends JsonValue = JsonValue, Output extends JsonValue = JsonValue>(action: string): (input?: Input) => Promise<Output>;
13
+ export declare function useViewState<State extends JsonObject = JsonObject>(): Readonly<Ref<State>>;
14
+ export declare function useHostComponents(): import("../view-contracts.js").HostComponents;
15
+ export declare function useRegion<Name extends PlayerRegion>(name: Name): RegionContext<Name>;
16
+ export declare function useFrame(callback: (timestamp: number) => void): () => void;
17
+ export declare function useSpectrum(): Readonly<Float32Array>;
@@ -0,0 +1,74 @@
1
+ import { createApp, defineComponent, h, inject, onMounted, onBeforeUnmount } from 'vue';
2
+ import TDesign, { ConfigProvider, Dialog } from 'tdesign-vue-next';
3
+ const bridgeKey = Symbol('ceru.plugin.view');
4
+ export const defineView = (setup) => setup;
5
+ export const ViewDialog = defineComponent({
6
+ name: 'CeruViewDialog', inheritAttrs: false,
7
+ setup(_, { attrs, slots, emit }) {
8
+ const bridge = useView();
9
+ const dismiss = (event) => {
10
+ if (!attrs.visible)
11
+ return;
12
+ emit('close', { trigger: 'close-btn', e: event });
13
+ emit('update:visible', false);
14
+ };
15
+ onMounted(() => bridge.overlay.addEventListener('ceru-overlay-dismiss', dismiss));
16
+ onBeforeUnmount(() => bridge.overlay.removeEventListener('ceru-overlay-dismiss', dismiss));
17
+ return () => h(Dialog, { attach: () => bridge.overlay, ...attrs }, slots);
18
+ }
19
+ });
20
+ export function mountComponent(component, bridge) {
21
+ const container = bridge.root.ownerDocument.createElement('div');
22
+ bridge.root.append(container);
23
+ const app = createApp({ render: () => h(ConfigProvider, {}, { default: () => h(component, bridge.props) }) });
24
+ app.use(TDesign);
25
+ app.component('TDialog', ViewDialog);
26
+ app.provide(bridgeKey, bridge);
27
+ let mounted = false;
28
+ const dispose = () => { if (mounted) {
29
+ mounted = false;
30
+ app.unmount();
31
+ } container.remove(); };
32
+ try {
33
+ app.mount(container);
34
+ mounted = true;
35
+ }
36
+ catch (error) {
37
+ dispose();
38
+ throw error;
39
+ }
40
+ bridge.onDispose(dispose);
41
+ return dispose;
42
+ }
43
+ export function useView() {
44
+ const bridge = inject(bridgeKey);
45
+ if (!bridge)
46
+ throw Error('useView requires a mounted Ceru component view');
47
+ return bridge;
48
+ }
49
+ export function useAction(action) {
50
+ const bridge = useView();
51
+ return (input) => bridge.invoke(action, input);
52
+ }
53
+ export function useViewState() { return useView().state; }
54
+ export function useHostComponents() { return useView().components; }
55
+ export function useRegion(name) {
56
+ const region = useView().region;
57
+ if (region?.name !== name || region.version !== 1)
58
+ throw Error('Not mounted in region: ' + name);
59
+ return region;
60
+ }
61
+ export function useFrame(callback) {
62
+ const region = useView().region;
63
+ if (!region)
64
+ throw Error('useFrame requires a mounted player region');
65
+ const stop = region.onFrame(callback);
66
+ onBeforeUnmount(stop);
67
+ return stop;
68
+ }
69
+ export function useSpectrum() {
70
+ const region = useView().region;
71
+ if (!region || !('spectrum' in region.props))
72
+ throw Error('No spectrum in this region');
73
+ return region.props.spectrum;
74
+ }
@@ -0,0 +1,7 @@
1
+ import type { PlayerRegion, RegionContext } from '../regions.js';
2
+ import type { HostComponents } from '../view-contracts.js';
3
+ export type { HostComponents, RegionTransitionHook } from '../view-contracts.js';
4
+ export declare const useRegion: <Name extends PlayerRegion>(name: Name) => RegionContext<Name>;
5
+ export declare const useHostComponents: () => HostComponents;
6
+ export declare const useFrame: (callback: (timestamp: number) => void) => void;
7
+ export declare const useSpectrum: () => Readonly<Float32Array>;
@@ -0,0 +1,5 @@
1
+ import * as shared from './index.js';
2
+ export const useRegion = shared.useRegion;
3
+ export const useHostComponents = shared.useHostComponents;
4
+ export const useFrame = shared.useFrame;
5
+ export const useSpectrum = shared.useSpectrum;
package/dist/wasm.d.ts ADDED
@@ -0,0 +1,5 @@
1
+ import type { AssetHandle } from './index.js';
2
+ export interface WasmAPI {
3
+ /** Instantiate a WebAssembly resource embedded in this plugin's artifact. */
4
+ instantiate(resource: AssetHandle | string, imports?: WebAssembly.Imports): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
5
+ }
package/dist/wasm.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shiqianjiang/ceru-plugin-sdk",
3
- "version": "0.3.15",
3
+ "version": "3.0.0",
4
4
  "description": "Typed authoring contracts for Ceru Music v2 single-file plugins",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -10,6 +10,12 @@
10
10
  "prepack": "npm run build"
11
11
  },
12
12
  "exports": {
13
+ "./crypto-streams": {"types":"./dist/crypto-streams.d.ts","default":"./dist/crypto-streams.js"},
14
+ "./wasm": {"types":"./dist/wasm.d.ts","default":"./dist/wasm.js"},
15
+ "./streams": {"types":"./dist/streams.d.ts","default":"./dist/streams.js"},
16
+ "./vue": {"types":"./dist/vue/index.d.ts","default":"./dist/vue/index.js"},
17
+ "./vue/region": {"types":"./dist/vue/region.d.ts","default":"./dist/vue/region.js"},
18
+ "./view-bridge": {"types":"./dist/view-bridge.d.ts","default":"./dist/view-bridge.js"},
13
19
  "./quality": {
14
20
  "types": "./dist/quality.d.ts",
15
21
  "default": "./dist/quality.js"
@@ -78,11 +84,6 @@
78
84
  "import": "./dist/library.js",
79
85
  "default": "./dist/library.js"
80
86
  },
81
- "./host-library": {
82
- "types": "./dist/host-library.d.ts",
83
- "import": "./dist/host-library.js",
84
- "default": "./dist/host-library.js"
85
- },
86
87
  "./sockets": {
87
88
  "types": "./dist/sockets.d.ts",
88
89
  "import": "./dist/sockets.js",
@@ -117,6 +118,10 @@
117
118
  "types": "./dist/compat/format.d.ts",
118
119
  "import": "./dist/compat/format.js",
119
120
  "default": "./dist/compat/format.js"
121
+ },
122
+ "./navigation": {
123
+ "types": "./dist/navigation.d.ts",
124
+ "default": "./dist/navigation.js"
120
125
  }
121
126
  },
122
127
  "files": [
@@ -126,6 +131,9 @@
126
131
  "LICENSE"
127
132
  ],
128
133
  "license": "MIT",
134
+ "peerDependencies": { "vue": "^3.5.21", "tdesign-vue-next": "^1.15.2" },
135
+ "peerDependenciesMeta": { "vue": {"optional":true}, "tdesign-vue-next": {"optional":true} },
136
+ "devDependencies": { "tdesign-vue-next": "1.15.4" },
129
137
  "dependencies": {
130
138
  "@types/lodash": "^4.17.25",
131
139
  "buffer": "^6.0.3",
@@ -1,29 +0,0 @@
1
- import type { LibraryAPI, LibraryPlaylist, PlaylistImportRequest, PlaylistLocation, PlaylistReference, PlaylistRemoveResult } from './library.js';
2
- import type { ContentEntity, OperationContext, Page } from './index.js';
3
- type LibraryCapability = 'library.read' | 'library.write' | 'library.delete';
4
- /** Bind these functions to existing app services. No database, account or UI is created here. */
5
- export interface HostLibraryServices {
6
- authorize(permissionKey: string, capability: LibraryCapability, operation: OperationContext, target?: PlaylistReference): Promise<void>;
7
- chooseTarget(suggestedName: string | undefined, operation: OperationContext): Promise<PlaylistReference | null>;
8
- list(location: PlaylistLocation | undefined, cursor: string | undefined, operation: OperationContext): Promise<Page<LibraryPlaylist>>;
9
- getTracks(target: PlaylistReference, cursor: string | undefined, operation: OperationContext): Promise<Page<ContentEntity>>;
10
- /** Existing local/cloud service must deduplicate requestId per plugin/user/target. */
11
- append(input: PlaylistImportRequest & {
12
- target: PlaylistReference;
13
- }): Promise<{
14
- added: number;
15
- skipped: number;
16
- }>;
17
- /**
18
- * Delete the given tracks from an existing playlist and report how many rows
19
- * were actually there. Cloud targets may need a paginated lookup first.
20
- */
21
- remove(target: PlaylistReference, items: ContentEntity[], operation: OperationContext): Promise<PlaylistRemoveResult>;
22
- /** Keep the playlist, drop its tracks. */
23
- clear(target: PlaylistReference, operation: OperationContext): Promise<void>;
24
- /** Notify the existing store/event bus only after persistence succeeds. */
25
- changed(target: PlaylistReference): void;
26
- }
27
- /** Core-side validation/delegation. Pass only a Host-authenticated OperationContext. */
28
- export declare function createHostLibraryBridge(services: HostLibraryServices): LibraryAPI;
29
- export {};
@@ -1,69 +0,0 @@
1
- import { assertRemovableTracks } from './validate.js';
2
- import { assertContentPage } from './music.js';
3
- function checkTarget(target) {
4
- if (!target ||
5
- typeof target.id !== 'string' ||
6
- !target.id ||
7
- !['local', 'cloud'].includes(target.location))
8
- throw new Error('Invalid target playlist');
9
- }
10
- /** Core-side validation/delegation. Pass only a Host-authenticated OperationContext. */
11
- export function createHostLibraryBridge(services) {
12
- return {
13
- playlists: {
14
- async list(input) {
15
- input.operation.signal.throwIfAborted();
16
- await services.authorize(input.permissionKey, 'library.read', input.operation);
17
- return services.list(input.location, input.cursor, input.operation);
18
- },
19
- async getTracks(input) {
20
- checkTarget(input.target);
21
- await services.authorize(input.permissionKey, 'library.read', input.operation, input.target);
22
- const result = await services.getTracks(input.target, input.cursor, input.operation);
23
- assertContentPage(result);
24
- return result;
25
- },
26
- async import(input) {
27
- input.operation.signal.throwIfAborted();
28
- assertContentPage({ items: input.items });
29
- if (input.items.some((item) => item.ref.kind !== 'track'))
30
- throw new Error('Only tracks can be imported');
31
- if (typeof input.requestId !== 'string' || !input.requestId || input.requestId.length > 256)
32
- throw new Error('Invalid import request ID');
33
- await services.authorize(input.permissionKey, 'library.write', input.operation, input.target);
34
- const target = input.target ?? (await services.chooseTarget(input.suggestedName, input.operation));
35
- if (!target)
36
- return { cancelled: true, added: 0, skipped: 0 };
37
- checkTarget(target);
38
- // The final user-selected destination may have a different grant/account scope.
39
- await services.authorize(input.permissionKey, 'library.write', input.operation, target);
40
- input.operation.signal.throwIfAborted();
41
- const result = await services.append({ ...input, target });
42
- services.changed(target);
43
- return { cancelled: false, target, added: result.added, skipped: result.skipped };
44
- },
45
- async removeTracks(input) {
46
- checkTarget(input.target);
47
- assertRemovableTracks(input.items);
48
- input.operation.signal.throwIfAborted();
49
- await services.authorize(input.permissionKey, 'library.delete', input.operation, input.target);
50
- input.operation.signal.throwIfAborted();
51
- const result = await services.remove(input.target, input.items, input.operation);
52
- const removed = Number(result?.removed) || 0;
53
- const notFound = Number(result?.notFound) || 0;
54
- if (removed + notFound !== input.items.length)
55
- throw new Error('Playlist removal result does not match the request');
56
- services.changed(input.target);
57
- return { removed, notFound };
58
- },
59
- async clearPlaylist(input) {
60
- checkTarget(input.target);
61
- input.operation.signal.throwIfAborted();
62
- await services.authorize(input.permissionKey, 'library.delete', input.operation, input.target);
63
- input.operation.signal.throwIfAborted();
64
- await services.clear(input.target, input.operation);
65
- services.changed(input.target);
66
- },
67
- },
68
- };
69
- }