webwallgl 1.0.0 → 1.1.0

package/README.en.md

@@ -4,7 +4,7 @@
 
 ## Introduction
 
-WebWallGL is a browser-side renderer for Wallpaper Engine wallpapers — "scene" today, with video and web support coming in later releases: its main job is replaying workshop scene packages (scene.pkg) in WebGL in real time, with layer effect chains, particles, 3D puppet bones, text widgets, script sandboxes, audio response and live user-property updates. Upcoming versions will add effects exclusive to this library — stay tuned.
+WebWallGL is a browser-side renderer for Wallpaper Engine wallpapers — scene, video, and web: its main job is replaying workshop scene packages (scene.pkg) in WebGL in real time, with layer effect chains, particles, 3D puppet bones, text widgets, script sandboxes, audio response and live user-property updates; web wallpapers run in a sandboxed iframe with a WE API shim injected before author scripts. Upcoming versions will add effects exclusive to this library — stay tuned.
 
 - [GitHub repository](https://github.com/oneincase/webwallgl)
 - [Live demo (GitHub Pages)](https://oneincase.github.io/webwallgl/)
@@ -36,12 +36,12 @@ import { mount, httpSource } from "webwallgl";
 
 ```
 // 2) ESM CDN via jsDelivr (without a bundler)
-import { mount, httpSource } from "https://cdn.jsdelivr.net/npm/webwallgl@1.0.0/webwallgl.min.mjs";
+import { mount, httpSource } from "https://cdn.jsdelivr.net/npm/webwallgl@1.1.0/webwallgl.min.mjs";
 ```
 
 ```
 <!-- 3) UMD <script>: exposes the global WebWallGL -->
-<script src="https://cdn.jsdelivr.net/npm/webwallgl@1.0.0/webwallgl.global.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/webwallgl@1.1.0/webwallgl.global.min.js"></script>
 <script>
   const { mount, httpSource } = WebWallGL;
 </script>
@@ -70,6 +70,31 @@ 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.
 
+## Mount target: canvas or container div
+
+mount() takes any HTMLElement as its first argument, not just a canvas. Pass a canvas and it is used directly; pass a plain container (a div, say) and the library creates a full-bleed canvas inside it (tagged data-webwallgl, reused on remount; a position:static container is switched to relative).
+
+This is not a style choice — **web wallpapers require a container**. A web wallpaper does not use WebGL; the library appendChild()s a sandboxed iframe into the element you pass, and a canvas cannot have children, so passing one fails. If the same code path must handle both scene and web wallpapers (a general wallpaper player, say), always pass a div:
+
+```
+<!-- Works for both wallpaper types -->
+<div id="wp" style="position:relative;width:100%;height:400px"></div>
+
+// Scene wallpaper: the library builds a canvas inside the div
+// Web wallpaper:   the library mounts a sandboxed iframe inside the div
+const wp = await mount(document.querySelector("#wp"), {
+  source: httpSource("https://cdn.example.com/wallpapers/2517518192"),
+});
+
+// wp.canvas is always readable: the real canvas on the scene path,
+// the container you passed on the web path
+console.log(wp.canvas);
+```
+
+- You never branch on type yourself: mount() reads project.json first — type "web" takes the web path, everything else goes through scene assembly
+- The web entry URL resolves as Source.webEntry() → {httpSource base}/{project.file or index.html}; if neither yields a URL, mount throws
+- On the web path the WebGL-side options (fit / renderDpr / features) do not apply; pause/resume, setVolume and setProperties still work, relayed to author code through the shim
+
 ## 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:
@@ -122,6 +147,32 @@ input.addEventListener("change", () => {
 | `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 |
 
+## User properties
+
+User properties are the settings a wallpaper author exposes in WE (colors, toggles, sliders, dropdowns), declared under general.properties in project.json. Keys are the author's property names (typically things like schemecolor or newproperty12); values must be scalars matching the property type:
+
+| Property type | What to pass | Example |
+| --- | --- | --- |
+| `color` | A "r g b" string: three 0..1 floats separated by spaces (not #RRGGBB, not 0..255) | `"0.5 0.2 0.8"` |
+| `bool` | A boolean | `true` |
+| `slider` | A number within the author's min/max | `100` |
+| `combo` | The option value; pass a number when options are integers (integer strings also work) | `1` |
+| `textinput / file / directory` | A string | `"https://…/clock.png"` |
+
+```
+// First see which properties this wallpaper has and their current values
+console.log(wp.getProperties());
+// → { schemecolor: "0 0 0", newproperty12: true, … }
+
+// Then set them by name (pass only what you change; the rest stays put)
+wp.setProperties({ schemecolor: "0.5 0.2 0.8", newproperty12: false });
+```
+
+- Property names differ per wallpaper; there is no cross-wallpaper naming convention — read getProperties() first instead of hardcoding guesses
+- Writing a name the current scene doesn't declare raises no error: the value still lands in the table (a later scene may use it) but changes nothing on screen — a typo shows up as "nothing happened", not as an exception
+- setProperties() patches in place — property table, effect constants and script sandboxes — with no re-fetch and no re-parse
+- Wallpapers without a project.json still run: the property table is empty and fields fall back to the scene.json snapshot values
+
 ## Events & diagnostics
 
 ```
@@ -154,6 +205,8 @@ b.pause(); // does not affect a
 - 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
+- load() puts the instance back into the playing state (even if it was paused before); call pause() again after load() to stay paused
+- load() re-applies the properties given at mount time; values set later via setProperties() do not carry over — property names are per-scene anyway, so re-apply them after load() if you need them
 
 ## Troubleshooting
 
@@ -162,6 +215,28 @@ b.pause(); // does not affect a
 - 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
+- Web wallpaper has no audio/properties: the entry HTML must be same-origin or CORS-readable so the library can inject the WE shim; unreadable cross-origin falls back to a bare iframe (no official APIs)
+- Web wallpaper relative assets 404: resources rely on &lt;base href> pointing at the original directory; wallpapers that build URLs from location.href may break under blob loading
+
+## Changelog
+
+Current version: 1.1.0. This section records only user-visible changes (API, behavior, compatibility, fidelity), each backed by a commit in the repository; pure internal refactors and verifier scripts are omitted.
+
+| Version | Date | Notes |
+| --- | --- | --- |
+| `1.0.0` | 2026-09-06 | First stable release: the public API is settled (mount / SceneInstance / Source) |
+| `1.0.0-beta1` | 2026-09-04 | First public preview |
+
+After 1.0.0 (unreleased, already on the repository's main branch) — these will ship in the next version:
+
+- New external pointer injection channel (__wp.pushPointer / pointerLeave): when the wallpaper window cannot receive the mouse (e.g. the Finder desktop window swallows events on macOS), the host polls the system cursor and pushes it in. Scene and web wallpapers share one protocol — callers need not branch on type
+- Web wallpapers joined the same channel: the shim synthesizes DOM events against the hit element (full over/out/enter/leave chains, click derived from button edges). Of 49 local web wallpapers, interaction went from dead to working on 24 with mousemove, 29 with click and 16 with pointer events. Hard limit: CSS :hover is driven by browser hit-testing and cannot be lit by synthetic events
+- Effect-pass compile failures driven to near zero (seven rounds): the transpiler now handles int/float mixing, macro scoping, vector narrowing, scientific notation and more. Library-wide effect-pass compilation went from 1653/1873 (88.3%) to 1823/1873 (97.3%), +170 in total. The symptom was an effect silently missing — a failed compile only warns, so god rays / visualizers / glows simply vanished
+- Pause semantics completed: pausing must freeze rAF/timers and CSS animations together (compositor-driven CSS animations ignore JS freezing — 1444432396 kept animating after pause); resuming must re-arm held rAF callbacks (self-recursive rAF wallpapers break their chain permanently — 1278092907 froze forever after resume), restoring only what we paused
+- Fidelity fixes: keyframe animations now run on the real clock (previously they accumulated the target frame interval, diverging from the bone clock by 5.5s over 30s — hair desynced from the head and the scalp showed through); object scripts and keyframe animations now work in local space with per-frame parent/child recomposition (previously local return values were written straight into world slots, so elements drifted away untouched and got clipped); hidden mask layers referenced by clipping_mask now correctly read back what is behind them (previously they fell back to the referencing layer itself, painting a solid white block)
+- Two new documentation sections, "Mount target" and "User properties": web wallpapers require a container div rather than a canvas, and what value shape each property type expects
+
+The full commit history lives in the GitHub repository; every fix records its symptom, root cause, measured scope and verification method in the commit message.
 
 ## Copyright & compliance
 

package/README.md

@@ -4,7 +4,7 @@
 
 ## 简介
 
-WebWallGL 是一个浏览器端的 Wallpaper Engine「scene」场景、视频、web（后续版本支持）壁纸渲染库：主要功能是把创意工坊场景包（scene.pkg）在 WebGL 里实时还原，支持图层效果链、粒子、3D 木偶骨骼、文字挂件、脚本沙箱、音频响应与用户自定义属性热更新。后续版本将加入本库独有效果支持，请敬请期待。
+WebWallGL 是一个浏览器端的 Wallpaper Engine「scene」场景、视频、web 网页壁纸渲染库：主要功能是把创意工坊场景包（scene.pkg）在 WebGL 里实时还原，支持图层效果链、粒子、3D 木偶骨骼、文字挂件、脚本沙箱、音频响应与用户自定义属性热更新；网页类型壁纸经 sandbox iframe + 加载前 WE shim 注入运行。后续版本将加入本库独有效果支持，请敬请期待。
 
 - [GitHub 开源仓库](https://github.com/oneincase/webwallgl)
 - [在线版（GitHub Pages）](https://oneincase.github.io/webwallgl/)
@@ -36,12 +36,12 @@ import { mount, httpSource } from "webwallgl";
 
 ```
 // 2) ESM CDN（jsDelivr，vite/webpack 之外的直引方式）
-import { mount, httpSource } from "https://cdn.jsdelivr.net/npm/webwallgl@1.0.0/webwallgl.min.mjs";
+import { mount, httpSource } from "https://cdn.jsdelivr.net/npm/webwallgl@1.1.0/webwallgl.min.mjs";
 ```
 
 ```
 <!-- 3) UMD <script>：暴露全局 WebWallGL -->
-<script src="https://cdn.jsdelivr.net/npm/webwallgl@1.0.0/webwallgl.global.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/webwallgl@1.1.0/webwallgl.global.min.js"></script>
 <script>
   const { mount, httpSource } = WebWallGL;
 </script>
@@ -70,6 +70,30 @@ console.log("实测帧率", wp.stats.fps);
 
 画布的 CSS 尺寸就是渲染尺寸：库把 backing store 对齐 clientWidth/clientHeight，容器改大小后画面宽高比自动跟随，不需要手动 resize。
 
+## 挂载目标：canvas 还是容器 div
+
+mount() 的第一个参数收任意 HTMLElement，不限于 canvas。传 canvas 就直接用它；传普通容器（div 等）则库在其内部自建一块铺满的 canvas（带 data-webwallgl 标记，重复挂载会复用同一块，容器若是 position:static 会被改成 relative）。
+
+选哪个不是风格问题——**网页类型壁纸必须传容器**。网页壁纸不走 WebGL，库会把 sandbox iframe 直接 appendChild 进你传的元素；canvas 不能有子元素，传 canvas 会挂不上。如果同一段代码要同时应付场景壁纸和网页壁纸（例如一个通用壁纸播放器），一律传 div 最稳妥：
+
+```
+<!-- 通用写法：两类壁纸都能挂 -->
+<div id="wp" style="position:relative;width:100%;height:400px"></div>
+
+// 场景壁纸：库在 div 内自建 canvas
+// 网页壁纸：库在 div 内挂 sandbox iframe
+const wp = await mount(document.querySelector("#wp"), {
+  source: httpSource("https://cdn.example.com/wallpapers/2517518192"),
+});
+
+// wp.canvas 始终可读：场景路径是那块真 canvas，网页路径是你传入的容器
+console.log(wp.canvas);
+```
+
+- 类型不用你判断：mount() 先取 project.json，type 为 "web" 走网页路径，其余一律走场景装配
+- 网页入口 URL 的解析顺序是 Source.webEntry() → {httpSource 基址}/{project.file 或 index.html}；两者都给不出就抛错
+- 网页路径下 fit / renderDpr / features 这些 WebGL 侧选项自然不适用；pause/resume、setVolume、setProperties 仍然有效（经 shim 转达给作者代码）
+
 ## 资源来源 Source
 
 库对网络只发两个请求（scene.pkg 与可选的 project.json），所以资源抽象只有一个接口、三个内置实现：
@@ -122,6 +146,32 @@ input.addEventListener("change", () => {
 | `stats / info` | 实测帧率（{fps, running}，停了会归零而不是冻住）/ 场景基本信息（逻辑分辨率、图层数、是否含模型/粒子/文字） |
 | `on(ev, fn)` | 订阅 ready / error / diagnostic，返回取消函数 |
 
+## 用户属性 properties
+
+用户属性就是 WE 里作者暴露给观众的那些设置项（颜色、开关、滑条、下拉），定义在 project.json 的 general.properties。键是属性名（作者自定的，常见形态是 schemecolor、newproperty12 这类），值必须按属性类型给对应的标量：
+
+| 属性类型 | 传什么 | 示例 |
+| --- | --- | --- |
+| `color` | 字符串 "r g b"，三个 0..1 浮点用空格分隔（不是 #RRGGBB，也不是 0..255） | `"0.5 0.2 0.8"` |
+| `bool` | 布尔 | `true` |
+| `slider` | 数字，落在作者定义的 min/max 内 | `100` |
+| `combo` | 选项值；选项为整数时给 number（整数字符串也认） | `1` |
+| `textinput / file / directory` | 字符串 | `"https://…/clock.png"` |
+
+```
+// 先看这张壁纸有哪些属性、当前值是什么
+console.log(wp.getProperties());
+// → { schemecolor: "0 0 0", newproperty12: true, … }
+
+// 再按名字改（只传要改的，其余保持不动）
+wp.setProperties({ schemecolor: "0.5 0.2 0.8", newproperty12: false });
+```
+
+- 属性名逐壁纸不同，没有跨壁纸通用的名字——先 getProperties() 读一遍再改，不要硬编码猜名字
+- 写一个当前场景没有的名字不会报错：值会照样进属性表（换场景后可能被用上），但对当前画面无任何影响——拼错名字的症状是「调了没反应」而不是异常
+- setProperties() 是就地热更新：改属性表、效果常量与脚本沙箱，不重新拉包也不重新解析
+- 没有 project.json 的壁纸也能跑：此时属性表为空，场景字段一律用 scene.json 里的快照值
+
 ## 事件与诊断
 
 ```
@@ -154,6 +204,8 @@ b.pause(); // 不影响 a
 - 解析后的 scene.pkg 按 source.key 缓存（最多 2 份）：暂停恢复、改属性、setRenderDpr 重挂都不重新下载
 - release() 后 stats.running 变 false、读数归零 —— 停住的读数不该冻在最后一个值上
 - destroy() 之后 canvas 归还给你，库不再碰它；可以再 mount() 一个新实例
+- load() 换场景会把实例恢复成播放态（即使换之前是暂停的），要保持暂停就在 load() 之后再 pause() 一次
+- load() 会重新套用挂载时传入的 properties，此前用 setProperties() 改的值不会延续到新场景——属性名本就是逐场景定义的，要沿用得自己在 load() 之后再设一次
 
 ## 故障排查
 
@@ -162,6 +214,28 @@ b.pause(); // 不影响 a
 - Failed to fetch 且无状态码：自定义协议/WKWebView 对缺失路径的行为，属正常容错路径，看最后一条错误即可
 - stats.fps 为 0 但画面在动：读数是「真正提交渲染」的帧，标签页被遮挡时浏览器会暂停 rAF，属预期
 - 有声音但延迟起播：自动播放策略要求用户交互后才允许出声，volume 默认 0 正是为此
+- 网页壁纸无音频/属性：入口 HTML 必须同源或 CORS 可读，库才能改写注入 WE shim；跨域不可读时会退回裸 iframe（无官方 API）
+- 网页壁纸相对资源 404：依赖 &lt;base href> 指回原站点目录；依赖 location.href 拼路径的壁纸在 blob 加载下可能异常
+
+## 版本更新说明
+
+当前版本 1.1.0。本节只记对使用者可见的变化（API、行为、兼容性、还原度），逐条对应仓库里的提交；纯内部重构与判据脚本不列。
+
+| 版本 | 日期 | 说明 |
+| --- | --- | --- |
+| `1.0.0` | 2026-09-06 | 首个正式版：公共 API 定稿（mount / SceneInstance / Source 三件套） |
+| `1.0.0-beta1` | 2026-09-04 | 首个公开测试版 |
+
+1.0.0 之后（未发版，已在仓库主线）—— 下个版本会包含这些：
+
+- 新增外部指针注入通道 __wp.pushPointer / pointerLeave：桌面壁纸窗口收不到鼠标时（如 macOS 下 Finder 桌面窗口吃掉事件），由宿主轮询系统鼠标后推进来。场景与网页两类壁纸共用同一套协议，调用方不必判断类型
+- 网页壁纸接入同一条注入通道：shim 按命中元素合成 DOM 事件（over/out/enter/leave 链完整、click 靠按键边缘合成）。本机库 49 张网页壁纸里 mousemove 24 / click 29 / pointer* 16 张的交互从「完全无反应」变为可用。硬限制：CSS :hover 由浏览器 hit-test 驱动，合成事件点不亮
+- 效果 pass 编译失败清零（七批）：转译器修掉整浮混用、宏作用域、向量收窄、科学计数法等形态。全库效果 pass 编译通过率 1653/1873 (88.3%) → 1823/1873 (97.3%)，累计 +170。症状是「某个效果静默不出现」——编译失败只 warn 不报错，画面上表现为体积光/音谱/光晕整个缺失
+- 暂停语义补全：暂停必须同时冻结 rAF/定时器与 CSS 动画（合成器驱动的 CSS 动画不受 JS 冻结影响，1444432396 表现为「点了暂停画面照旧」）；恢复必须重挂 rAF 挂起项（rAF 自递归的壁纸暂停一次就永久断链，1278092907 表现为「恢复后永久定格」），且只还原我们代为暂停的部分
+- 还原度修复若干：关键帧动画改用真实时钟（此前按目标帧间隔累加，与骨骼两套时基必然发散，30 秒漂 5.5 秒，表现为头发与头不同步、头顶漏模）；对象脚本与关键帧动画的坐标空间改为 local 并每帧重算父子变换（此前把脚本返回的 local 值直接写进 world 槽，表现为元素无人操作就自行滑走、被边缘裁切）；clipping_mask 引用的隐藏遮罩层现在能正确回读身后画面（此前回退成引用方自身，表现为一块纯白板）
+- 使用说明新增「挂载目标」与「用户属性」两节：网页壁纸必须传容器 div 而非 canvas，以及各类属性该传什么形态的值
+
+完整提交历史见 GitHub 仓库；每条修复在提交信息里都写明了症状、根因、影响面数字与验证方式。
 
 ## 版权与合规
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webwallgl",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Wallpaper Engine scene wallpaper renderer for the browser (npm / CDN)",
   "license": "MIT",
   "author": "oneincase <462534624@qq.com>",

package/types.d.ts

@@ -11,6 +11,7 @@ export type Source = {
     /**
      * 场景容器（scene.pkg）字节。实现方只管给字节，解析由库负责。
      * 抛错即视为该场景不可用，会走 onError。
+     * 网页壁纸（project.type=web）不会调用本方法。
      */
     scenePkg(signal?: AbortSignal): Promise<ArrayBuffer | Uint8Array>;
     /**
@@ -18,6 +19,13 @@ export type Source = {
      * 没有 project.json，此时场景字段一律用 scene.json 内的快照值。
      */
     project?(signal?: AbortSignal): Promise<unknown | null>;
+    /**
+     * 网页壁纸入口 URL（index.html 等）。`project.type` 为 web 时由 mount 调用；
+     * 省略则回退到 `{httpSource 基址}/{project.file || "index.html"}`。
+     */
+    webEntry?(signal?: AbortSignal): Promise<{
+        url: string;
+    } | null>;
     /**
      * 缓存键。相同键的 scene.pkg 命中库内缓存，避免重复解析上百 MB 的包
      * （暂停恢复、改属性都不该重新走一遍解析）。省略则不参与缓存。
@@ -138,7 +146,7 @@ export type FrameStats = {
     running: boolean;
 };
 export type SceneInstance = {
-    /** 挂载目标（构造时传入的那个 canvas） */
+    /** 挂载目标（构造时传入；场景路径可能是内部自建的 canvas） */
     readonly canvas: HTMLCanvasElement;
     pause(): void;
     resume(): void;

package/webwallgl.d.ts

@@ -22,12 +22,12 @@ export {
 } from "./types";
 
 export declare function mount(
-  canvas: HTMLCanvasElement,
+  el: HTMLElement,
   options: MountOptions,
 ): Promise<SceneInstance>;
 
 export declare function createScene(
-  canvas: HTMLCanvasElement,
+  el: HTMLElement,
   options?: Partial<Omit<MountOptions, "source">>,
 ): SceneInstance;