webwallgl 1.0.0-beta1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oneincase <462534624@qq.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,173 @@
+# WebWallGL — Wallpaper Engine scene renderer for the browser
+
+**[简体中文](README.md) | [English](README.en.md)**
+
+## Introduction
+
+WebWallGL is a browser-side renderer for Wallpaper Engine "scene" wallpapers: it faithfully replays workshop scene packages (scene.pkg) in WebGL, with layer effect chains, particles, 3D puppet bones, text widgets, script sandboxes, audio response and live user-property updates.
+
+- Zero runtime dependencies, single-file delivery (ESM ~400KB / gzip ~126KB)
+- Installable via npm or a <script> CDN tag; multiple isolated instances per page
+- This bench is the library's first consumer — everything you see here is public API
+
+## What can you build
+
+WebWallGL is a 'wallpaper-compatible rendering core' — anywhere a "dynamic background" is needed, drop in a WebWallGL instance:
+
+- Wallpaper apps: the core renderer for desktop wallpaper engines (Tauri / Electron / WebView shells), fully replaying WE workshop scenes
+- Websites: animated backgrounds or full-screen hero sections for homepages, landing pages and product sites
+- Dev tools: background layers for dashboards, monitoring walls, terminals and GUI launchers
+- Background plugins: embedded render source for music visualizers, OBS backdrops, digital signage and widget engines
+
+In one line: everything can be a wall. Your app provides a canvas and a source for the scene package — parsing, assembly, the render loop, script sandboxes, pointer and audio are all WebWallGL's job.
+
+## Installation
+
+Three ways to include it — pick one:
+
+```
+// 1) npm + bundler (recommended)
+npm i webwallgl
+import { mount, httpSource } from "webwallgl";
+```
+
+```
+// 2) ESM CDN
+import { mount, httpSource } from "https://cdn.example.com/webwallgl/1.0.0-beta1/webwallgl.min.mjs";
+```
+
+```
+<!-- 3) UMD <script>: exposes the global WebWallGL -->
+<script src="https://cdn.example.com/webwallgl/1.0.0-beta1/webwallgl.global.min.js"></script>
+<script>
+  const { mount, httpSource } = WebWallGL;
+</script>
+```
+
+## Quick start
+
+One canvas plus one source is everything. mount() resolves after the first frame is actually drawn:
+
+```
+<canvas id="wp" style="width:100%;height:400px"></canvas>
+
+import { mount, httpSource } from "webwallgl";
+
+const wp = await mount(document.querySelector("#wp"), {
+  source: httpSource("https://cdn.example.com/wallpapers/3122339805"),
+  fps: 60,
+});
+
+// The instance is ready to use after the first frame:
+wp.pause();
+wp.resume();
+wp.setProperties({ schemecolor: "0.5 0.2 0.8" });
+console.log("live fps:", wp.stats.fps);
+```
+
+The canvas CSS size is the render size: the library aligns the backing store to clientWidth/clientHeight, and the aspect follows container resizes automatically — no manual resize handling.
+
+## Loading scenes: Source
+
+The library makes only two network requests (scene.pkg and optional project.json), so the resource abstraction is one interface with three built-in implementations:
+
+| Factory | Use case |
+| --- | --- |
+| `httpSource(baseUrl, init?)` | HTTP base URL; falls back through the three real layouts: scene.pkg → scenes/scene.pkg → gifscene.pkg |
+| `fileSource(file, project?)` | A local .pkg from &lt;input type=file> or drag & drop |
+| `bytesSource(pkg, project?, key?)` | Bytes already in hand (bundled, IndexedDB cache, custom transport) |
+
+```
+// Local file: drop a scene.pkg into the page to preview it
+input.addEventListener("change", () => {
+  const src = fileSource(input.files[0]);
+  mount(canvas, { source: src });
+});
+```
+
+- httpSource tries the root scene.pkg first and tolerates each fetch separately — WKWebView/custom protocols throw Failed to fetch instead of a 404; the wrong order breaks every wallpaper
+- source.key feeds the library's parse cache: packages with the same key are parsed once (pause/property changes cost zero network)
+- A missing project.json is normal: without a property table, fields fall back to the scene.json snapshot values
+
+## Mount options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `source (required)` | `—` | See Source above |
+| `fit` | `"cover"` | cover crops to fill / contain letterboxes / stretch distorts |
+| `renderDpr` | `1` | Render DPR cap (effective = min(devicePixelRatio, renderDpr)); lower it to save VRAM |
+| `fps` | `60` | FPS cap; skipped frames don't count into stats.fps, so drops are visible |
+| `volume` | `0` | 0..1. Starts muted (autoplay policy); set a non-zero volume after ready |
+| `autoplay` | `true` | When false, stays paused after mount |
+| `properties` | `{}` | Initial user property overrides (keys are property names) |
+| `pointer / audio / media` | `built-in` | Pointer follows the canvas; audio/media are deterministic sims; pass null to disable |
+| `features` | `all on` | Debug switches: models / text / particles / effects / components |
+| `onReady / onError / onDiagnostic` | `—` | Callback surface; can also subscribe later via instance.on() |
+
+## The SceneInstance API
+
+| Member | Description |
+| --- | --- |
+| `pause() / resume() / paused` | Pause/resume. Never remounts the package: video/audio resume from where they were |
+| `setFit(fit) / setFps(n) / setVolume(v)` | Live updates, no remount (the render loop reads them per frame) |
+| `setRenderDpr(dpr)` | Changing DPR rebuilds the canvas; remounts internally (pkg cache hit, no re-download) |
+| `setProperties(props)` | Live property updates: patches the property table / effect constants / script sandboxes in place, no re-fetch |
+| `getProperties()` | The current flattened property value map |
+| `load(source)` | Switch scenes reusing the same canvas and WebGL context; resolves after the first frame |
+| `release() / restore()` | Free GL resources keeping the config (display sleep) / rebuild from the kept config |
+| `destroy()` | Terminal: frees resources, unbinds listeners; the instance is dead afterwards |
+| `stats / info` | Measured FPS ({fps, running}, zeroes out instead of freezing) / scene info (logical size, layer count, has models/particles/text) |
+| `on(ev, fn)` | Subscribe to ready / error / diagnostic; returns an unsubscribe function |
+
+## Events & diagnostics
+
+```
+const off = wp.on("diagnostic", (msg, level) => {
+  // level: "info" | "warn" | "error"
+  console[level === "error" ? "error" : "log"]("[wp]", msg);
+});
+wp.on("error", (err) => showError(err));
+wp.on("ready", (info) => {
+  // info: { width, height, layerCount, hasModels, hasParticles, hasText }
+});
+```
+
+The library ships no fallback page and phones home nowhere: diagnostics and errors arrive via callbacks only. What to do on failure (show a hint, swap the wallpaper, destroy the instance) is your call.
+
+## Multiple instances per page
+
+```
+const a = await mount(c1, { source: httpSource(urlA) });
+const b = await mount(c2, { source: httpSource(urlB) });
+b.pause(); // does not affect a
+```
+
+- Each instance owns a Runtime: config, FPS meter, WebGL context and property table are fully isolated
+- Pointer events bind to each instance's canvas; normalized coordinates are canvas-relative and never capture the page
+- Mind WebGL context limits: browsers allow ~8–16 per page and drop the oldest beyond that
+
+## Lifecycle & caching
+
+- Parsed scene.pkg entries are cached by source.key (up to 2): pause/resume, property changes and setRenderDpr remounts never re-download
+- After release(), stats.running goes false and the FPS reading zeroes out — a stopped meter must not freeze on its last value
+- After destroy() the canvas is yours again; mount() a fresh instance any time
+
+## Troubleshooting
+
+- Black screen with WEBGL2_UNAVAILABLE: no WebGL2 in this environment; there is no software fallback
+- HTTP 404: make sure the httpSource directory really contains a scene.pkg (all three layouts are tried before failing)
+- Failed to fetch with no status: custom-protocol/WKWebView behavior for missing paths — by design; just read the final error
+- stats.fps is 0 while the picture moves: the meter counts committed frames only; browsers suspend rAF for occluded tabs — expected
+- Audio starts late: autoplay policy requires user interaction before sound; that's why volume defaults to 0
+
+## Copyright & compliance
+
+The library code is MIT. Wallpaper Engine workshop assets (scene.pkg, textures, audio/video) remain copyrighted by their authors: point the library only at content you own or are licensed to use, and don't redistribute other people's work through your product.
+
+## Sponsor the author
+
+If this rendering core helped your project, buying the author a coffee is always appreciated. Scan the QR code to sponsor — any amount counts.
+
+| WeChat Pay | Alipay |
+| --- | --- |
+| ![WeChat Pay QR code](imgs/wechat.png) | ![Alipay QR code](imgs/alipay.png) |

package/README.md

@@ -0,0 +1,173 @@
+# WebWallGL —— 浏览器端 WE 场景壁纸渲染库
+
+**[简体中文](README.md) ｜ [English](README.en.md)**
+
+## 简介
+
+WebWallGL 是一个浏览器端的 Wallpaper Engine「scene」场景壁纸渲染库：把创意工坊场景包（scene.pkg）在 WebGL 里实时还原，支持图层效果链、粒子、3D 木偶骨骼、文字挂件、脚本沙箱、音频响应与用户自定义属性热更新。
+
+- 零运行时依赖，单文件引入（ESM 约 400KB / gzip 约 126KB）
+- 可 npm 安装，也可 <script> CDN 引入；一页可开多个互不干扰的实例
+- 本测试台本身就是库的第一个使用者 —— 你在这里看到的能力都是公共 API
+
+## 能做什么
+
+WebWallGL 是一个「壁纸兼容渲染核心」——凡是需要「动态背景」的地方，都可以塞一个 WebWallGL 实例进去：
+
+- 壁纸软件：桌面壁纸引擎（Tauri / Electron / WebView 壳）的核心渲染器，完整还原 WE 创意工坊场景
+- 网页：个人主页、落地页、产品官网的动态背景或全屏 hero 区块
+- 各类代码工具：仪表盘、监控大屏、终端（如 GUI 启动器/开发工具）的背景层
+- 背景插件：音乐播放器可视化、直播 OBS 背景板、数字标牌、kye/小部件引擎的嵌入渲染源
+
+一句话：万物皆可 Wall。你的应用只负责提供一块 canvas 和场景包的来源，剩下的解析、装配、渲染循环、脚本沙箱、指针与音频，全部交给 WebWallGL。
+
+## 安装
+
+三种引入方式，任选其一：
+
+```
+// 1) npm + 打包器（推荐）
+npm i webwallgl
+import { mount, httpSource } from "webwallgl";
+```
+
+```
+// 2) ESM CDN（vite/webpack 之外的直引方式）
+import { mount, httpSource } from "https://cdn.example.com/webwallgl/1.0.0-beta1/webwallgl.min.mjs";
+```
+
+```
+<!-- 3) UMD <script>：暴露全局 WebWallGL -->
+<script src="https://cdn.example.com/webwallgl/1.0.0-beta1/webwallgl.global.min.js"></script>
+<script>
+  const { mount, httpSource } = WebWallGL;
+</script>
+```
+
+## 快速开始
+
+一个 canvas + 一个资源来源就是全部。mount() 在首帧真正画出来之后 resolve：
+
+```
+<canvas id="wp" style="width:100%;height:400px"></canvas>
+
+import { mount, httpSource } from "webwallgl";
+
+const wp = await mount(document.querySelector("#wp"), {
+  source: httpSource("https://cdn.example.com/wallpapers/3122339805"),
+  fps: 60,
+});
+
+// 首帧之后实例即可用：
+wp.pause();
+wp.resume();
+wp.setProperties({ schemecolor: "0.5 0.2 0.8" });
+console.log("实测帧率", wp.stats.fps);
+```
+
+画布的 CSS 尺寸就是渲染尺寸：库把 backing store 对齐 clientWidth/clientHeight，容器改大小后画面宽高比自动跟随，不需要手动 resize。
+
+## 资源来源 Source
+
+库对网络只发两个请求（scene.pkg 与可选的 project.json），所以资源抽象只有一个接口、三个内置实现：
+
+| 工厂 | 用途 |
+| --- | --- |
+| `httpSource(baseUrl, init?)` | HTTP 基址；自动按 scene.pkg → scenes/scene.pkg → gifscene.pkg 三种真实布局回退 |
+| `fileSource(file, project?)` | &lt;input type=file> 或拖拽进来的 .pkg 本地文件 |
+| `bytesSource(pkg, project?, key?)` | 已经拿到字节（bundle 内嵌、IndexedDB 缓存、自定义通道） |
+
+```
+// 本地文件：拖一个 scene.pkg 进页面即可预览
+input.addEventListener("change", () => {
+  const src = fileSource(input.files[0]);
+  mount(canvas, { source: src });
+});
+```
+
+- httpSource 必须先试根目录 scene.pkg，且每个 fetch 单独容错 —— WKWebView/自定义协议对缺失路径抛 Failed to fetch 而不是 404，顺序错了会「一片壁纸全坏」
+- source.key 参与库内解析缓存：相同 key 的包不会重复解析（暂停/改属性零网络）
+- project 缺失是常态：没有属性表时场景字段用 scene.json 内的快照值
+
+## 挂载选项 MountOptions
+
+| 选项 | 默认 | 说明 |
+| --- | --- | --- |
+| `source（必填）` | `—` | 见上节 Source |
+| `fit` | `"cover"` | cover 等比裁切铺满 / contain 等比留边 / stretch 拉伸 |
+| `renderDpr` | `1` | 渲染 DPR 上限（实际取 min(devicePixelRatio, renderDpr)），调低省显存 |
+| `fps` | `60` | 帧率上限；被上限跳过的帧不计入 stats.fps，掉帧一眼可见 |
+| `volume` | `0` | 0..1。默认静音起步（浏览器自动播放策略）；就绪后再设非零音量 |
+| `autoplay` | `true` | false 时挂载后保持暂停 |
+| `properties` | `{}` | 初始用户属性覆盖值（键为属性名） |
+| `pointer / audio / media` | `内置` | 指针跟随 canvas、音频/系统媒体为确定性模拟；传 null 禁用 |
+| `features` | `全开` | 调试开关：models / text / particles / effects / components |
+| `onReady / onError / onDiagnostic` | `—` | 回调面；也可之后用 instance.on() 订阅 |
+
+## 实例 API SceneInstance
+
+| 成员 | 说明 |
+| --- | --- |
+| `pause() / resume() / paused` | 暂停恢复。禁止整包重挂：恢复时视频/音频从暂停点继续 |
+| `setFit(fit) / setFps(n) / setVolume(v)` | 热更新，无需重挂载（渲染循环每帧读取） |
+| `setRenderDpr(dpr)` | 改 DPR 需重建画布，内部自动重挂（pkg 缓存命中，不重新下载） |
+| `setProperties(props)` | 属性热更新：就地改属性表/效果常量/脚本沙箱，不重新拉包 |
+| `getProperties()` | 当前生效的扁平化属性值表 |
+| `load(source)` | 换场景，复用同一 canvas 与 WebGL 上下文；首帧后 resolve |
+| `release() / restore()` | 释放显存但保留配置（显示器睡眠）/ 用保留的配置重建 |
+| `destroy()` | 终态：释放资源、解绑监听，之后实例不可再用 |
+| `stats / info` | 实测帧率（{fps, running}，停了会归零而不是冻住）/ 场景基本信息（逻辑分辨率、图层数、是否含模型/粒子/文字） |
+| `on(ev, fn)` | 订阅 ready / error / diagnostic，返回取消函数 |
+
+## 事件与诊断
+
+```
+const off = wp.on("diagnostic", (msg, level) => {
+  // level: "info" | "warn" | "error"
+  console[level === "error" ? "error" : "log"]("[wp]", msg);
+});
+wp.on("error", (err) => showError(err));
+wp.on("ready", (info) => {
+  // info: { width, height, layerCount, hasModels, hasParticles, hasText }
+});
+```
+
+库不自带降级页，也不向任何服务器上报：诊断与错误全部经回调交给你，渲染失败的兜底（提示、换壁纸、卸载实例）由调用方决定。
+
+## 一页多实例
+
+```
+const a = await mount(c1, { source: httpSource(urlA) });
+const b = await mount(c2, { source: httpSource(urlB) });
+b.pause(); // 不影响 a
+```
+
+- 每个实例持独立的 Runtime：配置、帧率计、WebGL 上下文、属性表互不可见
+- 指针事件挂在各自的 canvas 上，归一化坐标相对画布，不会截获整页输入
+- 注意 WebGL 上下文数量：浏览器一般允许同页 8~16 个，超出会丢最旧的上下文
+
+## 生命周期与缓存
+
+- 解析后的 scene.pkg 按 source.key 缓存（最多 2 份）：暂停恢复、改属性、setRenderDpr 重挂都不重新下载
+- release() 后 stats.running 变 false、读数归零 —— 停住的读数不该冻在最后一个值上
+- destroy() 之后 canvas 归还给你，库不再碰它；可以再 mount() 一个新实例
+
+## 故障排查
+
+- 黑屏且 onError 报 WEBGL2_UNAVAILABLE：环境没有 WebGL2，库不做软件回退
+- HTTP 404 加载失败：确认 httpSource 指向的目录里真的有 scene.pkg（三种布局会依次尝试，全部失败才报错）
+- Failed to fetch 且无状态码：自定义协议/WKWebView 对缺失路径的行为，属正常容错路径，看最后一条错误即可
+- stats.fps 为 0 但画面在动：读数是「真正提交渲染」的帧，标签页被遮挡时浏览器会暂停 rAF，属预期
+- 有声音但延迟起播：自动播放策略要求用户交互后才允许出声，volume 默认 0 正是为此
+
+## 版权与合规
+
+库代码 MIT。Wallpaper Engine 创意工坊素材（scene.pkg、贴图、音视频）版权归各自作者所有：请仅指向你自己拥有或已获授权的素材，不要把他人作品打包进你的产品或公网分发。
+
+## 赞赏作者
+
+如果这个渲染核心帮到了你的项目，欢迎请作者喝杯咖啡。扫描二维码即可赞赏，金额随意。
+
+| 微信支付 | 支付宝 |
+| --- | --- |
+| ![微信支付赞赏码](imgs/wechat.png) | ![支付宝赞赏码](imgs/alipay.png) |

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "webwallgl",
+  "version": "1.0.0-beta1",
+  "description": "Wallpaper Engine scene wallpaper renderer for the browser (npm / CDN)",
+  "license": "MIT",
+  "author": "oneincase <462534624@qq.com>",
+  "type": "module",
+  "keywords": [
+    "wallpaper-engine",
+    "wallpaper",
+    "webgl",
+    "renderer",
+    "scene",
+    "canvas",
+    "animated-background",
+    "particles",
+    "browser"
+  ],
+  "files": [
+    "webwallgl.mjs",
+    "webwallgl.min.mjs",
+    "webwallgl.global.js",
+    "webwallgl.global.min.js",
+    "*.map",
+    "webwallgl.d.ts",
+    "types.d.ts",
+    "imgs"
+  ],
+  "main": "./webwallgl.global.min.js",
+  "module": "./webwallgl.mjs",
+  "types": "./webwallgl.d.ts",
+  "unpkg": "./webwallgl.global.min.js",
+  "jsdelivr": "./webwallgl.global.min.js",
+  "exports": {
+    ".": {
+      "types": "./webwallgl.d.ts",
+      "import": "./webwallgl.mjs",
+      "default": "./webwallgl.global.min.js"
+    }
+  },
+  "sideEffects": false
+}

package/types.d.ts

@@ -0,0 +1,170 @@
+/** 场景在 canvas 上的适配方式 */
+export type Fit = "cover" | "contain" | "stretch";
+/**
+ * WE 用户属性的取值。project.json 的 general.properties 里只出现这几种标量：
+ * bool → boolean，slider → number，combo/textinput/file/directory → string，
+ * color → "r g b"（0..1 浮点三元组，仍是 string）。
+ */
+export type PropertyValue = boolean | number | string;
+/** 场景资源来源。库对外只发两个请求，所以接口只有两个方法（见 LIBRARY-PLAN §4） */
+export type Source = {
+    /**
+     * 场景容器（scene.pkg）字节。实现方只管给字节，解析由库负责。
+     * 抛错即视为该场景不可用，会走 onError。
+     */
+    scenePkg(signal?: AbortSignal): Promise<ArrayBuffer | Uint8Array>;
+    /**
+     * 属性表（project.json）。可选，且返回 null 合法 —— 真实壁纸库里大量场景
+     * 没有 project.json，此时场景字段一律用 scene.json 内的快照值。
+     */
+    project?(signal?: AbortSignal): Promise<unknown | null>;
+    /**
+     * 缓存键。相同键的 scene.pkg 命中库内缓存，避免重复解析上百 MB 的包
+     * （暂停恢复、改属性都不该重新走一遍解析）。省略则不参与缓存。
+     */
+    readonly key?: string;
+};
+/**
+ * 指针状态提供者。默认实现监听传入 canvas 自身的 pointer 事件；
+ * 传 null 则禁用指针交互（壁纸脚本读到的指针恒为静止居中）。
+ */
+export type PointerSource = {
+    /** 归一化坐标 0..1，相对 canvas 左上角；y 向下 */
+    readonly x: number;
+    readonly y: number;
+    readonly leftDown: boolean;
+    readonly rightDown: boolean;
+    /** 指针是否在 canvas 内 */
+    readonly inside: boolean;
+};
+/**
+ * 音频频谱提供者（音频响应壁纸用）。返回当前快照，不推进状态 ——
+ * 推进由库的渲染循环按场景时间驱动，保证同一时刻取到同一份数据。
+ * 默认是内置的确定性模拟源（无需麦克风权限，离线可复现）。
+ */
+export type AudioSource = {
+    /** 左右声道各 64 段频谱，值域 0..1 */
+    snapshot(): {
+        left: Float32Array | number[];
+        right: Float32Array | number[];
+    };
+};
+/**
+ * 系统媒体信息提供者（"正在播放"类壁纸用）。默认是内置模拟源。
+ * 接真实数据时替换本接口即可，字段名与 WE 的 media* 回调一致。
+ */
+export type MediaSource = {
+    snapshot(): {
+        playing: boolean;
+        title?: string;
+        artist?: string;
+        album?: string;
+        /** 0..1 播放进度 */
+        position?: number;
+        durationSeconds?: number;
+    };
+};
+/** 渲染开关。调试用，默认全开；对应旧 types.ts 的 SKIP_* 常量取反 */
+export type FeatureFlags = {
+    /** puppet 骨骼网格（人物模型） */
+    models: boolean;
+    /** 文字对象（时钟/日期等挂件） */
+    text: boolean;
+    /** 粒子（雪/雨/火花/雾/光轴） */
+    particles: boolean;
+    /** 图层效果链 */
+    effects: boolean;
+    /** WE 内置组件对象（本机库 0 个，真出现时按开关处理） */
+    components: boolean;
+};
+/** 场景装配完成后的基本信息 */
+export type SceneInfo = {
+    /** 场景逻辑分辨率（scene.json 的 general.orthogonalprojection） */
+    width: number;
+    height: number;
+    /** 图层数（已按 features 过滤后） */
+    layerCount: number;
+    /** 是否含 3D 模型 / 粒子 / 文字（便于调用方决定要不要降画质） */
+    hasModels: boolean;
+    hasParticles: boolean;
+    hasText: boolean;
+};
+/** 诊断级别。库内部所有 reportDiag 都归到这三档 */
+export type DiagnosticLevel = "info" | "warn" | "error";
+export type SceneEvents = {
+    ready: (info: SceneInfo) => void;
+    error: (err: Error) => void;
+    diagnostic: (msg: string, level: DiagnosticLevel) => void;
+};
+export type MountOptions = {
+    /** 资源来源（必填） */
+    source: Source;
+    /** 适配模式。默认 "cover" */
+    fit?: Fit;
+    /**
+     * 渲染分辨率上限（有效 devicePixelRatio 封顶），越低越省显存。默认 1。
+     * 实际使用 min(devicePixelRatio, renderDpr)。
+     */
+    renderDpr?: number;
+    /** 帧率上限。默认 60。渲染循环跳过比目标更快的帧，降低 GPU 占用 */
+    fps?: number;
+    /**
+     * 音量 0..1。默认 0（静音起步）—— 浏览器自动播放策略要求先有用户交互，
+     * 非静音起步会让整个场景的音频节点被挂起。
+     */
+    volume?: number;
+    /** 是否自动开始渲染循环。默认 true */
+    autoplay?: boolean;
+    /** 用户属性覆盖值（键为 project.json 里的属性名） */
+    properties?: Record<string, PropertyValue>;
+    /** 指针源。默认跟随 canvas 自身 pointer 事件；null = 禁用 */
+    pointer?: PointerSource | null;
+    /** 音频源。默认内置确定性模拟；null = 禁用（频谱恒为 0） */
+    audio?: AudioSource | null;
+    /** 系统媒体源。默认内置模拟；null = 禁用 */
+    media?: MediaSource | null;
+    /** 渲染开关（调试用） */
+    features?: Partial<FeatureFlags>;
+    /** 诊断回调。替代旧的 GET /diag 上报 */
+    onDiagnostic?: SceneEvents["diagnostic"];
+    /** 装配或渲染失败。库不自带降级页，由调用方决定怎么兜 */
+    onError?: SceneEvents["error"];
+    /** 首帧渲染完成 */
+    onReady?: SceneEvents["ready"];
+};
+/** 帧率观测。running=false 表示已暂停或没在出帧（读数会归零而不是冻住） */
+export type FrameStats = {
+    fps: number;
+    running: boolean;
+};
+export type SceneInstance = {
+    /** 挂载目标（构造时传入的那个 canvas） */
+    readonly canvas: HTMLCanvasElement;
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+    setFit(fit: Fit): void;
+    setFps(fps: number): void;
+    setVolume(volume: number): void;
+    /** 改 DPR 需重建画布尺寸，内部自动重挂当前场景 */
+    setRenderDpr(dpr: number): void;
+    /**
+     * 用户属性热更新。就地改属性表 / 效果常量 / 脚本沙箱，
+     * **不重新拉取与解析 scene.pkg**（百 MB 包重挂是可感知的卡顿）。
+     */
+    setProperties(props: Record<string, PropertyValue>): void;
+    /** 当前生效的属性值（扁平化后的 name → value） */
+    getProperties(): Record<string, PropertyValue>;
+    /** 换场景，复用同一 canvas 与 WebGL 上下文 */
+    load(source: Source): Promise<void>;
+    /** 释放 GL/视频/音频资源，保留配置（显示器睡眠等场景） */
+    release(): void;
+    /** 用保留的配置重建 */
+    restore(): void;
+    /** 彻底销毁：解绑事件监听、释放全部资源，之后不可再用 */
+    destroy(): void;
+    readonly stats: FrameStats;
+    readonly info: SceneInfo | null;
+    /** 事件订阅，返回取消函数 */
+    on<K extends keyof SceneEvents>(ev: K, fn: SceneEvents[K]): () => void;
+};

package/webwallgl.d.ts

@@ -0,0 +1,42 @@
+// WebWallGL 公共类型入口（随 dist 发布为 dist/lib/webwallgl.d.ts）。
+//
+// ⚠️ 维护约束：函数签名是**手写的契约面**，全部类型来自 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,
+} from "./types";
+
+export declare function mount(
+  canvas: HTMLCanvasElement,
+  options: MountOptions,
+): Promise<SceneInstance>;
+
+export declare function createScene(
+  canvas: HTMLCanvasElement,
+  options?: Partial<Omit<MountOptions, "source">>,
+): SceneInstance;
+
+export declare function httpSource(baseUrl: string, init?: RequestInit): Source;
+
+export declare function fileSource(file: File | Blob, project?: unknown): Source;
+
+export declare function bytesSource(
+  pkg: ArrayBuffer | Uint8Array,
+  project?: unknown,
+  key?: string,
+): Source;