xxf_react 0.5.3 → 0.5.4

package/README.md

@@ -13,3 +13,7 @@ bun run src/index.ts
 ```
 
 This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+
+## 文档
+
+- [PlaybackQueue 播放队列状态管理](./src/media/playback-queue-store.md)

package/dist/media/index.d.ts

@@ -1,2 +1,3 @@
 export * from './video-state';
+export * from './playback-queue-store';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC"}

package/dist/media/index.js

@@ -1,2 +1,3 @@
 'use client';
 export * from './video-state';
+export * from './playback-queue-store';

package/dist/media/playback-queue-store.d.ts

@@ -0,0 +1,642 @@
+/**
+ * @fileoverview 播放队列状态管理 (Zustand)
+ *
+ * 支持多 Tab / 多页面场景，全局只有一个视频在播放。
+ *
+ * @module playback-queue-store
+ * @see {@link ./playback-queue-store.md} 详细文档
+ */
+/**
+ * Source 数据结构
+ *
+ * 每个 source 代表一个独立的播放列表，通常对应一个 Tab 或页面。
+ *
+ * @example
+ * ```ts
+ * const homeSource: SourceData = {
+ *   itemIds: ['video-1', 'video-2', 'video-3']
+ * }
+ * ```
+ */
+interface SourceData {
+    /**
+     * 该 source 下的所有项目 ID 列表
+     *
+     * - 有序数组，决定播放顺序
+     * - ID 应该是唯一的字符串标识符
+     */
+    itemIds: string[];
+}
+/**
+ * 播放队列状态
+ *
+ * 核心状态结构，包含所有 source 的数据和当前播放状态。
+ *
+ * @example
+ * ```ts
+ * const state: PlaybackQueueState = {
+ *   sources: {
+ *     'home': { itemIds: ['a', 'b', 'c'] },
+ *     'community': { itemIds: ['d', 'e'] },
+ *   },
+ *   itemIdToSource: { 'a': 'home', 'b': 'home', 'd': 'community' },
+ *   activeSource: 'home',
+ *   currentId: 'a',
+ *   muted: true,
+ *   loop: true,
+ * }
+ * ```
+ */
+interface PlaybackQueueState {
+    /**
+     * 多个 source 的数据
+     *
+     * key: source 名称（如 'home', 'community', 'detail-123'）
+     * value: 该 source 的数据
+     */
+    sources: Record<string, SourceData>;
+    /**
+     * ID 到 source 的反向索引
+     *
+     * 用于 `playById` 快速查找某个 ID 属于哪个 source。
+     * 复杂度从 O(n*m) 降低到 O(1)。
+     *
+     * @internal 内部使用，自动维护
+     */
+    itemIdToSource: Record<string, string>;
+    /**
+     * 当前激活的 source 名称
+     *
+     * - 播放、next、prev 操作都在此 source 内进行
+     * - 为 null 表示没有激活的 source
+     */
+    activeSource: string | null;
+    /**
+     * 当前正在播放的项目 ID
+     *
+     * - 全局唯一，保证同一时间只有一个视频在播放
+     * - 为 null 表示没有视频在播放
+     */
+    currentId: string | null;
+    /**
+     * 是否静音
+     *
+     * @default true（默认静音，符合浏览器自动播放策略）
+     */
+    muted: boolean;
+    /**
+     * 是否循环播放
+     *
+     * - true: 播放到最后一个后自动回到第一个
+     * - false: 播放到最后一个后停止
+     *
+     * @default true
+     */
+    loop: boolean;
+}
+/**
+ * 播放队列操作方法接口
+ *
+ * 定义所有可用的操作方法。
+ */
+interface PlaybackQueueActions {
+    /**
+     * 设置某个 source 的播放列表
+     *
+     * 用于初始化或更新某个 Tab/页面的播放列表。
+     *
+     * @param source - source 名称，建议使用有意义的标识符
+     *   - 'home' - 首页
+     *   - 'community' - 社区页
+     *   - 'detail-{id}' - 详情页
+     * @param ids - 项目 ID 列表，会自动去重
+     * @param autoPlay - 是否自动播放第一个，默认 false
+     *
+     * @example
+     * ```tsx
+     * // 初始化首页列表
+     * const { setSource } = usePlaybackActions()
+     *
+     * useEffect(() => {
+     *   setSource('home', templates.map(t => t.id))
+     * }, [templates])
+     *
+     * // 初始化并自动播放
+     * setSource('home', ['id-1', 'id-2'], true)
+     * ```
+     */
+    setSource: (source: string, ids: string[], autoPlay?: boolean) => void;
+    /**
+     * 向某个 source 追加项目
+     *
+     * 用于滚动加载场景，追加新数据时不影响当前播放状态。
+     *
+     * @param source - source 名称
+     * @param ids - 要追加的项目 ID 列表，会自动去重
+     *
+     * @example
+     * ```tsx
+     * // 滚动加载更多
+     * const { appendToSource } = usePlaybackActions()
+     *
+     * const onLoadMore = (newItems: Template[]) => {
+     *   appendToSource('home', newItems.map(t => t.id))
+     * }
+     * ```
+     */
+    appendToSource: (source: string, ids: string[]) => void;
+    /**
+     * 移除某个 source
+     *
+     * 用于页面卸载时清理数据，防止内存泄漏。
+     * 如果移除的是当前激活的 source，会自动停止播放。
+     *
+     * @param source - 要移除的 source 名称
+     *
+     * @example
+     * ```tsx
+     * // 详情页卸载时清理
+     * useEffect(() => {
+     *   setSource(`detail-${id}`, items)
+     *   return () => removeSource(`detail-${id}`)
+     * }, [id])
+     * ```
+     */
+    removeSource: (source: string) => void;
+    /**
+     * 播放指定 source 中的指定项目
+     *
+     * 会自动切换 activeSource 到指定的 source。
+     *
+     * @param source - source 名称
+     * @param id - 项目 ID
+     *
+     * @example
+     * ```tsx
+     * const { play } = usePlaybackActions()
+     *
+     * // 点击卡片播放
+     * <div onClick={() => play('home', item.id)}>
+     *   ...
+     * </div>
+     * ```
+     */
+    play: (source: string, id: string) => void;
+    /**
+     * 播放指定项目（自动查找 source）
+     *
+     * 优先在当前 activeSource 中查找，找不到则通过反向索引查找。
+     * 适用于不关心具体 source 的场景。
+     *
+     * @param id - 项目 ID
+     *
+     * @example
+     * ```tsx
+     * const { playById } = usePlaybackActions()
+     *
+     * // 从搜索结果播放（不知道属于哪个 source）
+     * <div onClick={() => playById(searchResult.id)}>
+     *   ...
+     * </div>
+     * ```
+     */
+    playById: (id: string) => void;
+    /**
+     * 播放下一个
+     *
+     * 在当前 activeSource 内播放下一个项目。
+     * 如果已是最后一个：
+     * - loop=true: 回到第一个
+     * - loop=false: 停止播放（currentId 变为 null）
+     *
+     * @example
+     * ```tsx
+     * const { next } = usePlaybackActions()
+     *
+     * <button onClick={next}>下一个</button>
+     * ```
+     */
+    next: () => void;
+    /**
+     * 播放上一个
+     *
+     * 在当前 activeSource 内播放上一个项目。
+     * 如果已是第一个：
+     * - loop=true: 跳到最后一个
+     * - loop=false: 停止播放
+     *
+     * @example
+     * ```tsx
+     * const { prev } = usePlaybackActions()
+     *
+     * <button onClick={prev}>上一个</button>
+     * ```
+     */
+    prev: () => void;
+    /**
+     * 停止播放
+     *
+     * 将 currentId 设为 null，但保留 activeSource。
+     *
+     * @example
+     * ```tsx
+     * const { stop } = usePlaybackActions()
+     *
+     * <button onClick={stop}>停止</button>
+     * ```
+     */
+    stop: () => void;
+    /**
+     * 播放完成回调
+     *
+     * 应在视频的 onEnded 事件中调用，会自动播放下一个。
+     *
+     * @example
+     * ```tsx
+     * const { onEnded } = usePlaybackActions()
+     *
+     * <video onEnded={onEnded} />
+     * ```
+     */
+    onEnded: () => void;
+    /**
+     * 设置静音状态
+     *
+     * @param muted - true 静音，false 取消静音
+     *
+     * @example
+     * ```tsx
+     * const { setMuted } = usePlaybackActions()
+     *
+     * setMuted(true)  // 静音
+     * setMuted(false) // 取消静音
+     * ```
+     */
+    setMuted: (muted: boolean) => void;
+    /**
+     * 切换静音状态
+     *
+     * @example
+     * ```tsx
+     * const { toggleMute } = usePlaybackActions()
+     * const muted = usePlaybackMuted()
+     *
+     * <button onClick={toggleMute}>
+     *   {muted ? '🔇' : '🔊'}
+     * </button>
+     * ```
+     */
+    toggleMute: () => void;
+    /**
+     * 设置循环播放
+     *
+     * @param loop - true 循环播放，false 播完停止
+     *
+     * @example
+     * ```tsx
+     * const { setLoop } = usePlaybackActions()
+     *
+     * setLoop(false) // 关闭循环
+     * ```
+     */
+    setLoop: (loop: boolean) => void;
+    /**
+     * 重置所有状态
+     *
+     * 将状态恢复到初始值，清空所有 source 和播放状态。
+     * 通常用于用户登出或需要完全重置的场景。
+     *
+     * @example
+     * ```tsx
+     * const { reset } = usePlaybackActions()
+     *
+     * // 用户登出时清理
+     * const handleLogout = () => {
+     *   reset()
+     *   // ...其他清理逻辑
+     * }
+     * ```
+     */
+    reset: () => void;
+}
+/**
+ * 播放队列 Store 完整类型
+ *
+ * 包含状态和操作方法。
+ */
+type PlaybackQueueStore = PlaybackQueueState & PlaybackQueueActions;
+/**
+ * 播放队列 Zustand Store
+ *
+ * 使用 `subscribeWithSelector` 中间件支持选择性订阅。
+ *
+ * @example
+ * ```tsx
+ * // 直接使用 store（不推荐，建议使用封装的 hooks）
+ * const currentId = usePlaybackQueueStore(state => state.currentId)
+ * ```
+ */
+export declare const usePlaybackQueueStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<PlaybackQueueStore>, "subscribe"> & {
+    subscribe: {
+        (listener: (selectedState: PlaybackQueueStore, previousSelectedState: PlaybackQueueStore) => void): () => void;
+        <U>(selector: (state: PlaybackQueueStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: ((a: U, b: U) => boolean) | undefined;
+            fireImmediately?: boolean;
+        } | undefined): () => void;
+    };
+}>;
+/**
+ * 获取播放队列操作方法
+ *
+ * 使用 shallow 比较，避免不必要的重渲染。
+ * 返回的方法引用稳定，可以安全地用作依赖项。
+ *
+ * @returns 所有操作方法
+ *
+ * @example
+ * ```tsx
+ * const { play, stop, next, prev, toggleMute, onEnded } = usePlaybackActions()
+ *
+ * // 在视频组件中
+ * <video
+ *   onEnded={onEnded}
+ *   onClick={() => play('home', item.id)}
+ * />
+ *
+ * // 控制按钮
+ * <button onClick={prev}>上一个</button>
+ * <button onClick={next}>下一个</button>
+ * <button onClick={toggleMute}>静音</button>
+ * ```
+ */
+export declare function usePlaybackActions(): PlaybackQueueActions;
+/**
+ * 判断指定项目是否正在播放
+ *
+ * 选择性订阅，只有当该项目的播放状态变化时才会重渲染。
+ * 这是性能最优的播放状态判断方式。
+ *
+ * @param id - 项目 ID
+ * @returns 是否正在播放
+ *
+ * @example
+ * ```tsx
+ * const VideoCard = ({ item }) => {
+ *   const isPlaying = usePlaybackIsPlaying(item.id)
+ *
+ *   return (
+ *     <video autoPlay={isPlaying} muted />
+ *   )
+ * }
+ * ```
+ */
+export declare function usePlaybackIsPlaying(id: string): boolean;
+/**
+ * 获取静音状态
+ *
+ * @returns 是否静音
+ *
+ * @example
+ * ```tsx
+ * const muted = usePlaybackMuted()
+ *
+ * <video muted={muted} />
+ * ```
+ */
+export declare function usePlaybackMuted(): boolean;
+/**
+ * 获取当前播放的项目 ID
+ *
+ * @returns 当前播放的 ID，没有播放时为 null
+ *
+ * @example
+ * ```tsx
+ * const currentId = usePlaybackCurrentId()
+ *
+ * if (currentId) {
+ *   console.log('正在播放:', currentId)
+ * }
+ * ```
+ */
+export declare function usePlaybackCurrentId(): string | null;
+/**
+ * 获取当前激活的 source 名称
+ *
+ * @returns source 名称，没有激活时为 null
+ *
+ * @example
+ * ```tsx
+ * const activeSource = usePlaybackActiveSource()
+ *
+ * // 高亮当前激活的 Tab
+ * <Tab active={activeSource === 'home'}>首页</Tab>
+ * ```
+ */
+export declare function usePlaybackActiveSource(): string | null;
+/**
+ * 获取循环播放状态
+ *
+ * @returns 是否循环播放
+ *
+ * @example
+ * ```tsx
+ * const loop = usePlaybackLoop()
+ * const { setLoop } = usePlaybackActions()
+ *
+ * <button onClick={() => setLoop(!loop)}>
+ *   {loop ? '循环开' : '循环关'}
+ * </button>
+ * ```
+ */
+export declare function usePlaybackLoop(): boolean;
+/**
+ * 获取指定 source 的项目 ID 列表
+ *
+ * @param source - source 名称
+ * @returns 项目 ID 列表，source 不存在时返回空数组
+ *
+ * @example
+ * ```tsx
+ * const homeItems = usePlaybackSourceItems('home')
+ *
+ * console.log('首页有', homeItems.length, '个视频')
+ * ```
+ */
+export declare function usePlaybackSourceItems(source: string): string[];
+/**
+ * 获取单个 item 的播放状态和静音状态（常用组合）
+ *
+ * 使用 shallow 比较，仅当 isPlaying 或 muted 变化时重渲染。
+ *
+ * @param id - 项目 ID
+ * @returns { isPlaying: boolean, muted: boolean }
+ *
+ * @example
+ * ```tsx
+ * const VideoCard = ({ item }) => {
+ *   const { isPlaying, muted } = usePlaybackItemState(item.id)
+ *   const { onEnded } = usePlaybackActions()
+ *
+ *   return (
+ *     <video
+ *       autoPlay={isPlaying}
+ *       muted={muted}
+ *       onEnded={onEnded}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export declare function usePlaybackItemState(id: string): {
+    isPlaying: boolean;
+    muted: boolean;
+};
+/**
+ * 播放队列命名空间
+ *
+ * 非 Hook 版本的 API，用于：
+ * - 组件外部调用（如事件回调、工具函数）
+ * - 不在 React 组件中的场景
+ * - 需要命令式调用的场景
+ *
+ * @example
+ * ```tsx
+ * // 在事件回调中使用
+ * const handleClick = () => {
+ *   PlaybackQueue.play('home', 'item-1')
+ * }
+ *
+ * // 在非组件代码中使用
+ * PlaybackQueue.toggleMute()
+ *
+ * // 获取当前状态快照
+ * const state = PlaybackQueue.getState()
+ * console.log('当前播放:', state.currentId)
+ *
+ * // 订阅状态变化
+ * const unsubscribe = PlaybackQueue.subscribeCurrentId((currentId, prevId) => {
+ *   console.log('播放变化:', prevId, '->', currentId)
+ * })
+ * // 不再需要时取消订阅
+ * unsubscribe()
+ * ```
+ */
+export declare const PlaybackQueue: {
+    /**
+     * 获取当前状态快照（非响应式）
+     *
+     * @returns 当前完整状态
+     */
+    readonly getState: () => PlaybackQueueState;
+    /**
+     * 设置某个 source 的播放列表
+     *
+     * @see {@link PlaybackQueueActions.setSource}
+     */
+    readonly setSource: (source: string, ids: string[], autoPlay?: boolean | undefined) => void;
+    /**
+     * 向某个 source 追加项目
+     *
+     * @see {@link PlaybackQueueActions.appendToSource}
+     */
+    readonly appendToSource: (source: string, ids: string[]) => void;
+    /**
+     * 移除某个 source
+     *
+     * @see {@link PlaybackQueueActions.removeSource}
+     */
+    readonly removeSource: (source: string) => void;
+    /**
+     * 播放指定项目
+     *
+     * @see {@link PlaybackQueueActions.play}
+     */
+    readonly play: (source: string, id: string) => void;
+    /**
+     * 播放指定项目（自动查找 source）
+     *
+     * @see {@link PlaybackQueueActions.playById}
+     */
+    readonly playById: (id: string) => void;
+    /**
+     * 播放下一个
+     *
+     * @see {@link PlaybackQueueActions.next}
+     */
+    readonly next: () => void;
+    /**
+     * 播放上一个
+     *
+     * @see {@link PlaybackQueueActions.prev}
+     */
+    readonly prev: () => void;
+    /**
+     * 停止播放
+     *
+     * @see {@link PlaybackQueueActions.stop}
+     */
+    readonly stop: () => void;
+    /**
+     * 播放完成回调
+     *
+     * @see {@link PlaybackQueueActions.onEnded}
+     */
+    readonly onEnded: () => void;
+    /**
+     * 设置静音状态
+     *
+     * @see {@link PlaybackQueueActions.setMuted}
+     */
+    readonly setMuted: (muted: boolean) => void;
+    /**
+     * 切换静音状态
+     *
+     * @see {@link PlaybackQueueActions.toggleMute}
+     */
+    readonly toggleMute: () => void;
+    /**
+     * 设置循环播放
+     *
+     * @see {@link PlaybackQueueActions.setLoop}
+     */
+    readonly setLoop: (loop: boolean) => void;
+    /**
+     * 重置所有状态
+     *
+     * @see {@link PlaybackQueueActions.reset}
+     */
+    readonly reset: () => void;
+    /**
+     * 订阅当前播放 ID 变化
+     *
+     * @param callback - 回调函数，参数为 (新值, 旧值)
+     * @returns 取消订阅函数
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = PlaybackQueue.subscribeCurrentId((currentId, prevId) => {
+     *   console.log('播放变化:', prevId, '->', currentId)
+     * })
+     *
+     * // 清理时取消订阅
+     * unsubscribe()
+     * ```
+     */
+    readonly subscribeCurrentId: (callback: (currentId: string | null, prevId: string | null) => void) => () => void;
+    /**
+     * 订阅 activeSource 变化
+     *
+     * @param callback - 回调函数，参数为 (新值, 旧值)
+     * @returns 取消订阅函数
+     */
+    readonly subscribeActiveSource: (callback: (source: string | null, prevSource: string | null) => void) => () => void;
+    /**
+     * 订阅静音状态变化
+     *
+     * @param callback - 回调函数，参数为 (新值, 旧值)
+     * @returns 取消订阅函数
+     */
+    readonly subscribeMuted: (callback: (muted: boolean, prevMuted: boolean) => void) => () => void;
+};
+export {};
+//# sourceMappingURL=playback-queue-store.d.ts.map

package/dist/media/playback-queue-store.d.ts.map

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

package/dist/media/playback-queue-store.js

@@ -0,0 +1,614 @@
+/**
+ * @fileoverview 播放队列状态管理 (Zustand)
+ *
+ * 支持多 Tab / 多页面场景，全局只有一个视频在播放。
+ *
+ * @module playback-queue-store
+ * @see {@link ./playback-queue-store.md} 详细文档
+ */
+import { create } from 'zustand';
+import { subscribeWithSelector } from 'zustand/middleware';
+import { useShallow } from 'zustand/react/shallow';
+// ============================================================================
+// Initial State - 初始状态
+// ============================================================================
+/**
+ * 初始状态
+ *
+ * @internal
+ */
+const initialState = {
+    sources: {},
+    itemIdToSource: {},
+    activeSource: null,
+    currentId: null,
+    muted: true, // 默认静音，符合浏览器自动播放策略
+    loop: true, // 默认循环播放
+};
+// ============================================================================
+// Helper Functions - 辅助函数
+// ============================================================================
+/**
+ * 更新单个 source 的反向索引
+ *
+ * @param currentIndex - 当前的反向索引
+ * @param sourceName - source 名称
+ * @param oldIds - 旧的 ID 列表
+ * @param newIds - 新的 ID 列表
+ * @returns 更新后的反向索引
+ *
+ * @internal
+ */
+function updateReverseIndexForSource(currentIndex, sourceName, oldIds, newIds) {
+    const index = { ...currentIndex };
+    // 移除旧的映射
+    for (const id of oldIds) {
+        if (index[id] === sourceName) {
+            delete index[id];
+        }
+    }
+    // 添加新的映射
+    for (const id of newIds) {
+        index[id] = sourceName;
+    }
+    return index;
+}
+// ============================================================================
+// Store - Zustand Store 定义
+// ============================================================================
+/**
+ * 播放队列 Zustand Store
+ *
+ * 使用 `subscribeWithSelector` 中间件支持选择性订阅。
+ *
+ * @example
+ * ```tsx
+ * // 直接使用 store（不推荐，建议使用封装的 hooks）
+ * const currentId = usePlaybackQueueStore(state => state.currentId)
+ * ```
+ */
+export const usePlaybackQueueStore = create()(subscribeWithSelector((set, get) => ({
+    ...initialState,
+    setSource: (source, ids, autoPlay = false) => {
+        if (!source) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn('[PlaybackQueue] source name is required');
+            }
+            return;
+        }
+        const uniqueIds = [...new Set(ids || [])];
+        set(state => {
+            var _a;
+            const oldIds = ((_a = state.sources[source]) === null || _a === void 0 ? void 0 : _a.itemIds) || [];
+            const newSources = {
+                ...state.sources,
+                [source]: { itemIds: uniqueIds },
+            };
+            const newIndex = updateReverseIndexForSource(state.itemIdToSource, source, oldIds, uniqueIds);
+            // 检查当前播放的项目是否还在列表中
+            let newCurrentId = state.currentId;
+            let newActiveSource = state.activeSource;
+            if (state.activeSource === source && state.currentId) {
+                if (!uniqueIds.includes(state.currentId)) {
+                    // 当前播放的项目不在新列表中
+                    newCurrentId = autoPlay && uniqueIds.length > 0 ? uniqueIds[0] : null;
+                }
+            }
+            // 如果要自动播放且当前没有在播放
+            if (autoPlay && uniqueIds.length > 0 && !state.currentId) {
+                newActiveSource = source;
+                newCurrentId = uniqueIds[0];
+            }
+            return {
+                sources: newSources,
+                itemIdToSource: newIndex,
+                activeSource: newActiveSource,
+                currentId: newCurrentId,
+            };
+        });
+    },
+    appendToSource: (source, ids) => {
+        if (!source || !ids || ids.length === 0)
+            return;
+        set(state => {
+            const sourceData = state.sources[source];
+            const existingIds = (sourceData === null || sourceData === void 0 ? void 0 : sourceData.itemIds) || [];
+            const existingSet = new Set(existingIds);
+            const newIds = ids.filter(id => !existingSet.has(id));
+            if (newIds.length === 0)
+                return state;
+            const allIds = [...existingIds, ...newIds];
+            const newIndex = { ...state.itemIdToSource };
+            for (const id of newIds) {
+                newIndex[id] = source;
+            }
+            return {
+                sources: {
+                    ...state.sources,
+                    [source]: { itemIds: allIds },
+                },
+                itemIdToSource: newIndex,
+            };
+        });
+    },
+    removeSource: (source) => {
+        set(state => {
+            const sourceData = state.sources[source];
+            if (!sourceData)
+                return state;
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { [source]: _removed, ...restSources } = state.sources;
+            // 清理反向索引
+            const newIndex = { ...state.itemIdToSource };
+            for (const id of sourceData.itemIds) {
+                if (newIndex[id] === source) {
+                    delete newIndex[id];
+                }
+            }
+            // 如果移除的是当前激活的 source，停止播放
+            if (state.activeSource === source) {
+                return {
+                    sources: restSources,
+                    itemIdToSource: newIndex,
+                    activeSource: null,
+                    currentId: null,
+                };
+            }
+            return {
+                sources: restSources,
+                itemIdToSource: newIndex,
+            };
+        });
+    },
+    play: (source, id) => {
+        const { sources } = get();
+        const sourceData = sources[source];
+        if (!sourceData) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[PlaybackQueue] Source "${source}" not found`);
+            }
+            return;
+        }
+        if (!sourceData.itemIds.includes(id)) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[PlaybackQueue] Item "${id}" not found in source "${source}"`);
+            }
+            return;
+        }
+        set({
+            activeSource: source,
+            currentId: id,
+        });
+    },
+    playById: (id) => {
+        var _a;
+        const { sources, activeSource, itemIdToSource } = get();
+        // 优先检查当前 activeSource
+        if (activeSource && ((_a = sources[activeSource]) === null || _a === void 0 ? void 0 : _a.itemIds.includes(id))) {
+            set({ currentId: id });
+            return;
+        }
+        // 使用反向索引快速查找
+        const source = itemIdToSource[id];
+        if (!source) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[PlaybackQueue] Item "${id}" not found in any source`);
+            }
+            return;
+        }
+        set({
+            activeSource: source,
+            currentId: id,
+        });
+    },
+    next: () => {
+        const { sources, activeSource, currentId, loop } = get();
+        if (!activeSource)
+            return;
+        const sourceData = sources[activeSource];
+        if (!sourceData || sourceData.itemIds.length === 0)
+            return;
+        // 如果没有当前播放项，播放第一个
+        if (!currentId) {
+            set({ currentId: sourceData.itemIds[0] });
+            return;
+        }
+        const currentIndex = sourceData.itemIds.indexOf(currentId);
+        if (currentIndex === -1) {
+            set({ currentId: sourceData.itemIds[0] });
+            return;
+        }
+        const nextIndex = currentIndex + 1;
+        if (nextIndex >= sourceData.itemIds.length) {
+            // 已是最后一个
+            set({ currentId: loop ? sourceData.itemIds[0] : null });
+            return;
+        }
+        set({ currentId: sourceData.itemIds[nextIndex] });
+    },
+    prev: () => {
+        const { sources, activeSource, currentId, loop } = get();
+        if (!activeSource)
+            return;
+        const sourceData = sources[activeSource];
+        if (!sourceData || sourceData.itemIds.length === 0)
+            return;
+        if (!currentId) {
+            set({ currentId: sourceData.itemIds[sourceData.itemIds.length - 1] });
+            return;
+        }
+        const currentIndex = sourceData.itemIds.indexOf(currentId);
+        if (currentIndex === -1) {
+            set({ currentId: sourceData.itemIds[0] });
+            return;
+        }
+        const prevIndex = currentIndex - 1;
+        if (prevIndex < 0) {
+            set({
+                currentId: loop ? sourceData.itemIds[sourceData.itemIds.length - 1] : null
+            });
+            return;
+        }
+        set({ currentId: sourceData.itemIds[prevIndex] });
+    },
+    stop: () => {
+        set({ currentId: null });
+    },
+    onEnded: () => {
+        get().next();
+    },
+    setMuted: (muted) => {
+        set({ muted });
+    },
+    toggleMute: () => {
+        set(state => ({ muted: !state.muted }));
+    },
+    setLoop: (loop) => {
+        set({ loop });
+    },
+    reset: () => {
+        set(initialState);
+    },
+})));
+// ============================================================================
+// Selectors - 选择器（静态引用，避免重复创建）
+// ============================================================================
+/** @internal */
+const selectActions = (state) => ({
+    setSource: state.setSource,
+    appendToSource: state.appendToSource,
+    removeSource: state.removeSource,
+    play: state.play,
+    playById: state.playById,
+    next: state.next,
+    prev: state.prev,
+    stop: state.stop,
+    onEnded: state.onEnded,
+    setMuted: state.setMuted,
+    toggleMute: state.toggleMute,
+    setLoop: state.setLoop,
+    reset: state.reset,
+});
+/** @internal */
+const selectMuted = (state) => state.muted;
+/** @internal */
+const selectCurrentId = (state) => state.currentId;
+/** @internal */
+const selectActiveSource = (state) => state.activeSource;
+/** @internal */
+const selectLoop = (state) => state.loop;
+// ============================================================================
+// Hooks - React Hooks（选择性订阅，性能优化）
+// ============================================================================
+/**
+ * 获取播放队列操作方法
+ *
+ * 使用 shallow 比较，避免不必要的重渲染。
+ * 返回的方法引用稳定，可以安全地用作依赖项。
+ *
+ * @returns 所有操作方法
+ *
+ * @example
+ * ```tsx
+ * const { play, stop, next, prev, toggleMute, onEnded } = usePlaybackActions()
+ *
+ * // 在视频组件中
+ * <video
+ *   onEnded={onEnded}
+ *   onClick={() => play('home', item.id)}
+ * />
+ *
+ * // 控制按钮
+ * <button onClick={prev}>上一个</button>
+ * <button onClick={next}>下一个</button>
+ * <button onClick={toggleMute}>静音</button>
+ * ```
+ */
+export function usePlaybackActions() {
+    return usePlaybackQueueStore(useShallow(selectActions));
+}
+/**
+ * 判断指定项目是否正在播放
+ *
+ * 选择性订阅，只有当该项目的播放状态变化时才会重渲染。
+ * 这是性能最优的播放状态判断方式。
+ *
+ * @param id - 项目 ID
+ * @returns 是否正在播放
+ *
+ * @example
+ * ```tsx
+ * const VideoCard = ({ item }) => {
+ *   const isPlaying = usePlaybackIsPlaying(item.id)
+ *
+ *   return (
+ *     <video autoPlay={isPlaying} muted />
+ *   )
+ * }
+ * ```
+ */
+export function usePlaybackIsPlaying(id) {
+    return usePlaybackQueueStore(state => state.currentId === id);
+}
+/**
+ * 获取静音状态
+ *
+ * @returns 是否静音
+ *
+ * @example
+ * ```tsx
+ * const muted = usePlaybackMuted()
+ *
+ * <video muted={muted} />
+ * ```
+ */
+export function usePlaybackMuted() {
+    return usePlaybackQueueStore(selectMuted);
+}
+/**
+ * 获取当前播放的项目 ID
+ *
+ * @returns 当前播放的 ID，没有播放时为 null
+ *
+ * @example
+ * ```tsx
+ * const currentId = usePlaybackCurrentId()
+ *
+ * if (currentId) {
+ *   console.log('正在播放:', currentId)
+ * }
+ * ```
+ */
+export function usePlaybackCurrentId() {
+    return usePlaybackQueueStore(selectCurrentId);
+}
+/**
+ * 获取当前激活的 source 名称
+ *
+ * @returns source 名称，没有激活时为 null
+ *
+ * @example
+ * ```tsx
+ * const activeSource = usePlaybackActiveSource()
+ *
+ * // 高亮当前激活的 Tab
+ * <Tab active={activeSource === 'home'}>首页</Tab>
+ * ```
+ */
+export function usePlaybackActiveSource() {
+    return usePlaybackQueueStore(selectActiveSource);
+}
+/**
+ * 获取循环播放状态
+ *
+ * @returns 是否循环播放
+ *
+ * @example
+ * ```tsx
+ * const loop = usePlaybackLoop()
+ * const { setLoop } = usePlaybackActions()
+ *
+ * <button onClick={() => setLoop(!loop)}>
+ *   {loop ? '循环开' : '循环关'}
+ * </button>
+ * ```
+ */
+export function usePlaybackLoop() {
+    return usePlaybackQueueStore(selectLoop);
+}
+/**
+ * 获取指定 source 的项目 ID 列表
+ *
+ * @param source - source 名称
+ * @returns 项目 ID 列表，source 不存在时返回空数组
+ *
+ * @example
+ * ```tsx
+ * const homeItems = usePlaybackSourceItems('home')
+ *
+ * console.log('首页有', homeItems.length, '个视频')
+ * ```
+ */
+export function usePlaybackSourceItems(source) {
+    return usePlaybackQueueStore(state => { var _a, _b; return (_b = (_a = state.sources[source]) === null || _a === void 0 ? void 0 : _a.itemIds) !== null && _b !== void 0 ? _b : []; });
+}
+/**
+ * 获取单个 item 的播放状态和静音状态（常用组合）
+ *
+ * 使用 shallow 比较，仅当 isPlaying 或 muted 变化时重渲染。
+ *
+ * @param id - 项目 ID
+ * @returns { isPlaying: boolean, muted: boolean }
+ *
+ * @example
+ * ```tsx
+ * const VideoCard = ({ item }) => {
+ *   const { isPlaying, muted } = usePlaybackItemState(item.id)
+ *   const { onEnded } = usePlaybackActions()
+ *
+ *   return (
+ *     <video
+ *       autoPlay={isPlaying}
+ *       muted={muted}
+ *       onEnded={onEnded}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function usePlaybackItemState(id) {
+    return usePlaybackQueueStore(useShallow(state => ({
+        isPlaying: state.currentId === id,
+        muted: state.muted,
+    })));
+}
+// ============================================================================
+// Non-Hook API - 非 Hook API（用于组件外部或副作用）
+// ============================================================================
+/**
+ * 播放队列命名空间
+ *
+ * 非 Hook 版本的 API，用于：
+ * - 组件外部调用（如事件回调、工具函数）
+ * - 不在 React 组件中的场景
+ * - 需要命令式调用的场景
+ *
+ * @example
+ * ```tsx
+ * // 在事件回调中使用
+ * const handleClick = () => {
+ *   PlaybackQueue.play('home', 'item-1')
+ * }
+ *
+ * // 在非组件代码中使用
+ * PlaybackQueue.toggleMute()
+ *
+ * // 获取当前状态快照
+ * const state = PlaybackQueue.getState()
+ * console.log('当前播放:', state.currentId)
+ *
+ * // 订阅状态变化
+ * const unsubscribe = PlaybackQueue.subscribeCurrentId((currentId, prevId) => {
+ *   console.log('播放变化:', prevId, '->', currentId)
+ * })
+ * // 不再需要时取消订阅
+ * unsubscribe()
+ * ```
+ */
+export const PlaybackQueue = {
+    /**
+     * 获取当前状态快照（非响应式）
+     *
+     * @returns 当前完整状态
+     */
+    getState: () => usePlaybackQueueStore.getState(),
+    /**
+     * 设置某个 source 的播放列表
+     *
+     * @see {@link PlaybackQueueActions.setSource}
+     */
+    setSource: (...args) => usePlaybackQueueStore.getState().setSource(...args),
+    /**
+     * 向某个 source 追加项目
+     *
+     * @see {@link PlaybackQueueActions.appendToSource}
+     */
+    appendToSource: (...args) => usePlaybackQueueStore.getState().appendToSource(...args),
+    /**
+     * 移除某个 source
+     *
+     * @see {@link PlaybackQueueActions.removeSource}
+     */
+    removeSource: (...args) => usePlaybackQueueStore.getState().removeSource(...args),
+    /**
+     * 播放指定项目
+     *
+     * @see {@link PlaybackQueueActions.play}
+     */
+    play: (...args) => usePlaybackQueueStore.getState().play(...args),
+    /**
+     * 播放指定项目（自动查找 source）
+     *
+     * @see {@link PlaybackQueueActions.playById}
+     */
+    playById: (...args) => usePlaybackQueueStore.getState().playById(...args),
+    /**
+     * 播放下一个
+     *
+     * @see {@link PlaybackQueueActions.next}
+     */
+    next: () => usePlaybackQueueStore.getState().next(),
+    /**
+     * 播放上一个
+     *
+     * @see {@link PlaybackQueueActions.prev}
+     */
+    prev: () => usePlaybackQueueStore.getState().prev(),
+    /**
+     * 停止播放
+     *
+     * @see {@link PlaybackQueueActions.stop}
+     */
+    stop: () => usePlaybackQueueStore.getState().stop(),
+    /**
+     * 播放完成回调
+     *
+     * @see {@link PlaybackQueueActions.onEnded}
+     */
+    onEnded: () => usePlaybackQueueStore.getState().onEnded(),
+    /**
+     * 设置静音状态
+     *
+     * @see {@link PlaybackQueueActions.setMuted}
+     */
+    setMuted: (...args) => usePlaybackQueueStore.getState().setMuted(...args),
+    /**
+     * 切换静音状态
+     *
+     * @see {@link PlaybackQueueActions.toggleMute}
+     */
+    toggleMute: () => usePlaybackQueueStore.getState().toggleMute(),
+    /**
+     * 设置循环播放
+     *
+     * @see {@link PlaybackQueueActions.setLoop}
+     */
+    setLoop: (...args) => usePlaybackQueueStore.getState().setLoop(...args),
+    /**
+     * 重置所有状态
+     *
+     * @see {@link PlaybackQueueActions.reset}
+     */
+    reset: () => usePlaybackQueueStore.getState().reset(),
+    /**
+     * 订阅当前播放 ID 变化
+     *
+     * @param callback - 回调函数，参数为 (新值, 旧值)
+     * @returns 取消订阅函数
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = PlaybackQueue.subscribeCurrentId((currentId, prevId) => {
+     *   console.log('播放变化:', prevId, '->', currentId)
+     * })
+     *
+     * // 清理时取消订阅
+     * unsubscribe()
+     * ```
+     */
+    subscribeCurrentId: (callback) => usePlaybackQueueStore.subscribe(state => state.currentId, callback),
+    /**
+     * 订阅 activeSource 变化
+     *
+     * @param callback - 回调函数，参数为 (新值, 旧值)
+     * @returns 取消订阅函数
+     */
+    subscribeActiveSource: (callback) => usePlaybackQueueStore.subscribe(state => state.activeSource, callback),
+    /**
+     * 订阅静音状态变化
+     *
+     * @param callback - 回调函数，参数为 (新值, 旧值)
+     * @returns 取消订阅函数
+     */
+    subscribeMuted: (callback) => usePlaybackQueueStore.subscribe(state => state.muted, callback),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -65,6 +65,7 @@
     "react": ">=18"
   },
   "dependencies": {
+    "zustand": "^5.0.11",
     "@microsoft/fetch-event-source": "^2.0.1",
     "@use-gesture/react": "^10.3.1",
     "bowser": "^2.14.1",