webwallgl 1.1.0 → 1.3.16

package/types.d.ts

@@ -26,15 +26,42 @@ export type Source = {
     webEntry?(signal?: AbortSignal): Promise<{
         url: string;
     } | null>;
+    /**
+     * 媒体壁纸（video / gif / image）的资源 URL。`project.type` 为这三者之一时
+     * 由 mount 调用；省略则回退到 `{httpSource 基址}/{project.file}`。
+     *
+     * 与 `webEntry` 分开而不是复用同一个方法：`webEntry` 的语义是「HTML 文档入口」
+     * （交给 iframe 加载并注入 shim），媒体是「一个可直接喂给 <video>/<img> 的资源」，
+     * 两者的消费方与失败模式都不同。`webEntry` 在 1.0.0 已公开，也不宜改语义。
+     *
+     * `type` 可选，用于纠正 project.json 里缺失或不准的类型；不给则以 project.type 为准。
+     */
+    mediaEntry?(signal?: AbortSignal): Promise<{
+        url: string;
+        type?: string;
+    } | null>;
     /**
      * 缓存键。相同键的 scene.pkg 命中库内缓存，避免重复解析上百 MB 的包
      * （暂停恢复、改属性都不该重新走一遍解析）。省略则不参与缓存。
      */
     readonly key?: string;
+    /**
+     * 释放本来源占用的资源。实例 destroy() / 换源时调用一次。
+     *
+     * 目前只有 `mediaSource(File)` 需要：本地文件走 `URL.createObjectURL`，
+     * 不 revoke 就是每换一次壁纸泄漏一个几十 MB 的 blob。
+     */
+    dispose?(): void;
 };
 /**
- * 指针状态提供者。默认实现监听传入 canvas 自身的 pointer 事件；
- * 传 null 则禁用指针交互（壁纸脚本读到的指针恒为静止居中）。
+ * 指针状态提供者（**当前未接线**）。
+ *
+ * 默认指针来自 canvas 自身的 pointer 事件，由 mountScene 按 `cfg.canvas` 建立，
+ * 与本接口无关。要从外部喂指针（桌面壁纸窗口在 underlay 层收不到鼠标）请用
+ * `SceneInstance.pushPointer(u, v, buttons)` —— 那是引擎实际消费的推模式通道。
+ *
+ * 本接口保留是为了不破坏 1.0.0 已公开的类型；注意 `rightDown` 即便接线也不会
+ * 生效：引擎的指针状态只消费按键位掩码的 bit0（左键），全库无壁纸读右键。
  */
 export type PointerSource = {
     /** 归一化坐标 0..1，相对 canvas 左上角；y 向下 */
@@ -49,6 +76,17 @@ export type PointerSource = {
  * 音频频谱提供者（音频响应壁纸用）。返回当前快照，不推进状态 ——
  * 推进由库的渲染循环按场景时间驱动，保证同一时刻取到同一份数据。
  * 默认是内置的确定性模拟源（无需麦克风权限，离线可复现）。
+ *
+ * **拉模式**：渲染循环每帧调一次 `snapshot()`。宿主每帧推 128 个浮点要走
+ * 跨语言桥的字符串拼接与 JS 解析，60fps 下开销可观；让渲染器主动拉，
+ * 宿主用同步原生桥直接返回即可。
+ *
+ * 契约：`left`/`right` 各 **64 段**、值域 **0..1**（已归一化）。段数不足 64
+ * 会补零，多于 64 会截断。32/16 段降采样与 level/silent 由库自行派生，
+ * 消费方（shader uniform、粒子、文字脚本）不区分数据来源。
+ *
+ * **scene 与 web 壁纸都生效**：网页壁纸经 iframe shim 的音频泵收到同一份数据
+ * （泵逐帧选源，所以 mount() 之后再 setAudio 也能生效）。
  */
 export type AudioSource = {
     /** 左右声道各 64 段频谱，值域 0..1 */
@@ -57,20 +95,141 @@ export type AudioSource = {
         right: Float32Array | number[];
     };
 };
+/** WE 播放态：0=停止 1=播放 2=暂停（与 MediaPlaybackEvent 枚举一致） */
+export type MediaPlaybackState = 0 | 1 | 2;
+/**
+ * 媒体配色的三元组。**必须是带链式方法的实例，不能是普通数组或对象**：
+ * 真实语料里的脚本会写 `event.primaryColor.subtract(old).multiply(t).add(old)`，
+ * 给数组会 TypeError 熔断整个脚本（症状是「换歌后整层不见了」）。
+ * 用 `createMediaSource()` 构造快照可自动保证类型正确。
+ */
+export type MediaColor = {
+    x: number;
+    y: number;
+    z: number;
+    add(o: MediaColor): MediaColor;
+    subtract(o: MediaColor): MediaColor;
+    multiply(k: number | MediaColor): MediaColor;
+};
+/** 系统媒体快照。字段名与 WE 的 media* 回调载荷一致 */
+export type MediaSnapshot = {
+    /** 有没有正在播放的媒体会话；false 时其余字段无意义 */
+    hasMedia: boolean;
+    state: MediaPlaybackState;
+    title: string;
+    artist: string;
+    album: string;
+    albumArtist: string;
+    /** 播放进度与总时长，单位**秒**（不是 0..1 比例） */
+    position: number;
+    duration: number;
+    hasThumbnail: boolean;
+    /**
+     * 真实封面图（data URL 或同源 URL）。宿主能拿到系统封面时给这里，
+     * 网页壁纸的 `mediaThumbnailChanged(e)` 会直接收到它作为 `e.thumbnail`。
+     *
+     * 留空时库用 primary/secondary 生成一张渐变占位图 —— 保证语料里
+     * `img.src = e.thumbnail` 那类写法不会拿到空串，但显示的不是真专辑封面。
+     *
+     * 注意场景（WebGL）壁纸不消费图片本体，其脚本只读 `e.hasThumbnail` 与取色，
+     * 所以这个字段只对网页壁纸有效。
+     */
+    thumbnail?: string;
+    /** 封面取色。见 MediaColor 的类型约束 */
+    primaryColor: MediaColor;
+    secondaryColor: MediaColor;
+    tertiaryColor: MediaColor;
+    textColor: MediaColor;
+    highContrastColor: MediaColor;
+    /** 播放列表内的曲目序号（换歌检测用） */
+    trackIndex: number;
+    /** 歌词行：[秒, 文本][]，按时间升序 */
+    lyrics: Array<[number, string]>;
+    /** 当前歌词行与其下标（由 position 定位，库不重算） */
+    lyricLine: string;
+    lyricIndex: number;
+};
 /**
- * 系统媒体信息提供者（"正在播放"类壁纸用）。默认是内置模拟源。
- * 接真实数据时替换本接口即可，字段名与 WE 的 media* 回调一致。
+ * 系统媒体源（"正在播放"类壁纸用）。默认是内置模拟源。
+ *
+ * **scene 与 web 壁纸共用同一个实例**：宿主装一次，两类壁纸看到同一份 Now Playing。
+ * 库每帧调 `update(tSec)` 推进、读 `snapshot` 取值，并自动 diff 出 WE 的
+ * mediaStatusChanged / mediaPropertiesChanged / mediaPlaybackChanged /
+ * mediaThumbnailChanged 四个回调派发给壁纸脚本。
+ *
+ * 五个控制方法是**反向控制**：壁纸里的"上一曲/下一曲/播放暂停"按钮会调到这里，
+ * 由你转发给真实播放器。库只负责调用并在之后立刻重新派发一次事件。
+ *
+ * 自己实现全部字段很繁琐，用 `createMediaSource(partial)` 只给已知字段即可。
  */
 export type MediaSource = {
-    snapshot(): {
-        playing: boolean;
-        title?: string;
-        artist?: string;
-        album?: string;
-        /** 0..1 播放进度 */
-        position?: number;
-        durationSeconds?: number;
-    };
+    /** 每帧由渲染循环推进（tSec 为场景时间，秒）。无状态的实现可留空函数 */
+    update?(tSec: number): void;
+    readonly snapshot: MediaSnapshot;
+    skipNext?(): void;
+    skipPrevious?(): void;
+    play?(): void;
+    pause?(): void;
+    playPause?(): void;
+};
+/**
+ * `createMediaSource(init, controls)` 的 init：宿主通常拿得到的那部分字段，
+ * 其余（配色、歌词行、trackIndex）由库补默认值。
+ *
+ * 类型本体放在这里而不是 api/media-source.ts，是因为只有本文件会被
+ * tsconfig.lib-types.json 编成发布的 types.d.ts —— 定义在别处的话
+ * 消费方 `import { createMediaSource } from "webwallgl"` 摸不到入参类型。
+ */
+export type MediaSourceInit = {
+    hasMedia?: boolean;
+    /** 0=停止 1=播放 2=暂停；也接受布尔 playing（true→1、false→2） */
+    state?: MediaPlaybackState;
+    playing?: boolean;
+    title?: string;
+    artist?: string;
+    album?: string;
+    albumArtist?: string;
+    /** 秒 */
+    position?: number;
+    duration?: number;
+    hasThumbnail?: boolean;
+    /**
+     * 真实封面图（data URL 或同源 URL）。给了就直接透给网页壁纸的
+     * `mediaThumbnailChanged(e).thumbnail`；不给则库生成渐变占位图。
+     * 传了非空值时 hasThumbnail 自动视为 true
+     */
+    thumbnail?: string;
+    primaryColor?: MediaColorInit;
+    secondaryColor?: MediaColorInit;
+    tertiaryColor?: MediaColorInit;
+    textColor?: MediaColorInit;
+    highContrastColor?: MediaColorInit;
+    trackIndex?: number;
+    /** [秒, 文本] 按时间升序；库按 position 定位当前行 */
+    lyrics?: Array<[number, string]>;
+};
+/** `mediaColor()` 与配色字段接受的形态 */
+export type MediaColorInit = number | number[] | {
+    x: number;
+    y: number;
+    z: number;
+} | MediaColor;
+/** `createMediaSource(init, controls)` 的 controls：宿主转发给真实播放器 */
+export type MediaSourceControls = {
+    skipNext?(): void;
+    skipPrevious?(): void;
+    play?(): void;
+    pause?(): void;
+    playPause?(): void;
+};
+/** 壁纸侧可用的媒体控制面（SceneInstance.media） */
+export type MediaControl = {
+    readonly snapshot: MediaSnapshot;
+    skipNext(): MediaSnapshot;
+    skipPrevious(): MediaSnapshot;
+    play(): MediaSnapshot;
+    pause(): MediaSnapshot;
+    playPause(): MediaSnapshot;
 };
 /** 渲染开关。调试用，默认全开；对应旧 types.ts 的 SKIP_* 常量取反 */
 export type FeatureFlags = {
@@ -125,13 +284,19 @@ export type MountOptions = {
     autoplay?: boolean;
     /** 用户属性覆盖值（键为 project.json 里的属性名） */
     properties?: Record<string, PropertyValue>;
-    /** 指针源。默认跟随 canvas 自身 pointer 事件；null = 禁用 */
+    /** 指针源。**当前未接线**，见 PointerSource 说明；外部喂指针请用 pushPointer() */
     pointer?: PointerSource | null;
-    /** 音频源。默认内置确定性模拟；null = 禁用（频谱恒为 0） */
+    /**
+     * 音频频谱源。默认内置确定性模拟；null = 禁用（频谱恒为 0）。
+     * 挂载后可用 `SceneInstance.setAudio()` 再换（SSE 等异步数据源常在挂载后才就绪）。
+     */
     audio?: AudioSource | null;
-    /** 系统媒体源。默认内置模拟；null = 禁用 */
+    /**
+     * 系统媒体源（Now Playing）。默认内置模拟；null = 禁用。
+     * scene 与 web 壁纸共用同一个实例；挂载后可用 `setMedia()` 再换。
+     */
     media?: MediaSource | null;
-    /** 渲染开关（调试用） */
+    /** 渲染开关（调试用）。**当前未接线** */
     features?: Partial<FeatureFlags>;
     /** 诊断回调。替代旧的 GET /diag 上报 */
     onDiagnostic?: SceneEvents["diagnostic"];
@@ -163,14 +328,86 @@ export type SceneInstance = {
     setProperties(props: Record<string, PropertyValue>): void;
     /** 当前生效的属性值（扁平化后的 name → value） */
     getProperties(): Record<string, PropertyValue>;
+    /**
+     * 换音频频谱源。传 null 回落内置模拟源。
+     *
+     * 与挂载选项 `audio` 等价，但可在任何时刻调用 —— 宿主的频谱通道
+     * （SSE / 原生桥 / WebAudio）常常在 mount() 之后才就绪。
+     * **换场景不清空**：装一次对之后所有场景生效。
+     *
+     * scene 与 web 壁纸都生效（网页侧经 iframe shim 的音频泵拿到同一份数据）。
+     */
+    setAudio(src: AudioSource | null): void;
+    /**
+     * 换系统媒体源（Now Playing）。传 null 回落内置模拟源。
+     *
+     * 与 `setAudio` 同纪律：**换场景不清空**，装一次对之后所有场景生效。
+     * scene 与 web 壁纸吃同一个实例。
+     */
+    setMedia(src: MediaSource | null): void;
+    /**
+     * 媒体控制面：读当前快照，以及壁纸侧同款的播放控制。
+     *
+     * 调用控制方法会转发给当前 media 源并**立即重新派发一次事件**，
+     * 壁纸里的歌名/封面/进度会同帧更新，不必等下一轮 diff。
+     */
+    readonly media: MediaControl;
+    /**
+     * 外部指针注入：把宿主轮询到的鼠标位置推进壁纸。
+     *
+     * 用于窗口收不到鼠标事件的场景 —— 桌面壁纸叠在桌面 underlay 层，
+     * macOS 下 Finder 的桌面窗口会吃掉事件，且没有「向下透传」的窗口属性。
+     *
+     * @param u 归一化横坐标 0..1（相对画布左缘）
+     * @param v 归一化纵坐标 0..1（相对画布上缘，y 向下）
+     * @param buttons 按键位掩码，同 MouseEvent.buttons；只有 bit0（左键）被消费
+     * @param mods 修饰键位掩码：bit0 ctrl / bit1 shift / bit2 alt / bit3 meta。
+     *   省略等于 0。只有 web 壁纸消费（合成事件的 ctrlKey 等字段）
+     *
+     * 与 canvas 自身的 DOM 指针监听并存，谁后写谁赢。scene 与 web 壁纸都生效，
+     * 媒体壁纸（video/gif/image）没有指针概念，调用静默无效。
+     */
+    pushPointer(u: number, v: number, buttons?: number, mods?: number): void;
+    /**
+     * 外部指针离开本窗口（鼠标移到了别的显示器）。
+     *
+     * **只清按键，保留最后位置** —— 清掉位置会让 xray 开窗跳到相机外、
+     * 视差弹回中心，画面明显抽一下。语义与 DOM 的 mouseleave 一致。
+     */
+    pointerLeave(): void;
+    /**
+     * 外部滚轮注入：把宿主捕获的滚轮 / 触摸板手势推进壁纸。
+     *
+     * **只有 web 壁纸生效。** scene 壁纸静默无效不是遗漏：WE 的场景脚本沙箱
+     * 不暴露任何滚轮 API，实测 194 张场景壁纸零消费（场景包里的 `scroll`
+     * 全都是纹理滚动 shader 的 `g_ScrollSpeed`，与鼠标无关）。
+     *
+     * @param dx 横向滚动量，正 = 内容向右（与 WheelEvent.deltaX 同向同量级）
+     * @param dy 纵向滚动量，正 = 内容向下（与 WheelEvent.deltaY 同向；
+     *   macOS 原生 NSEvent.scrollingDeltaY 是**反向**的，宿主需取反）
+     * @param mode 同 WheelEvent.deltaMode：0 像素 / 1 行 / 2 页。触摸板恒为 0
+     * @param mods 修饰键位掩码，bit0 ctrl。**触摸板双指捏合应映射成 ctrl + 滚轮**
+     *   —— 浏览器就是这样把 macOS 的 magnify 手势喂给网页的，
+     *   OrbitControls / pano2vr 一族都靠 `event.ctrlKey` 区分缩放与滚动
+     *
+     * 位置沿用最后一次 `pushPointer()` 的坐标（滚轮事件本身不带位置）。
+     */
+    pushWheel(dx: number, dy: number, mode?: number, mods?: number): void;
     /** 换场景，复用同一 canvas 与 WebGL 上下文 */
     load(source: Source): Promise<void>;
     /** 释放 GL/视频/音频资源，保留配置（显示器睡眠等场景） */
     release(): void;
     /** 用保留的配置重建 */
     restore(): void;
-    /** 彻底销毁：解绑事件监听、释放全部资源，之后不可再用 */
-    destroy(): void;
+    /**
+     * 彻底销毁：解绑事件监听、释放全部资源，之后不可再用。
+     * `releasePkgCache: true` 连带淘汰本实例 source 的 scene.pkg 解析缓存 ——
+     * 缓存默认跨实例保留（同壁纸重挂不重新下载），宿主"销毁即放弃"的语义
+     * （如桌面壁纸逐张切换）需要显式声明，否则旧包会压在缓存里不落内存。
+     */
+    destroy(opts?: {
+        releasePkgCache?: boolean;
+    }): void;
     readonly stats: FrameStats;
     readonly info: SceneInfo | null;
     /** 事件订阅，返回取消函数 */

package/webwallgl.d.ts

@@ -2,25 +2,66 @@
 //
 // ⚠️ 维护约束：函数签名是**手写的契约面**，全部类型来自 api/types.ts
 // （tsc 自动生成到 dist/lib/types，构建时由 build:lib 拷贝拼接）。
-// 改 api/mount.ts / api/source.ts 的**函数签名**时必须同步本文件 ——
-// 类型本体（MountOptions/SceneInstance/Source 等）改 api/types.ts 即可自动带出。
-
-export {
-  type Fit,
-  type Source,
-  type MountOptions,
-  type SceneInstance,
-  type SceneInfo,
-  type SceneEvents,
-  type FrameStats,
-  type PropertyValue,
-  type FeatureFlags,
-  type PointerSource,
-  type AudioSource,
-  type MediaSource,
-  type DiagnosticLevel,
+// 改 api/index.ts 的**导出清单**或 mount/source/media-source 的**函数签名**时
+// 必须同步本文件 —— 类型本体（MountOptions/SceneInstance/Source/MediaSourceInit
+// 等）改 api/types.ts 即可自动带出。
+//
+// 只在 types.ts 里定义类型：别处（如 media-source.ts）定义的类型不进
+// tsconfig.lib-types.json 的编译范围，本文件 import 它会解析失败。
+//
+// 漏声明一个运行时导出的后果不是"类型弱一点"，而是消费方 import 直接
+// TS2305 编译不过（verify-arch 会比对 api/index.ts 与本文件的导出清单）。
+//
+// ⚠️ 必须 import 后再 export，不能写成 `export { type X } from "./types"`：
+// 后者只做转发导出，**不把名字引入本文件作用域**，下面的函数签名会引用到
+// 未定义标识符（tsc 报 TS2304 × 7）。消费方普遍开着 skipLibCheck，报错被吞掉，
+// 症状是所有导出静默退化成 any —— 库看起来"能用"，实则零类型检查。
+import type {
+  Fit,
+  Source,
+  MountOptions,
+  SceneInstance,
+  SceneInfo,
+  SceneEvents,
+  FrameStats,
+  PropertyValue,
+  FeatureFlags,
+  PointerSource,
+  AudioSource,
+  MediaSource,
+  MediaSnapshot,
+  MediaColor,
+  MediaColorInit,
+  MediaControl,
+  MediaPlaybackState,
+  MediaSourceInit,
+  MediaSourceControls,
+  DiagnosticLevel,
 } from "./types";
 
+export type {
+  Fit,
+  Source,
+  MountOptions,
+  SceneInstance,
+  SceneInfo,
+  SceneEvents,
+  FrameStats,
+  PropertyValue,
+  FeatureFlags,
+  PointerSource,
+  AudioSource,
+  MediaSource,
+  MediaSnapshot,
+  MediaColor,
+  MediaColorInit,
+  MediaControl,
+  MediaPlaybackState,
+  MediaSourceInit,
+  MediaSourceControls,
+  DiagnosticLevel,
+};
+
 export declare function mount(
   el: HTMLElement,
   options: MountOptions,
@@ -40,3 +81,23 @@ export declare function bytesSource(
   project?: unknown,
   key?: string,
 ): Source;
+
+export declare function mediaSource(
+  urlOrFile: string | File | Blob,
+  options?: { type?: "video" | "gif" | "image"; key?: string },
+): Source;
+
+export declare function sniffMediaType(
+  url: string,
+): "video" | "gif" | "image" | null;
+
+export declare function createMediaSource(
+  init?: MediaSourceInit,
+  controls?: MediaSourceControls,
+): MediaSource & { set(patch: MediaSourceInit): void };
+
+export declare function mediaColor(
+  r: MediaColorInit,
+  g?: number,
+  b?: number,
+): MediaColor;