pixel-daylight-switch-gsvegetable 3.0.0 → 3.1.1

package/docs/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog\n\n## [3.1.1] — Standalone refractive glass engine\n\n- Extract the refractive lens into a separately mountable WebGL2 overlay with no fixed aspect ratio or switch dependency.\n- Expose configurable geometry, refraction, dispersion, bezel, shine, opacity and lifecycle methods.\n- Accept origin-clean canvas, image, video and bitmap sources; document browser security boundaries for DOM backgrounds.\n- Add a dedicated glass-engine demo, integration guide, TypeScript API and smoke checks.\n- Keep the existing day/night switch renderer and all five scenes unchanged.\n\n [3.0.1] — Layered community scenes
+
+- Add Manifest v2 with reusable pixel-matrix assets and ordered scene layers.
+- Add bounded, deterministic drift and bob motion tracks without executing third-party code.
+- Preserve the original Manifest v1 schema and registration behavior.
+- Add a Floating Island example, v2 JSON Schema, TypeScript declarations and validation tests.
+
+
+## [3.0.0] — Community scene plugins
+
+- Add a validated, data-only Scene Manifest v1 and public scene registry API.
+- Render registered pixel-matrix scenes through the existing refractive glass renderer with interpolated 24-hour palettes.
+- Expose scene registration from CommonJS and ESM package entry points.
+- Add CDN registry loading, a Sakura Evening example, JSON Schema, documentation and automated tests.
+- Preserve all five built-in scene implementations and their dedicated live animation systems.
+
+
+All notable changes to Pixel Daylight Switch are documented here.
+
+## [Unreleased] — Developer integration
+
+- Make the one-line embed responsive and prevent demo-page global CSS from leaking into host websites.
+- Generate responsive, copy-ready integration snippets from the Playground.
+- Add React and Vue 3 lifecycle integration recipes.
+- Refresh `llms.txt` and add smoke/browser regression coverage for embed isolation.
+
+
+## [2.2.0] — Mobile scene controls
+
+### Mobile app experience
+- Add a dedicated mobile app shell with five selectable scenes: countryside, Japanese street, apartment, seaside and mountain cabin.
+- Add an optional snowfall control.
+- Add live day/night status, device-language UI (English, Simplified Chinese and Japanese), accessible pressed states and compact portrait/landscape layouts.
+- Reuse the shared renderer and preserve the glass shader, refraction, highlights, dispersion and drag interaction.
+
+### Documentation and verification
+- Update English, Simplified Chinese and Japanese README files with the mobile controls.
+- Extend mobile smoke checks for all five scene choices, weather control and renderer remount behavior.
+
+## [2.1.0] — Android visual and versioning fix
+
+### Android app
+- Replace the warm yellow-beige native page background with a neutral cool gray.
+- Match the Capacitor native window background and mobile theme color to the page background.
+- Set Android versionName and versionCode from the package version so new APKs no longer appear as version 1.0.
+
+### Build reliability
+- Apply package-driven Android version metadata after each generated Capacitor project.
+- Keep the shared WebGL renderer and scene implementation unchanged.
+
+## [2.0.0] — Released
+
+### Android 与 iOS
+- 引入 Capacitor 8 原生应用构建路径，支持 Android 与 iOS 共用现有 Web 渲染器。
+- 新增独立移动端入口与全屏布局，处理 viewport、安全区域、横竖屏和触控拖动。
+- 新增移动资源准备脚本与 smoke test，确保原生包使用与 Web 完全相同的 `app.js`。
+- 新增 Android Debug APK 与 iOS Simulator 自动构建工作流。
+
+### 架构与兼容性
+- Web 继续保持独立运行；不重写、不复制 WebGL shader、场景数据或交互物理逻辑。
+- 原生 Android / iOS 工程按需由 Capacitor 生成，不把 IDE 派生文件提交到仓库。
+- 本版本不包含已签名商店包；正式发布仍需开发者签名与商店配置。
+
+## [1.3.1]
+
+### 稳定性与生命周期
+- 修复组件卸载时主动销毁 WebGL context，导致同一 canvas/root 后续重新挂载可能异常的问题。
+- 保留 GPU 资源释放与事件监听器、观察器清理，同时允许 canvas 在卸载后重新挂载。
+
+### 自动化验证
+- 增加 CommonJS、ESM 与 SSR 导入检查。
+- 增加 Node.js 18、20、22 的 CI 兼容性检查。
+- 增加 Chromium 浏览器回归：自动挂载、重复挂载/卸载、多实例、指针交互、事件监听器清理。
+- 增加移动端触控、Playground 小屏布局与参数应用检查。
+- 将浏览器回归纳入 npm 发布前置检查。
+
+## [1.3.0]
+
+<details>
+<summary>查看 v1.3.0 详细更新</summary>
+
+### 场景与世界
+- 新增日本街道：店铺、暖帘、路灯、自动售货机、自行车与道路细节。
+- 新增现代公寓：城市窗景、沙发、茶几、落地灯、室内植物与地毯。
+- 新增海边：海面、沙滩、灯塔、帆船与海岸植被。
+- 新增山间木屋：层叠山脉、针叶林、雪顶、木屋与烟囱。
+- 保留乡村小屋作为默认场景。
+- 新增 `data-scene` 场景属性，并在 Playground 中加入场景选择。
+
+### Playground 与参数组织
+- 参数按用途拆分：滑动响应速度、惯性与回弹归入运动反馈；折射、边缘厚度、色散与高光归入玻璃光学；时间倍率单独归入世界节奏；场景、天气和初始昼夜归入场景环境。
+
+### 兼容性
+- 默认仍为 `countryside`，既有接入方式不需要修改。
+- 场景切换不改变开关物理、玻璃 shader 与昼夜时间逻辑。
+
+</details>
+
+## [1.2.0]
+
+<details>
+<summary>查看 v1.2.0 详细更新</summary>
+
+### 参数与世界
+- 新增 `data-friction`、`data-bounce`，分别调节惯性阻尼与边缘回弹。
+- 新增 `data-dispersion`、`data-shine`，调节玻璃边缘色散与表面高光。
+- 新增 `data-time-speed` 时间倍率，以及 `data-weather="snow"` 飘雪天气。
+
+### Playground
+- 新增独立参数实验室，支持分组调节、预设和 HTML 代码复制。
+- 重构实验室视觉，采用更克制的编辑式布局。
+- 通过独立预览与双缓冲切换，减少快速调参时的 WebGL 重建与白屏。
+
+### 文档
+- README 改为中文优先，并整理参数说明与英文文档。
+
+### 兼容性
+- 新增参数均为可选项；未设置时保留原有默认行为。
+
+</details>
+
+## [1.1.0]
+- 新增动画速度、镜片折射、外框厚度和初始夜晚状态的 HTML 参数配置。
+
+## [1.0.0]
+- 首个公开版本。
+

package/docs/GLASS_ENGINE.md

@@ -0,0 +1,65 @@
+# Standalone Glass Engine
+
+PixelGlassEngine extracts the project's refractive lens into a reusable WebGL2 overlay. It is independent of the day/night switch: it does not create a switch, impose an aspect ratio, or set a fixed component size.
+
+## Browser
+
+Load `glass-engine.js`, then pass a source that the browser can upload to WebGL:
+
+```html
+<div id="card" style="position:relative;width:100%;height:260px;overflow:hidden">
+  <canvas id="background" width="1200" height="520"></canvas>
+</div>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/glass-engine.js"></script>
+<script>
+  const card = document.querySelector('#card');
+  const background = document.querySelector('#background');
+  const glass = PixelGlassEngine.createGlass(card, {
+    source: background,
+    width: '72%',
+    height: '68%',
+    left: '14%',
+    top: '16%',
+    radius: 32,
+    refraction: 1.24,
+    dispersion: 0.05,
+    bezel: 0.046,
+    shine: 0.44
+  });
+  // Later: glass.setOptions({ refraction: 1.32 });
+  // Before removing the card: glass.destroy();
+</script>
+```
+
+## npm
+
+```js
+import { createGlass } from 'pixel-daylight-switch-gsvegetable/glass-engine';
+
+const glass = createGlass(container, { source: backgroundCanvas, width: '70%', height: 160, radius: 28 });
+glass.setOptions({ dispersion: 0.08 });
+glass.setSource(nextCanvasOrImage);
+glass.destroy();
+```
+
+## Source contract and browser security
+
+The source may be an HTMLCanvasElement, OffscreenCanvas, HTMLImageElement, HTMLVideoElement, ImageBitmap, or a function returning one of those objects. The source must be ready and origin-clean. Cross-origin images require appropriate CORS headers and `crossOrigin = "anonymous"` before assigning `src`.
+
+A browser does not expose arbitrary DOM pixels as a WebGL texture. Therefore this engine does not claim to refract any arbitrary page behind an overlay automatically. For a live webpage, provide a canvas snapshot/render target from the host application (for example, the same canvas used by a chart, game, or custom renderer). A DOM-to-canvas adapter is application-specific and may be blocked by cross-origin content, video, fonts, or browser security.
+
+## Options
+
+- `source`: canvas/image/video/bitmap or a callback returning one.
+- `width`, `height`, `left`, `top`: numbers in CSS pixels or CSS length strings; no fixed aspect ratio.
+- `radius`: number in CSS pixels or CSS length string.
+- `refraction`: magnification factor; default `1.24`.
+- `dispersion`: RGB edge separation, clamped to `0–0.25`.
+- `bezel`: relative edge thickness, clamped to `0–0.3`.
+- `shine`: highlight intensity.
+- `opacity`: glass opacity from `0–1`.
+- `ink`, `light`: RGB arrays in normalized `0–1`.\n- `shellDay`, `shellNight`, `hiNight`, `loNight`, `night`: day/night environment colors and blend amount, preserving the original renderer's lighting controls.
+- `dpr`: render pixel-ratio ceiling, default `2`.
+- `continuous`: redraw continuously for animated sources; set `false` for static sources and call `render()` when the source changes.
+
+The renderer uses WebGL2. It throws a clear error if WebGL2 is unavailable rather than silently substituting a visually unrelated fake-refraction effect.

package/{INTEGRATIONS.md → docs/INTEGRATIONS.md}

@@ -123,7 +123,7 @@ unregister();
 
 For CDN usage, load `scene-plugin.js` before `app.js`, then call `PixelDaylightSwitchScenePlugins.registerScene(manifest)` before mounting. The embed loader loads both scripts in the correct order for built-in scenes; custom manifests still need to be registered by the host page.
 
-Manifest v1 is data-only: a bounded pixel matrix, named palettes and a 24-hour palette timeline. See [the schema](schemas/scene-manifest.v1.schema.json) and [the example](examples/scenes/sakura-evening.json). Do not place executable code, remote script URLs or untrusted HTML in a manifest.
+Manifest v1 is data-only: a bounded pixel matrix, named palettes and a 24-hour palette timeline. See [the schema](../schemas/scene-manifest.v1.schema.json) and [the example](../examples/scenes/sakura-evening.json). Do not place executable code, remote script URLs or untrusted HTML in a manifest.
 
 ## Lifecycle and events
 
@@ -137,3 +137,24 @@ Manifest v1 is data-only: a bounded pixel matrix, named palettes and a 24-hour p
 ## Configuration
 
 See [README.md](README.md) for the complete list of `data-*` attributes, CSS custom properties, rendering behavior and supported scene identifiers.
+
+
+## Standalone refractive glass
+
+The independent glass layer is exported as `createGlass` and does not mount or depend on the day/night switch:
+
+```js
+import { createGlass } from 'pixel-daylight-switch-gsvegetable/glass-engine';
+const glass = createGlass(container, {
+  source: backgroundCanvas,
+  width: '70%', height: 180, left: '15%', top: 24,
+  radius: 28, refraction: 1.24, dispersion: 0.05,
+  bezel: 0.046, shine: 0.44
+});
+// Update, swap source, and clean up independently.
+glass.setOptions({ refraction: 1.32 });
+glass.setSource(nextCanvas);
+glass.destroy();
+```
+
+See [the complete glass engine guide](GLASS_ENGINE.md) and [live parameter demo](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html). The source must be an origin-clean canvas, image, video, bitmap or callback returning one. Arbitrary DOM cannot be sampled directly by WebGL; host applications must provide a renderable source.

package/docs/README.md

@@ -0,0 +1,5 @@
+# Project documentation
+
+- [Framework integration recipes](INTEGRATIONS.md) — React, Vue and plain HTML integration.
+- [Scene plugin authoring guide](SCENE_PLUGINS.md) — Manifest v2 assets, layers, motion and v1 compatibility.
+- [Changelog](CHANGELOG.md) — release history.

package/{SCENE_PLUGINS.md → docs/SCENE_PLUGINS.md}

@@ -1,10 +1,10 @@
 # Scene Plugin Guide
 
-Pixel Daylight Switch 3.0.0 introduces a declarative community-scene format. A scene is JSON data, not an executable JavaScript plugin. The renderer validates the manifest and draws the resulting pixel world through the existing refractive-glass pipeline.
+The Pixel Daylight Switch community scene system supports a declarative community-scene format. A scene is JSON data, not an executable JavaScript plugin. The renderer validates the manifest and draws the resulting pixel world through the existing refractive-glass pipeline.
 
 ## Two ways to create a scene
 
-**Palette creator:** Start with `examples/scenes/sakura-evening.json`, keep its pixel rows, and change the colors under `palettes`. This is the quickest way to create a distinct atmosphere.
+**Palette creator:** Start with `../examples/scenes/sakura-evening.json`, keep its pixel rows, and change the colors under `palettes`. This is the quickest way to create a distinct atmosphere.
 
 **Pixel-world creator:** Edit `canvas` and `pixels` to design your own geometry, then define a color for every symbol in each palette. Each character represents one pixel; rows must all have the declared width.
 
@@ -38,7 +38,7 @@ Load the registry before the renderer:
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
 <div data-ld-part="toggle-daylight" data-scene="sakura-evening"></div>
 <script>
-  PixelDaylightSwitch.registerScene(sceneManifest);
+  PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
 </script>
 ```
 
@@ -50,7 +50,7 @@ The one-line `embed.js` loader loads the registry before the renderer, but it do
 
 Required fields:
 
-- `schemaVersion`: currently `1`.
+- `schemaVersion`: `1` for the original single-matrix format or `2` for layered pixel assets and motion.
 - `id`: unique lowercase ID, 3–64 characters. Built-in scene IDs are reserved.
 - `name`, `author`, `license`: scene metadata.
 - `canvas`: width 1–192 and height 1–112.
@@ -60,7 +60,23 @@ Required fields:
 
 Every symbol used in `pixels` must have a color in every palette. The renderer interpolates the RGB values between adjacent time stops, including across midnight. Keep the first and last palette compatible to avoid a visible midnight jump.
 
-The authoritative machine-readable contract is [schemas/scene-manifest.v1.schema.json](schemas/scene-manifest.v1.schema.json). A complete sample is [examples/scenes/sakura-evening.json](examples/scenes/sakura-evening.json).
+The authoritative machine-readable contract is [../schemas/scene-manifest.v1.schema.json](../schemas/scene-manifest.v1.schema.json). A complete sample is [../examples/scenes/sakura-evening.json](../examples/scenes/sakura-evening.json).
+
+## Layered scenes and pixel assets (Manifest v2)
+
+Version 3.0.1 adds reusable pixel-art assets, compositing layers and deterministic motion tracks. Manifest v1 remains supported without changes; use `schemaVersion: 2` to opt in.
+
+A v2 manifest keeps the base `canvas`, `pixels`, `palettes` and `timeCycle`, and adds:
+
+- `assets`: up to 24 named pixel matrices (each up to 192 × 112).
+- `layers`: 1–16 ordered placements that reference an asset and specify integer `x` / `y` coordinates.
+- `animation`: optional `drift` or `bob` motion on either axis, with bounded speed, distance and phase.
+
+The dot character (`.`) is transparent when an asset is composited as a layer. All other characters are palette symbols, so every palette must define colors for symbols used by the base matrix and every asset. Layers are drawn in array order; later layers appear above earlier ones. Motion is deterministic and uses the scene's animation clock; it does not execute plugin code.
+
+Example: [Floating Island v2](../examples/scenes/floating-island.v2.json). The v2 contract is [../schemas/scene-manifest.v2.schema.json](../schemas/scene-manifest.v2.schema.json); the original v1 contract remains at [../schemas/scene-manifest.v1.schema.json](../schemas/scene-manifest.v1.schema.json).
+
+The current asset format is deliberately pixel-matrix based. Arbitrary PNG/JPEG downloads and executable animation callbacks are not part of v3.0.1; this keeps rendering crisp, portable, CSP-friendly and safe for community contributions.
 
 ## API
 
@@ -73,6 +89,6 @@ Registration rejects duplicate IDs, built-in IDs, malformed dimensions, invalid
 
 ## Scope and safety
 
-Manifest v1 supports palette-driven pixel maps. It intentionally does not execute plugin JavaScript, evaluate expressions, or load arbitrary code. External image/sprite assets, layered tile maps and custom animation tracks are not part of v1; they should be introduced through a separately versioned schema extension with explicit asset limits and lifecycle rules.
+Manifest v1 supports palette-driven pixel maps; Manifest v2 adds bounded pixel-matrix assets, ordered layers and declarative drift/bob tracks. Neither version executes plugin JavaScript, evaluates expressions, loads arbitrary code or downloads external images. Raster image imports and tile-atlas tooling are outside the v3.0.1 scope.
 
 All five built-in scenes continue to use their original hand-authored painters and scene-specific live behavior. Community scenes use the data-driven renderer and do not replace or mutate built-in scene definitions.

package/examples/scenes/floating-island.v2.json

@@ -0,0 +1,152 @@
+{
+  "schemaVersion": 2,
+  "id": "floating-island",
+  "name": "Floating Island",
+  "author": "Pixel Daylight Switch",
+  "license": "CC0-1.0",
+  "canvas": {
+    "width": 24,
+    "height": 12
+  },
+  "pixels": [
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................",
+    "........................"
+  ],
+  "palettes": {
+    "day": {
+      ".": "#8ed5f4",
+      "g": "#74b66d",
+      "t": "#79543f",
+      "l": "#f8d77a",
+      "c": "#ffffff"
+    },
+    "dusk": {
+      ".": "#e99a91",
+      "g": "#627e69",
+      "t": "#5b4653",
+      "l": "#f6bb86",
+      "c": "#f4c6d0"
+    },
+    "night": {
+      ".": "#171d3b",
+      "g": "#304b4a",
+      "t": "#302c43",
+      "l": "#f1d28a",
+      "c": "#a8b7e8"
+    }
+  },
+  "timeCycle": [
+    {
+      "at": 0,
+      "palette": "night"
+    },
+    {
+      "at": 6,
+      "palette": "night"
+    },
+    {
+      "at": 8,
+      "palette": "day"
+    },
+    {
+      "at": 17,
+      "palette": "day"
+    },
+    {
+      "at": 19,
+      "palette": "dusk"
+    },
+    {
+      "at": 21,
+      "palette": "night"
+    },
+    {
+      "at": 24,
+      "palette": "night"
+    }
+  ],
+  "assets": {
+    "island": {
+      "width": 14,
+      "height": 4,
+      "pixels": [
+        "......gg......",
+        "....gggggg....",
+        "..gggggggggg..",
+        "gggggggggggggg"
+      ]
+    },
+    "tree": {
+      "width": 5,
+      "height": 7,
+      "pixels": [
+        "..g..",
+        ".ggg.",
+        "ggggg",
+        "..t..",
+        "..t..",
+        "..t..",
+        "..t.."
+      ]
+    },
+    "cloud": {
+      "width": 8,
+      "height": 3,
+      "pixels": [
+        "..cccc..",
+        ".cccccc.",
+        "cccccccc"
+      ]
+    }
+  },
+  "layers": [
+    {
+      "id": "island",
+      "asset": "island",
+      "x": 5,
+      "y": 7
+    },
+    {
+      "id": "tree",
+      "asset": "tree",
+      "x": 8,
+      "y": 0
+    },
+    {
+      "id": "cloud-left",
+      "asset": "cloud",
+      "x": -3,
+      "y": 2,
+      "animation": {
+        "type": "drift",
+        "axis": "x",
+        "speed": 0.12,
+        "distance": 4,
+        "phase": 0
+      }
+    },
+    {
+      "id": "cloud-right",
+      "asset": "cloud",
+      "x": 17,
+      "y": 4,
+      "animation": {
+        "type": "bob",
+        "axis": "y",
+        "speed": 0.18,
+        "distance": 2,
+        "phase": 1.4
+      }
+    }
+  ]
+}

package/glass-engine.js

@@ -0,0 +1,162 @@
+/*!
+ * Pixel Daylight Switch — standalone refractive glass engine
+ * Unlicense. The optical lens equations are adapted from the original app.js shader.
+ */
+(function (root, factory) {
+  'use strict';
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.PixelGlassEngine = api;
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict';
+  const VERT = `#version 300 es
+  in vec2 aPos;
+  void main(){ gl_Position=vec4(aPos,0.0,1.0); }`;
+  const FRAG = `#version 300 es
+  precision highp float;
+  uniform sampler2D uSource;
+  uniform vec2 uResolution, uCenter, uHalf, uSourceSize;
+  uniform float uRadius, uRefraction, uDispersion, uBezel, uShine, uOpacity, uEdgeDark;
+  uniform vec3 uInk, uLight, uShellDay, uShellNight, uHiNight, uLoNight;\n  uniform float uNight;\n  vec3 envLow, envHigh;
+  out vec4 outColor;
+  float sdRoundBox(vec2 p, vec2 b, float r) {
+    vec2 q=abs(p)-b+vec2(r);
+    return length(max(q,0.0))+min(max(q.x,q.y),0.0)-r;
+  }
+  float softBox(vec2 p, vec2 c, vec2 h, float s) {
+    vec2 q=abs(p-c)-h;
+    float d=length(max(q,0.0))+min(max(q.x,q.y),0.0);
+    return 1.0-smoothstep(-s,s,d);
+  }
+  vec3 smoothTex(vec2 uv) {
+    vec2 st=uv*uSourceSize-0.5, i=floor(st), f=st-i, f2=f*f, f3=f2*f;
+    vec2 w0=(1.0-3.0*f+3.0*f2-f3)/6.0;
+    vec2 w1=(4.0-6.0*f2+3.0*f3)/6.0;
+    vec2 w2=(1.0+3.0*f+3.0*f2-3.0*f3)/6.0;
+    vec2 w3=f3/6.0, g0=w0+w1, g1=w2+w3;
+    vec2 h0=(i-0.5+w1/g0+0.5)/uSourceSize;
+    vec2 h1=(i+1.5+w3/g1+0.5)/uSourceSize;
+    return g0.y*(g0.x*texture(uSource,vec2(h0.x,h0.y)).rgb+g1.x*texture(uSource,vec2(h1.x,h0.y)).rgb)
+      +g1.y*(g0.x*texture(uSource,vec2(h0.x,h1.y)).rgb+g1.x*texture(uSource,vec2(h1.x,h1.y)).rgb);
+  }
+  vec3 studio(vec3 R) {
+    vec3 c=mix(envLow,envHigh,smoothstep(-0.55,0.85,R.y));
+    vec2 s=R.xy/(1.0+max(R.z,0.0));
+    float key=softBox(s,vec2(-0.1,0.56),vec2(0.5,0.11),0.17);
+    float fill=softBox(s,vec2(0.34,-0.6),vec2(0.3,0.05),0.2);
+    c+=envHigh*key*1.15;
+    c+=envHigh*fill*0.14;
+    return c;
+  }
+  void main(){
+    envLow=mix(uShellDay*0.74,uLoNight,uNight);
+    envHigh=mix(uLight,uHiNight,uNight);
+    vec2 frag=gl_FragCoord.xy;
+    vec2 p=frag-uCenter;
+    float d=sdRoundBox(p,uHalf,uRadius);
+    if(d>1.0){outColor=vec4(0.0);return;}
+    vec2 q=p;
+    vec2 inner=max(uHalf-uRadius,vec2(0.0));
+    q.x=sign(p.x)*max(abs(p.x)-inner.x,0.0);
+    q.y=sign(p.y)*max(abs(p.y)-inner.y,0.0);
+    float rad=length(q);
+    vec2 gr=q/max(rad,1.0e-3);
+    float rho=clamp(rad/max(uRadius,1.0),0.0,1.0);
+    float mag=max(uRefraction,1.001);
+    float bt=clamp((rho-0.7)/0.3,0.0,1.0);
+    float band=bt*bt*(3.0-2.0*bt);
+    float strength=1.0-1.0/mag+0.2;
+    float bend=pow(band,2.2)*uRadius*strength;
+    vec2 base=uCenter+p/mag;
+    vec2 shiftDir=gr*bend;
+    float ca=uDispersion*band;
+    vec2 uvR=(base+shiftDir*(1.0-ca))/uResolution;
+    vec2 uvG=(base+shiftDir)/uResolution;
+    vec2 uvB=(base+shiftDir*(1.0+ca))/uResolution;
+    vec3 seen;
+    if(band>0.02) seen=vec3(smoothTex(uvR).r,smoothTex(uvG).g,smoothTex(uvB).b);
+    else seen=smoothTex(uvG);
+    vec2 tilt=gr*(0.22*rho+0.78*pow(rho,7.0));
+    vec3 N=normalize(vec3(tilt,sqrt(max(1.0-dot(tilt,tilt),0.02))));
+    vec3 R=vec3(2.0*N.z*N.xy,2.0*N.z*N.z-1.0);
+    vec2 lp=q/max(uRadius,1.0);
+    vec3 lens=seen*1.035;
+    float edge=pow(rho,16.0);
+    lens=mix(lens,uInk,edge*0.42);
+    float pool=smoothstep(0.05,0.95,-lp.y*0.9+lp.x*0.2)*smoothstep(1.0,0.8,rho)*smoothstep(0.42,0.86,rho);
+    lens+=envHigh*pool*mix(0.3,0.1,uNight);
+    float broad=softBox(lp,vec2(-0.1,0.62),vec2(0.5,0.17),0.3)*smoothstep(0.98,0.72,rho);
+    lens=mix(lens,envHigh,broad*mix(uShine,0.1,uNight));
+    float fresnel=pow(1.0-N.z,3.0);
+    float dir=0.2+0.8*smoothstep(-0.6,0.85,dot(gr,normalize(vec2(-0.42,0.9))));
+    float mirror=clamp(fresnel*dir*dir*0.6,0.0,0.42);
+    if(mirror>1.0e-3) lens=mix(lens,studio(R),mirror);
+    float alpha=uOpacity*(1.0-smoothstep(0.0,1.0,d));
+    outColor=vec4(clamp(lens,0.0,1.0)*alpha,alpha);
+  }`;
+  const defaults={width:'100%',height:'100%',left:'0px',top:'0px',radius:'28px',refraction:1.24,dispersion:0.05,bezel:0.046,shine:0.44,opacity:1,edgeDark:0.42,ink:[0.08,0.1,0.16],light:[0.94,0.97,1],shellDay:[0.42,0.52,0.62],shellNight:[0.08,0.1,0.16],hiNight:[0.42,0.5,0.62],loNight:[0.06,0.08,0.13],night:0,dpr:2,continuous:true};
+  function createGlass(container, options) {
+    if(!container || !container.ownerDocument) throw new TypeError('createGlass(container): a DOM element is required');
+    const opts={...defaults,...(options||{})};
+    if(!opts.source) throw new TypeError('createGlass requires a renderable source (canvas, image, video, bitmap, or callback).');
+    const doc=container.ownerDocument;
+    const canvas=doc.createElement('canvas');
+    canvas.setAttribute('aria-hidden','true');
+    canvas.className='pixel-glass-engine';
+    canvas.style.cssText='position:absolute;inset:0;width:100%;height:100%;pointer-events:none;z-index:1;display:block;max-width:none;max-height:none;';
+    const computed=doc.defaultView.getComputedStyle(container);
+    const previousPosition=container.style.position;
+    if(computed.position==='static') container.style.position='relative';
+    container.appendChild(canvas);
+    const gl=canvas.getContext('webgl2',{alpha:true,premultipliedAlpha:true,antialias:false,depth:false,stencil:false,powerPreference:'high-performance'});
+    if(!gl){canvas.remove();if(previousPosition!==container.style.position)container.style.position=previousPosition;throw new Error('PixelGlassEngine requires WebGL2.');}
+    const compile=(type,src)=>{const s=gl.createShader(type);gl.shaderSource(s,src);gl.compileShader(s);if(!gl.getShaderParameter(s,gl.COMPILE_STATUS)){const msg=gl.getShaderInfoLog(s);gl.deleteShader(s);throw new Error(msg||'Shader compilation failed');}return s;};
+    let program,vao,buffer,texture,raf=0,destroyed=false,source=opts.source||null,resizeObserver=null,dim={w:1,h:1};
+    try{
+      program=gl.createProgram();const vs=compile(gl.VERTEX_SHADER,VERT),fs=compile(gl.FRAGMENT_SHADER,FRAG);
+      gl.attachShader(program,vs);gl.attachShader(program,fs);gl.bindAttribLocation(program,0,'aPos');gl.linkProgram(program);gl.deleteShader(vs);gl.deleteShader(fs);
+      if(!gl.getProgramParameter(program,gl.LINK_STATUS))throw new Error(gl.getProgramInfoLog(program)||'Shader link failed');
+      gl.useProgram(program);vao=gl.createVertexArray();gl.bindVertexArray(vao);buffer=gl.createBuffer();gl.bindBuffer(gl.ARRAY_BUFFER,buffer);gl.bufferData(gl.ARRAY_BUFFER,new Float32Array([-1,-1,3,-1,-1,3]),gl.STATIC_DRAW);gl.enableVertexAttribArray(0);gl.vertexAttribPointer(0,2,gl.FLOAT,false,0,0);
+      texture=gl.createTexture();gl.activeTexture(gl.TEXTURE0);gl.bindTexture(gl.TEXTURE_2D,texture);gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_MIN_FILTER,gl.LINEAR);gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_MAG_FILTER,gl.LINEAR);gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_WRAP_S,gl.CLAMP_TO_EDGE);gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_WRAP_T,gl.CLAMP_TO_EDGE);gl.uniform1i(gl.getUniformLocation(program,'uSource'),0);
+    }catch(error){canvas.remove();throw error;}
+    const U={};for(const n of ['uResolution','uCenter','uHalf','uSourceSize','uRadius','uRefraction','uDispersion','uBezel','uShine','uOpacity','uEdgeDark','uInk','uLight','uShellDay','uShellNight','uHiNight','uLoNight','uNight'])U[n]=gl.getUniformLocation(program,n);
+    function resolveSource(){if(typeof source==='function')return source();return source;}
+    function dimensions(el){return {w:el?.videoWidth||el?.naturalWidth||el?.width||0,h:el?.videoHeight||el?.naturalHeight||el?.height||0};}
+    function draw(){
+      raf=0;if(destroyed)return;
+      const rect=container.getBoundingClientRect(),dpr=Math.min(Number(opts.dpr)||2,doc.defaultView.devicePixelRatio||1,2);
+      const W=Math.max(2,Math.round(rect.width*dpr)),H=Math.max(2,Math.round(rect.height*dpr));
+      if(!W||!H)return;
+      if(canvas.width!==W||canvas.height!==H){canvas.width=W;canvas.height=H;gl.viewport(0,0,W,H);}
+      const el=resolveSource();
+      if(!el){if(opts.background){gl.bindTexture(gl.TEXTURE_2D,texture);gl.texImage2D(gl.TEXTURE_2D,0,gl.RGBA,1,1,0,gl.RGBA,gl.UNSIGNED_BYTE,new Uint8Array([245,236,217,255]));}else{if(opts.continuous)raf=doc.defaultView.requestAnimationFrame(draw);return;}}
+      else{
+        dim=dimensions(el);if(!dim.w||!dim.h){if(opts.continuous)raf=doc.defaultView.requestAnimationFrame(draw);return;}
+        gl.activeTexture(gl.TEXTURE0);gl.bindTexture(gl.TEXTURE_2D,texture);gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL,1);gl.texImage2D(gl.TEXTURE_2D,0,gl.RGBA,gl.RGBA,gl.UNSIGNED_BYTE,el);
+      }
+      gl.clearColor(0,0,0,0);gl.clear(gl.COLOR_BUFFER_BIT);gl.useProgram(program);gl.bindVertexArray(vao);
+      const width=opts.width,height=opts.height,left=opts.left,top=opts.top;
+      const cssPx=(v,total)=>{if(typeof v==='number')return v;const value=String(v??'').trim();if(value.endsWith('%'))return (parseFloat(value)||0)*total/100;return parseFloat(value)||total;};
+      const w=cssPx(width,rect.width),h=cssPx(height,rect.height),x=cssPx(left,rect.width),y=cssPx(top,rect.height);
+      const cx=(x+w/2)*dpr,cy=H-(y+h/2)*dpr,halfX=w*dpr/2,halfY=h*dpr/2;
+      const radius=Math.min(cssPx(opts.radius,Math.min(w,h)*0.28)*dpr,halfX,halfY);
+      const bezel=Math.max(0.1,Math.min(0.3,Number(opts.bezel)||0.046))*Math.min(halfX,halfY);
+      gl.uniform2f(U.uResolution,W,H);gl.uniform2f(U.uCenter,cx,cy);gl.uniform2f(U.uHalf,halfX,halfY);gl.uniform2f(U.uSourceSize,dim?.w||W,dim?.h||H);
+      gl.uniform1f(U.uRadius,radius);gl.uniform1f(U.uRefraction,Math.max(1.001,Number(opts.refraction)||1.24));gl.uniform1f(U.uDispersion,Math.max(0,Math.min(.25,Number(opts.dispersion)||0)));gl.uniform1f(U.uBezel,bezel);gl.uniform1f(U.uShine,Math.max(0,Number(opts.shine)||0));gl.uniform1f(U.uOpacity,Math.max(0,Math.min(1,Number(opts.opacity)??1)));gl.uniform1f(U.uEdgeDark,Math.max(0,Math.min(1,Number(opts.edgeDark)??.42)));gl.uniform3fv(U.uInk,new Float32Array(opts.ink||defaults.ink));gl.uniform3fv(U.uLight,new Float32Array(opts.light||defaults.light));gl.uniform3fv(U.uShellDay,new Float32Array(opts.shellDay||defaults.shellDay));gl.uniform3fv(U.uShellNight,new Float32Array(opts.shellNight||defaults.shellNight));gl.uniform3fv(U.uHiNight,new Float32Array(opts.hiNight||defaults.hiNight));gl.uniform3fv(U.uLoNight,new Float32Array(opts.loNight||defaults.loNight));gl.uniform1f(U.uNight,Math.max(0,Math.min(1,Number(opts.night)||0)));
+      gl.drawArrays(gl.TRIANGLES,0,3);
+      if(opts.continuous)raf=doc.defaultView.requestAnimationFrame(draw);
+    }
+    function schedule(){if(!raf&&!destroyed)raf=doc.defaultView.requestAnimationFrame(draw);}
+    resizeObserver=typeof ResizeObserver!=='undefined'?new ResizeObserver(schedule):null;resizeObserver?.observe(container);
+    if(source&&typeof source==='object'&&'addEventListener'in source){source.addEventListener('loadeddata',schedule);source.addEventListener('resize',schedule);}
+    schedule();
+    return {
+      canvas,
+      setSource(next){source=next;schedule();return this;},
+      setOptions(next){Object.assign(opts,next||{});schedule();return this;},
+      render(){if(raf)doc.defaultView.cancelAnimationFrame(raf);raf=0;draw();return this;},
+      destroy(){if(destroyed)return;destroyed=true;if(raf)doc.defaultView.cancelAnimationFrame(raf);resizeObserver?.disconnect();if(source&&typeof source==='object'&&'removeEventListener'in source){source.removeEventListener('loadeddata',schedule);source.removeEventListener('resize',schedule);}gl.deleteTexture(texture);gl.deleteBuffer(buffer);gl.deleteVertexArray(vao);gl.deleteProgram(program);canvas.remove();if(previousPosition!==container.style.position&&container.style.position==='relative')container.style.position=previousPosition;}
+    };
+  }
+  return {createGlass,version:'3.1.1'};
+});

package/glass-engine.mjs

@@ -0,0 +1,4 @@
+import './glass-engine.js';
+const createGlass = globalThis.PixelGlassEngine.createGlass;
+export { createGlass };
+export default globalThis.PixelGlassEngine;

package/index.cjs

@@ -8,4 +8,5 @@ api.registerScene = scenes.registerScene;
 api.validateScene = scenes.validateScene;
 api.getScene = scenes.getScene;
 api.listScenes = scenes.listScenes;
+api.createGlass = require('./glass-engine.js').createGlass;
 module.exports = api;