pixel-daylight-switch-gsvegetable 3.0.1 → 3.1.1

package/README.ja.md

@@ -12,22 +12,22 @@
 
 Pixel Daylight Switch は、ドラッグ操作で昼・夕暮れ・夜を切り替えられる UI コンポーネントです。ガラスレンズの中のピクセルアートの世界が、スイッチの動きに合わせて変化します。Vanilla JavaScript、WebGL2、Canvas 2D フォールバックで構成され、実行時にサードパーティ製ライブラリを必要としません。
 
-**[ライブデモ](https://gsvegetable.github.io/pixel-daylight-switch/)** · **[パラメーター Playground](https://gsvegetable.github.io/pixel-daylight-switch/playground.html)** · **[npm パッケージ](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable)**
+**[ライブデモ](https://gsvegetable.github.io/pixel-daylight-switch/)** · **[パラメーター Playground](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html)** · **[npm パッケージ](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable)**
 
 ## 目的別リンク
 
 | 目的 | リンク |
 | --- | --- |
 | スイッチを体験する | [ライブデモ](https://gsvegetable.github.io/pixel-daylight-switch/) |
-| シーンや表示を調整する | [パラメーター Playground](https://gsvegetable.github.io/pixel-daylight-switch/playground.html) |
-| コンポーネントを見る | [Preview](https://gsvegetable.github.io/pixel-daylight-switch/preview.html) |
+| シーンや表示を調整する | [パラメーター Playground](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html) |
+| コンポーネントを見る | [Preview](https://gsvegetable.github.io/pixel-daylight-switch/demos/preview.html) |
 | Web サイトに埋め込む | [embed.js](embed.js) |
 | JavaScript プロジェクトで使う | [npm](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable) |
-| React / Vue の導入例 | [フレームワーク統合ガイド](INTEGRATIONS.md) |
+| React / Vue の導入例 | [フレームワーク統合ガイド](docs/INTEGRATIONS.md) |
 | 実装を読む | [app.js](app.js) · [style.css](style.css) |
 | モバイルビルド | [ビルド情報](builds/README.md) · [GitHub Actions](https://github.com/GSvegetable/pixel-daylight-switch/actions/workflows/mobile-build.yml) |
 | テスト結果 | [CI ワークフロー](https://github.com/GSvegetable/pixel-daylight-switch/actions/workflows/ci.yml) |
-| 更新履歴 | [CHANGELOG](CHANGELOG.md) |
+| 更新履歴 | [CHANGELOG](docs/CHANGELOG.md) |
 | 不具合を報告する | [Issues](https://github.com/GSvegetable/pixel-daylight-switch/issues) |
 
 ## 主な機能
@@ -96,50 +96,61 @@ const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable');
 
 ESM と CommonJS の両方を提供します。SSR 環境でもインポートできますが、`mount()` はブラウザー上で対象要素が存在してから呼び出してください。
 
-## コミュニティシーンプラグイン（v3.0.0）
 
-3.0.0 では JSON Manifest によるカスタムピクセルワールドの登録に対応しました。初めての方はピクセルマップをそのまま使い、昼夜パレットの色だけを変更できます。上級者はピクセルマップと時間パレットを自由に設計できます。プラグインは宣言型データのみを受け取り、レンダラー内で第三者 JavaScript を実行しません。
+## 独立ガラス屈折エンジン（v3.1.1）
 
-**ブラウザーで使用：**
+ガラスレンズを昼夜スイッチから独立して利用できるようになりました。固定アスペクト比に依存せず、幅・高さ・位置・角丸・屈折・色分散・縁の厚さ・ハイライトを個別に設定できます。Canvas、画像、動画、ImageBitmap、またはそれらを返す関数を背景ソースとして指定します。[ガイド](docs/GLASS_ENGINE.md) と [ライブデモ](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html) を参照してください。
 
-```html
-<script src="https://gsvegetable.github.io/pixel-daylight-switch/scene-plugin.js"></script>
-<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);
-</script>
+```js
+import { createGlass } from 'pixel-daylight-switch-gsvegetable/glass-engine';
+const glass = createGlass(container, { source: backgroundCanvas, width: '72%', height: 180, radius: 28 });
+glass.setOptions({ refraction: 1.3, dispersion: 0.08 });
+glass.destroy();
 ```
 
-コンポーネントをマウントする前に Manifest を登録してください。npm の場合：
+WebGL は任意の DOM ピクセルを直接読み取れません。Web ページの背景を屈折させるには、ホストアプリが Canvas などの描画ソースを提供する必要があります。クロスオリジンメディアには CORS 制約があります。
+
+## コミュニティシーン
+
+コミュニティシーンは宣言型 JSON Manifest で定義し、コンポーネントのマウント前に登録します。現在の形式は **Manifest v2** です。再利用可能なピクセル素材、順序付きレイヤー、制限付きモーショントラックに対応し、既存の Manifest v1 シーンも引き続き利用できます。
+
+### シーンの登録
+
+npm プロジェクトの場合：
 
 ```js
 import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
-import myScene from './my-scene.json';
+import scene from './floating-island.v2.json';
 
-const unregister = registerScene(myScene);
+const unregister = registerScene(scene);
 const root = document.querySelector('[data-ld-part="toggle-daylight"]');
-root.dataset.scene = myScene.id;
+root.dataset.scene = scene.id;
 PixelDaylightSwitch.mount(root);
 ```
 
-Manifest v1 はシーン ID、作者・ライセンス、ピクセルキャンバス、文字ベースのピクセルマップ、複数の昼夜パレット、24 時間のタイムラインで構成されます。キャンバスは最大 192 × 112 ピクセルです。すべてのピクセル記号に各パレットの色を定義する必要があります。時間ノード間の色はレンダラーが補間します。
+ブラウザーで直接使用する場合は、`scene-plugin.js` を `app.js` より先に読み込み、マウント前に Manifest を登録します。
 
-- [プラグイン開発ガイド](SCENE_PLUGINS.md)
-- [Manifest v1 JSON Schema](schemas/scene-manifest.v1.schema.json)
-- [Sakura Evening サンプル](examples/scenes/sakura-evening.json)
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/scene-plugin.js"></script>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
+<div data-ld-part="toggle-daylight" data-scene="my-community-scene"></div>
+<script>
+  PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
+</script>
+```
 
-### Manifest v2：レイヤー付きピクセルワールド（v3.0.1）
+### Manifest v2 の機能
 
-3.0.1 では Manifest v1 を変更せずに v2 を追加しました。v2 は最大 24 個の再利用可能なピクセルアセットと、最大 16 個の順序付きレイヤーに対応します。レイヤーはシーン座標に配置でき、drift または bob の宣言型モーショントラックで横・縦方向に動かせます。重ねるアセット内の . は透明として扱い、それ以外の文字は昼夜パレットで着色されます。
+- 最大 24 個の再利用可能な文字ベースのピクセル素材と、最大 16 個の順序付きレイヤー。
+- 整数のシーン座標を使用し、後のレイヤーほど手前に合成されます。
+- オーバーレイ素材のドット文字 `.` は透明ピクセルとして扱われます。
+- `drift` と `bob` の決定論的なモーショントラックに対応し、X/Y 軸上で動作します。
+- 既存の Manifest v1 と 5 つの組み込みシーンは引き続きサポートされます。
 
-- [Manifest v2 JSON Schema](schemas/scene-manifest.v2.schema.json)
-- [Floating Island レイヤーサンプル](examples/scenes/floating-island.v2.json)
-- [シーンプラグイン開発ガイド](SCENE_PLUGINS.md)
+[Manifest v2 Schema](schemas/scene-manifest.v2.schema.json)、[Floating Island サンプル](examples/scenes/floating-island.v2.json)、[シーン制作ガイド](docs/SCENE_PLUGINS.md)を参照してください。互換性のため [v1 Schema](schemas/scene-manifest.v1.schema.json) も維持されています。
 
-v2 のアセットは文字ベースのピクセルマップです。PNG/JPEG の外部ダウンロードには対応しません。これによりピクセル表現と昼夜の色変化を一貫させ、外部画像の CORS や任意コード実行を避けます。
+現在の素材形式は文字ベースのピクセルマトリックスです。PNG/JPEG のアップロードや任意の実行コードには対応していません。
 
-5 つの組み込みシーンは従来の描画・アニメーション実装を維持します。
 
 ## 設定属性
 
@@ -248,35 +259,27 @@ iOS は初回に `npm run mobile:ios:init`、以降は `npm run mobile:ios` を
 ```text
 pixel-daylight-switch/
 ├── .github/workflows/       # CI、モバイルビルド、npm 公開
-├── assets/
-│   └── scene-gallery.png    # 5 シーンの一覧画像
-├── builds/
-│   └── README.md            # モバイル成果物の説明（バイナリは Actions が生成）
-├── mobile/
-│   ├── index.html            # Capacitor アプリの入口
-│   └── mobile.css            # モバイル専用レイアウト
-├── scripts/
-│   └── prepare-mobile.cjs   # Capacitor 用 Web ランタイム準備
-├── tests/
-│   ├── browser/              # Playwright 操作・モバイル回帰テスト
-│   ├── fixture.html
-│   ├── mobile-smoke.cjs
-│   ├── package-smoke.cjs
-│   └── server.cjs
-├── app.js                    # コンポーネント、シーン、入力、描画
-├── style.css                 # コンポーネントのスタイル
-├── embed.js                  # 1 スクリプト埋め込みローダー
-├── index.html                # ライブデモ
-├── preview.html              # コンポーネントプレビュー
-├── playground.html            # パラメーター Playground
-├── index.mjs / index.cjs     # ESM / CommonJS エントリー
-├── package.json               # npm メタデータとスクリプト
-├── capacitor.config.json     # Capacitor 設定
-├── playwright.config.cjs     # ブラウザーテスト設定
-├── CHANGELOG.md
-├── llms.txt
+├── assets/                  # シーンギャラリー画像
+├── builds/                  # モバイルビルド情報
+├── docs/                    # 統合ガイド、シーン制作ガイド、変更履歴
+├── examples/scenes/         # コミュニティシーン Manifest
+├── mobile/                  # Capacitor アプリシェル
+├── schemas/                 # Manifest v1 / v2 JSON Schema
+├── scripts/                 # モバイル準備・バージョン設定
+├── tests/                   # Node / Chromium 回帰テスト
+├── app.js / style.css       # ランタイムとコンポーネントスタイル
+├── scene-plugin.js          # シーン登録・検証 API
+├── embed.js                 # Web サイト埋め込みローダー
+├── index.html               # ライブデモ
+├── demos/                   # パラメーター Playground と Preview
+├── config/                  # 開発ツール設定
+├── index.mjs / index.cjs    # ESM / CommonJS エントリー
+├── package.json             # パッケージ設定とスクリプト
+├── capacitor.config.json    # Capacitor 設定
+├── playwright.config.cjs    # ブラウザーテスト設定
+├── llms.txt                 # AI 向けプロジェクトガイド
 ├── LICENSE
-└── README*.md                 # 英語・簡体字中国語・日本語の README
+└── README*.md               # 英語・簡体字中国語・日本語 README
 ```
 
 ## ライセンス

package/README.md

@@ -12,23 +12,23 @@
 
 Pixel Daylight Switch is a draggable day/night UI component. Move its glass control to travel between day, dusk and night while a miniature pixel-art world changes inside the lens. It uses vanilla JavaScript, WebGL2 and a Canvas 2D fallback, with no third-party runtime dependency.
 
-**[Open the live demo](https://gsvegetable.github.io/pixel-daylight-switch/)** · **[Launch the parameter lab](https://gsvegetable.github.io/pixel-daylight-switch/playground.html)** · **[Install from npm](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable)**
+**[Open the live demo](https://gsvegetable.github.io/pixel-daylight-switch/)** · **[Launch the parameter lab](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html)** · **[Install from npm](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable)**
 
 ## Start here
 
 | Goal | Direct link |
 | --- | --- |
 | Experience the switch | [Live demo](https://gsvegetable.github.io/pixel-daylight-switch/) |
-| Customize scenes and visual behavior | [Interactive parameter lab](https://gsvegetable.github.io/pixel-daylight-switch/playground.html) |
-| Inspect the component | [Preview page](https://gsvegetable.github.io/pixel-daylight-switch/preview.html) |
+| Customize scenes and visual behavior | [Interactive parameter lab](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html) |
+| Inspect the component | [Preview page](https://gsvegetable.github.io/pixel-daylight-switch/demos/preview.html) |
 | Add it to a website with one script | [Embed loader source](embed.js) |
 | Use it in a JavaScript project | [npm package](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable) |
-| Framework integration recipes | [React and Vue examples](INTEGRATIONS.md) |
-| Scene plugin authoring guide | [Scene plugin guide](SCENE_PLUGINS.md) |
+| Framework integration recipes | [React and Vue examples](docs/INTEGRATIONS.md) |\n| Standalone glass refraction | [Glass engine guide](docs/GLASS_ENGINE.md) · [Live demo](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html) |
+| Scene plugin authoring guide | [Scene plugin guide](docs/SCENE_PLUGINS.md) |
 | Read implementation details | [Runtime](app.js) · [Styles](style.css) |
 | Download mobile builds | [Build notes and limitations](builds/README.md) · [GitHub Actions artifacts](https://github.com/GSvegetable/pixel-daylight-switch/actions/workflows/mobile-build.yml) |
 | Check tests | [CI workflow](https://github.com/GSvegetable/pixel-daylight-switch/actions/workflows/ci.yml) |
-| Review changes | [Changelog](CHANGELOG.md) |
+| Review changes | [Changelog](docs/CHANGELOG.md) |
 | Report a bug | [Issue tracker](https://github.com/GSvegetable/pixel-daylight-switch/issues) |
 
 ## Features
@@ -97,72 +97,61 @@ const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable');
 
 The package exposes ESM and CommonJS entry points. Importing is safe in an SSR environment; call `mount()` only in a browser after the target element exists. The package's published file list is defined in [package.json](package.json).
 
-## Community scene plugins (v3.0.0)
 
-Version 3 introduces a data-driven scene plugin API. Community scenes use a JSON manifest; they do not execute third-party JavaScript inside the renderer.
+## Standalone glass engine (v3.1.1)
 
-### Register a scene
-
-Load the registry before the renderer when using script tags:
-
-```html
-<script src="https://gsvegetable.github.io/pixel-daylight-switch/scene-plugin.js"></script>
-<script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
-<div data-ld-part="toggle-daylight" data-scene="sakura-evening"></div>
-```
-
-Register a manifest before mounting the component:
+The glass lens is also available independently of the day/night switch. It accepts a canvas, image, video, bitmap, or source callback and lets you set any width, height, position, radius, refraction, dispersion, bezel and highlight values. See the [glass engine guide](docs/GLASS_ENGINE.md) and [live demo](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html).
 
 ```js
-const unregister = PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
-PixelDaylightSwitch.mount(document.querySelector('[data-ld-part="toggle-daylight"]'));
+import { createGlass } from 'pixel-daylight-switch-gsvegetable/glass-engine';
+const glass = createGlass(container, { source: backgroundCanvas, width: '72%', height: 180, radius: 28 });
+glass.setOptions({ refraction: 1.3, dispersion: 0.08 });
+glass.destroy();
 ```
 
-With npm:
+WebGL cannot sample arbitrary DOM pixels directly. To refract a live page background, provide an origin-clean canvas/render target from your application. Cross-origin media is subject to browser CORS rules.
 
-```js
-import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
-import sakura from './sakura-evening.json';
+## Community scenes
 
-registerScene(sakura);
-PixelDaylightSwitch.mount(document.querySelector('[data-ld-part="toggle-daylight"]'));
-```
+Community scenes are declarative JSON manifests registered before the component is mounted. The current format is **Manifest v2**, which supports reusable pixel-matrix assets, ordered layers and bounded motion tracks. Existing Manifest v1 scenes remain compatible.
 
-### Manifest v2 — layered pixel worlds (v3.0.1)
+### Register a scene
 
-Version 3.0.1 extends the community scene format without changing Manifest v1. V2 scenes can define up to 24 reusable pixel-matrix assets and up to 16 ordered layers. A layer places an asset at integer scene coordinates and can optionally animate with a deterministic drift or bob track along either axis. The dot (.) is transparent in overlay assets; all other symbols are color-mapped by the scene palettes.
+For npm projects:
 
 ```js
 import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
-import island from './floating-island.v2.json';
+import scene from './floating-island.v2.json';
 
-registerScene(island);
+const unregister = registerScene(scene);
 const root = document.querySelector('[data-ld-part="toggle-daylight"]');
-root.dataset.scene = island.id;
+root.dataset.scene = scene.id;
 PixelDaylightSwitch.mount(root);
 ```
 
-- [Manifest v2 JSON Schema](schemas/scene-manifest.v2.schema.json)
-- [Floating Island layered example](examples/scenes/floating-island.v2.json)
-- [Full scene authoring guide](SCENE_PLUGINS.md)
+For direct browser usage, load `scene-plugin.js` before `app.js`, then register the manifest before mounting:
 
-V2 assets are native pixel matrices, not downloaded PNG/JPEG files. This keeps the scene pipeline deterministic and avoids remote asset/CORS dependencies or executable plugin code.
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/scene-plugin.js"></script>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
+<div data-ld-part="toggle-daylight" data-scene="my-community-scene"></div>
+<script>
+  PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
+</script>
+```
 
-## Manifest v1
+### Manifest v2 capabilities
 
-A manifest contains a fixed-size character pixel map, named color palettes and a 24-hour palette timeline. The renderer interpolates colors between timeline stops while keeping the same scene geometry.
+- Up to 24 reusable pixel-matrix assets and 16 ordered layers.
+- Integer scene coordinates; later layers are composited above earlier layers.
+- The dot character (`.`) is transparent in overlay assets.
+- Optional deterministic `drift` and `bob` motion tracks on either axis.
+- Existing v1 manifests and all five built-in scenes remain supported and unchanged.
 
-- Canvas limit: 192 × 112 pixels.
-- Pixel rows must match the declared width and height.
-- Every symbol used by the pixel map must have a color in every palette.
-- Colors use `#RGB` or `#RRGGBB`.
-- Timeline stops are strictly increasing and range from 0 to 24 hours.
-- Built-in scene IDs are reserved; community IDs must be unique.
-- The runtime accepts declarative data only. Manifest data is validated and copied on registration; it cannot run scripts.
+See the [Manifest v2 schema](schemas/scene-manifest.v2.schema.json), [Floating Island example](examples/scenes/floating-island.v2.json) and [scene authoring guide](docs/SCENE_PLUGINS.md). The v1 schema remains available for compatibility at [schemas/scene-manifest.v1.schema.json](schemas/scene-manifest.v1.schema.json).
 
-See the [v1 JSON Schema](schemas/scene-manifest.v1.schema.json) and [Sakura Evening example](examples/scenes/sakura-evening.json). The public API is `registerScene(manifest)`, `validateScene(manifest)`, `getScene(id)`, and `listScenes()`. The returned unregister function removes that registration.
+Assets currently use native character pixel matrices; PNG/JPEG uploads and arbitrary executable plugin callbacks are not part of the current format.
 
-The first manifest release focuses on palette-driven pixel worlds. Sprite assets, layered tile maps and declarative animation tracks are planned as compatible schema extensions rather than arbitrary executable plugin code.
 
 ## Configuration
 
@@ -271,35 +260,27 @@ For iOS, use `npm run mobile:ios:init` once and `npm run mobile:ios` for later s
 ```text
 pixel-daylight-switch/
 ├── .github/workflows/       # CI, native mobile builds, npm publishing
-├── assets/
-│   └── scene-gallery.png    # Five-scene overview image
-├── builds/
-│   └── README.md            # Mobile artifact notes; binaries are workflow outputs
-├── mobile/
-│   ├── index.html            # Capacitor app entry
-│   └── mobile.css            # Mobile-only layout
-├── scripts/
-│   └── prepare-mobile.cjs   # Prepare the shared web runtime for Capacitor
-├── tests/
-│   ├── browser/              # Playwright interaction and mobile regressions
-│   ├── fixture.html
-│   ├── mobile-smoke.cjs
-│   ├── package-smoke.cjs
-│   └── server.cjs
-├── app.js                    # Component runtime, scenes, input and rendering
-├── style.css                 # Component styles
-├── embed.js                  # One-script website embed loader
-├── index.html                # Live demo page
-├── preview.html              # Component preview
-├── playground.html            # Interactive parameter lab
-├── index.mjs / index.cjs     # ESM and CommonJS package entry points
-├── package.json               # Package metadata and scripts
-├── capacitor.config.json     # Capacitor configuration
-├── playwright.config.cjs     # Browser test configuration
-├── CHANGELOG.md
-├── llms.txt
+├── assets/                  # Gallery artwork
+├── builds/                  # Mobile build notes
+├── docs/                    # Integration guides, scene guide, changelog
+├── examples/scenes/         # Community scene manifests
+├── mobile/                  # Capacitor app shell
+├── schemas/                 # Manifest v1 and v2 JSON Schemas
+├── scripts/                 # Mobile preparation/version scripts
+├── tests/                   # Node and Chromium regression tests
+├── app.js / style.css       # Runtime and component styles
+├── scene-plugin.js          # Community scene registry and validator
+├── embed.js                 # One-script website embed loader
+├── index.html               # Live demo
+├── demos/                   # Public parameter lab and preview pages
+├── config/                  # Tooling configuration
+├── index.mjs / index.cjs    # ESM and CommonJS package entry points
+├── package.json             # Package metadata and scripts
+├── capacitor.config.json    # Capacitor configuration
+├── playwright.config.cjs    # Browser test configuration
+├── llms.txt                 # AI-readable project guide
 ├── LICENSE
-└── README*.md                 # English, Simplified Chinese and Japanese docs
+└── README*.md               # English, Simplified Chinese and Japanese
 ```
 
 ## License

package/README.zh-CN.md

@@ -12,22 +12,22 @@
 
 Pixel Daylight Switch 是一个可拖动的昼夜切换 UI 组件。拖动玻璃开关，可以让内部的像素世界从白天经过黄昏切换到夜晚。项目使用原生 JavaScript、WebGL2 和 Canvas 2D 回退渲染，不依赖第三方运行时库。
 
-**[直接体验在线演示](https://gsvegetable.github.io/pixel-daylight-switch/)** · **[打开参数实验室](https://gsvegetable.github.io/pixel-daylight-switch/playground.html)** · **[npm 安装](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable)**
+**[直接体验在线演示](https://gsvegetable.github.io/pixel-daylight-switch/)** · **[打开参数实验室](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html)** · **[npm 安装](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable)**
 
 ## 快速入口
 
 | 你想做什么 | 直接打开 |
 | --- | --- |
 | 体验昼夜开关 | [在线演示](https://gsvegetable.github.io/pixel-daylight-switch/) |
-| 调整场景与视觉参数 | [交互式参数实验室](https://gsvegetable.github.io/pixel-daylight-switch/playground.html) |
-| 查看组件预览 | [Preview 页面](https://gsvegetable.github.io/pixel-daylight-switch/preview.html) |
+| 调整场景与视觉参数 | [交互式参数实验室](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html) |
+| 查看组件预览 | [Preview 页面](https://gsvegetable.github.io/pixel-daylight-switch/demos/preview.html) |
 | 用一个脚本嵌入网站 | [嵌入加载器源码](embed.js) |
 | 在 JavaScript 项目中使用 | [npm 包](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable) |
-| React / Vue 接入示例 | [框架集成指南](INTEGRATIONS.md) |
+| React / Vue 接入示例 | [框架集成指南](docs/INTEGRATIONS.md) |\n| 独立玻璃折射引擎 | [引擎文档](docs/GLASS_ENGINE.md) · [在线演示](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html) |
 | 阅读核心实现 | [运行时 app.js](app.js) · [样式 style.css](style.css) |
 | 获取移动端构建 | [构建说明与限制](builds/README.md) · [GitHub Actions 构建任务](https://github.com/GSvegetable/pixel-daylight-switch/actions/workflows/mobile-build.yml) |
 | 查看自动化测试 | [CI 工作流](https://github.com/GSvegetable/pixel-daylight-switch/actions/workflows/ci.yml) |
-| 查看版本变化 | [更新日志](CHANGELOG.md) |
+| 查看版本变化 | [更新日志](docs/CHANGELOG.md) |
 | 反馈问题 | [GitHub Issues](https://github.com/GSvegetable/pixel-daylight-switch/issues) |
 
 ## 功能特点
@@ -96,50 +96,61 @@ const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable');
 
 npm 包提供 ESM 和 CommonJS 入口，可在 SSR 环境中安全导入；只有在浏览器中且目标元素已经存在时，才能调用 `mount()`。npm 发布文件清单以 [package.json](package.json) 为准。
 
-## 社区场景插件（v3.0.0）
 
-3.0.0 开始支持通过 JSON Manifest 注册自定义像素世界。普通创作者可以保留像素矩阵、只修改昼夜色板；进阶创作者可以自己设计像素矩阵和时间色板。插件只提供声明式数据，不会在渲染器中执行第三方 JavaScript。
+## 独立玻璃折射引擎（v3.1.1）
 
-**浏览器使用：**
+这次升级把玻璃镜片从昼夜开关中独立出来。现在可以单独创建一层玻璃，不再受原开关的固定宽高比和尺寸限制；可分别设置宽度、高度、位置、圆角、折射、色散、边缘厚度和高光。支持 Canvas、图片、视频、ImageBitmap 或返回这些对象的函数作为背景源。查看[完整接入文档](docs/GLASS_ENGINE.md)和[在线调参演示](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html)。
 
-```html
-<script src="https://gsvegetable.github.io/pixel-daylight-switch/scene-plugin.js"></script>
-<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);
-</script>
+```js
+import { createGlass } from 'pixel-daylight-switch-gsvegetable/glass-engine';
+const glass = createGlass(container, { source: backgroundCanvas, width: '72%', height: 180, radius: 28 });
+glass.setOptions({ refraction: 1.3, dispersion: 0.08 });
+glass.destroy();
 ```
 
-请在组件挂载前注册 Manifest。使用 npm 时：
+注意：浏览器不允许 WebGL 直接读取任意网页 DOM 像素。若要折射实时网页背景，宿主应用必须提供可采样的 Canvas / 渲染目标；跨域媒体还必须满足 CORS 要求。
+
+## 社区场景
+
+社区场景使用声明式 JSON Manifest，在组件挂载前注册。当前采用 **Manifest v2**，支持可复用像素素材、顺序图层和受限动画轨道，同时继续兼容已有的 Manifest v1 场景。
+
+### 注册场景
+
+在 npm 项目中：
 
 ```js
 import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
-import myScene from './my-scene.json';
+import scene from './floating-island.v2.json';
 
-const unregister = registerScene(myScene);
+const unregister = registerScene(scene);
 const root = document.querySelector('[data-ld-part="toggle-daylight"]');
-root.dataset.scene = myScene.id;
+root.dataset.scene = scene.id;
 PixelDaylightSwitch.mount(root);
 ```
 
-Manifest v1 包含场景 ID、作者与许可证、像素画布、字符像素矩阵、多个昼夜色板和 24 小时时间节点。画布最大为 192 × 112；每个像素符号都必须在每套色板中定义颜色。渲染器会在相邻时间节点之间插值颜色。
+直接在浏览器中使用时，先加载 `scene-plugin.js`，再加载 `app.js`，并在挂载组件前注册 Manifest：
 
-- [完整插件开发指南](SCENE_PLUGINS.md)
-- [Manifest v1 JSON Schema](schemas/scene-manifest.v1.schema.json)
-- [樱花黄昏示例](examples/scenes/sakura-evening.json)
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/scene-plugin.js"></script>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
+<div data-ld-part="toggle-daylight" data-scene="my-community-scene"></div>
+<script>
+  PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
+</script>
+```
 
-### Manifest v2：分层像素世界（v3.0.1）
+### Manifest v2 能力
 
-3.0.1 在不改变 Manifest v1 的前提下增加了 v2。v2 支持最多 24 个可复用像素素材、最多 16 个按顺序合成的图层。图层可以指定场景坐标，并使用 drift 或 bob 声明式运动轨道沿水平或垂直方向移动。叠加素材中的点号 . 表示透明，其余字符由昼夜色板统一着色。
+- 最多 24 个可复用字符像素素材、最多 16 个顺序合成图层。
+- 图层使用整数场景坐标，后声明的图层显示在前面图层之上。
+- 叠加素材中的点号 `.` 表示透明像素。
+- 支持 `drift`（往返漂移）和 `bob`（正弦浮动）两种受限动画轨道，可沿水平或垂直方向运行。
+- 继续兼容已有 v1 Manifest，原有五个内置场景保持不变。
 
-- [Manifest v2 JSON Schema](schemas/scene-manifest.v2.schema.json)
-- [Floating Island 分层场景示例](examples/scenes/floating-island.v2.json)
-- [完整场景插件开发指南](SCENE_PLUGINS.md)
+查看 [Manifest v2 Schema](schemas/scene-manifest.v2.schema.json)、[Floating Island 分层场景示例](examples/scenes/floating-island.v2.json) 和[场景创作指南](docs/SCENE_PLUGINS.md)。为保证兼容性，原始 [v1 Schema](schemas/scene-manifest.v1.schema.json) 仍然保留。
 
-当前 v2 素材采用原生字符像素矩阵，而不是远程 PNG/JPEG 图片；这样可以保持像素边缘清晰、昼夜调色一致，也不需要额外的跨域图片加载或执行第三方代码。
+当前素材采用字符像素矩阵，不支持 PNG/JPEG 上传，也不会执行社区提交的任意脚本。
 
-五个内置场景仍保留原有绘制与动态逻辑。
 
 ## 配置参数
 
@@ -248,35 +259,27 @@ iOS 首次创建使用 `npm run mobile:ios:init`，后续使用 `npm run mobile:
 ```text
 pixel-daylight-switch/
 ├── .github/workflows/       # CI、原生移动端构建、npm 发布
-├── assets/
-│   └── scene-gallery.png    # 五种场景总览图
-├── builds/
-│   └── README.md            # 移动端产物说明；二进制由工作流生成
-├── mobile/
-│   ├── index.html            # Capacitor 应用入口
-│   └── mobile.css            # 移动端专用布局
-├── scripts/
-│   └── prepare-mobile.cjs   # 为 Capacitor 准备共用 Web 运行时
-├── tests/
-│   ├── browser/              # Playwright 交互与移动端回归
-│   ├── fixture.html
-│   ├── mobile-smoke.cjs
-│   ├── package-smoke.cjs
-│   └── server.cjs
-├── app.js                    # 组件运行时、场景、交互与渲染
-├── style.css                 # 组件样式
-├── embed.js                  # 单脚本网站嵌入加载器
-├── index.html                # 在线演示主页
-├── preview.html              # 组件预览
-├── playground.html            # 交互式参数实验室
-├── index.mjs / index.cjs     # ESM 与 CommonJS 包入口
-├── package.json               # npm 元数据与脚本
-├── capacitor.config.json     # Capacitor 配置
-├── playwright.config.cjs     # 浏览器测试配置
-├── CHANGELOG.md
-├── llms.txt
+├── assets/                  # 场景展示图片
+├── builds/                  # 移动端构建说明
+├── docs/                    # 集成指南、场景创作指南、更新日志
+├── examples/scenes/         # 社区场景 Manifest 示例
+├── mobile/                  # Capacitor 应用外壳
+├── schemas/                 # Manifest v1 / v2 JSON Schema
+├── scripts/                 # 移动端准备与版本脚本
+├── tests/                   # Node 与 Chromium 回归测试
+├── app.js / style.css       # 运行时与组件样式
+├── scene-plugin.js          # 场景注册与校验 API
+├── embed.js                 # 网站单脚本嵌入加载器
+├── index.html               # 在线演示
+├── demos/                   # 参数实验室与组件预览页面
+├── config/                  # 工具配置
+├── index.mjs / index.cjs    # ESM / CommonJS 入口
+├── package.json             # 包元数据与脚本
+├── capacitor.config.json    # Capacitor 配置
+├── playwright.config.cjs    # 浏览器测试配置
+├── llms.txt                 # 面向 AI 的项目说明
 ├── LICENSE
-└── README*.md                 # 英文、简体中文、日文文档
+└── README*.md               # 英文、简体中文和日文 README
 ```
 
 ## 许可证

package/browser.mjs

@@ -1,3 +1,4 @@
+import './glass-engine.js';
 import './scene-plugin.js';
 
 // Browser ESM consumers need to register their scene before mounting.
@@ -10,6 +11,7 @@ try {
 }
 
 const api = globalThis.PixelDaylightSwitch;
+api.createGlass = globalThis.PixelGlassEngine.createGlass;
 const scenes = globalThis.PixelDaylightSwitchScenePlugins;
 export const mount = api.mount;
 export const unmount = api.unmount;
@@ -18,3 +20,5 @@ export const validateScene = scenes.validateScene;
 export const getScene = scenes.getScene;
 export const listScenes = scenes.listScenes;
 export default api;
+
+export const createGlass = globalThis.PixelGlassEngine.createGlass;

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 introduced 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>
 ```
 
@@ -60,7 +60,7 @@ 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)
 
@@ -74,7 +74,7 @@ A v2 manifest keeps the base `canvas`, `pixels`, `palettes` and `timeCycle`, and
 
 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).
+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.
 

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;

package/index.d.ts

@@ -54,6 +54,7 @@ export interface PixelDaylightSwitchAPI {
   validateScene(manifest: unknown): SceneValidationResult;
   getScene(id: string): SceneManifest | null;
   listScenes(): SceneManifest[];
+  createGlass: typeof createGlass;
 }
 declare const PixelDaylightSwitch: PixelDaylightSwitchAPI;
 export declare const mount: PixelDaylightSwitchAPI['mount'];
@@ -63,3 +64,22 @@ export declare const validateScene: PixelDaylightSwitchAPI['validateScene'];
 export declare const getScene: PixelDaylightSwitchAPI['getScene'];
 export declare const listScenes: PixelDaylightSwitchAPI['listScenes'];
 export default PixelDaylightSwitch;
+
+export type GlassSource = HTMLCanvasElement | OffscreenCanvas | HTMLImageElement | HTMLVideoElement | ImageBitmap | (() => GlassSource);
+export interface GlassEngineOptions {
+  source?: GlassSource;
+  width?: number | string; height?: number | string;
+  left?: number | string; top?: number | string;
+  radius?: number | string; refraction?: number; dispersion?: number;
+  bezel?: number; shine?: number; opacity?: number; edgeDark?: number;
+  ink?: [number, number, number]; light?: [number, number, number];\n  shellDay?: [number, number, number]; shellNight?: [number, number, number];\n  hiNight?: [number, number, number]; loNight?: [number, number, number]; night?: number;
+  dpr?: number; continuous?: boolean;
+}
+export interface GlassEngineInstance {
+  canvas: HTMLCanvasElement;
+  setSource(source: GlassSource): this;
+  setOptions(options: Partial<GlassEngineOptions>): this;
+  render(): this;
+  destroy(): void;
+}
+export declare function createGlass(container: HTMLElement, options?: GlassEngineOptions): GlassEngineInstance;

package/index.mjs

@@ -1,4 +1,5 @@
 import api from './index.cjs';
+import { createGlass } from './glass-engine.mjs';
 
 export const mount = api.mount;
 export const unmount = api.unmount;
@@ -6,4 +7,5 @@ export const registerScene = api.registerScene;
 export const validateScene = api.validateScene;
 export const getScene = api.getScene;
 export const listScenes = api.listScenes;
+export { createGlass };
 export default api;

package/llms.txt

@@ -42,11 +42,17 @@ CommonJS: `const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetabl
 
 The package is safe to import during SSR; mount only after the target DOM element exists. `mount(element)` is idempotent and returns a cleanup function on success (or null on failure). `unmount(element)` stops rendering and removes observers/listeners; it does not remove the DOM root or forcibly invalidate the canvas context.
 
-Framework lifecycle examples are in [INTEGRATIONS.md](INTEGRATIONS.md). Scene plugin authoring, manifest constraints and API examples are in [SCENE_PLUGINS.md](SCENE_PLUGINS.md).
+Framework lifecycle examples are in [INTEGRATIONS.md](docs/INTEGRATIONS.md). Scene plugin authoring, manifest constraints and API examples are in [SCENE_PLUGINS.md](docs/SCENE_PLUGINS.md).
 
-## Community scene plugins (v3.0.0)
+## Standalone refractive glass engine (v3.1.1)
 
-The optional `scene-plugin.js` registry exposes `registerScene(manifest)`, `validateScene(manifest)`, `getScene(id)` and `listScenes()`. Load the registry before `app.js` in a browser, or import `registerScene` from the npm package. Register a scene before mounting its root. Manifest v1 uses a 1–192 by 1–112 printable-ASCII pixel map, up to 8 named palettes, and a 24-hour timeline that starts at 0 and ends at 24. Every used pixel symbol must have a valid `#RGB` or `#RRGGBB` color in every palette. Data is copied and deeply frozen on registration. Arbitrary plugin JavaScript is never executed. External image/sprite assets, layered tile maps and custom animation tracks are not supported in v1; they are reserved for a future schema extension. See [SCENE_PLUGINS.md](SCENE_PLUGINS.md), the [v1 JSON Schema](schemas/scene-manifest.v1.schema.json), and the [Sakura example](examples/scenes/sakura-evening.json).
+Import `createGlass` from `pixel-daylight-switch-gsvegetable/glass-engine`, or load `glass-engine.js` directly and use `PixelGlassEngine.createGlass(container, options)`. The independent WebGL2 overlay has configurable width, height, position, radius, refraction, dispersion, bezel, shine, opacity, source and lifecycle methods. Sources are origin-clean canvas, image, video, ImageBitmap or a callback returning one. WebGL cannot sample arbitrary DOM pixels; host applications must supply a renderable background source. See [GLASS_ENGINE.md](docs/GLASS_ENGINE.md) and [the demo](https://gsvegetable.github.io/pixel-daylight-switch/demos/glass-engine.html).
+
+## Community scene plugins (current: Manifest v2)
+
+The optional `scene-plugin.js` registry exposes `registerScene(manifest)`, `validateScene(manifest)`, `getScene(id)` and `listScenes()`. Register a data-only JSON manifest before mounting the scene. Manifest v2 supports up to 24 reusable pixel-matrix assets, up to 16 ordered layers, transparent overlay pixels (.), and bounded deterministic drift/bob motion tracks. Manifest v1 remains supported and its schema is unchanged. Every symbol in the base matrix and assets must be defined in each palette. Registration validates, copies and freezes the data; arbitrary JavaScript, remote image downloads and executable callbacks are not run.
+
+For npm, import `registerScene` from the package. In a browser, load `scene-plugin.js` before `app.js` and register the manifest before mounting. See [the scene authoring guide](docs/SCENE_PLUGINS.md), [Manifest v2 Schema](schemas/scene-manifest.v2.schema.json), [v1 compatibility schema](schemas/scene-manifest.v1.schema.json) and [Floating Island v2 example](examples/scenes/floating-island.v2.json).
 
 ## Scenes and weather
 
@@ -93,30 +99,19 @@ Invalid values fall back to defaults; documented numeric ranges are clamped.
 ## Links
 
 - [Live demo](https://gsvegetable.github.io/pixel-daylight-switch/)
-- [Interactive Playground](https://gsvegetable.github.io/pixel-daylight-switch/playground.html)
-- [Preview](https://gsvegetable.github.io/pixel-daylight-switch/preview.html)
-- [Integration recipes](INTEGRATIONS.md)
+- [Interactive Playground](https://gsvegetable.github.io/pixel-daylight-switch/demos/playground.html)
+- [Preview](https://gsvegetable.github.io/pixel-daylight-switch/demos/preview.html)
+- [Integration recipes](docs/INTEGRATIONS.md)
 - [English README](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
-- [Changelog](CHANGELOG.md)
-
-
-## Scene plugins (v3.0.0)
-
-- Public API: registerScene(manifest), validateScene(manifest), getScene(id), listScenes().
-- Manifest schema: schemas/scene-manifest.v1.schema.json.
-- Example: examples/scenes/sakura-evening.json.
-- Manifest v1: printable-ASCII pixel matrix (up to 192x112), named palettes, 24-hour palette interpolation.
-- Scene registration is data-only; arbitrary plugin JavaScript is not executed.
-- Browser script order: scene-plugin.js, register the manifest, then app.js. The one-line embed loader loads the registry before the renderer.
-- Existing built-in scenes and their custom live animation code remain unchanged.
+- [Changelog](docs/CHANGELOG.md)
 
 
-## Scene Manifest v2 (v3.0.1)
+## Scene plugins — current Manifest v2
 
-- Manifest v1 remains supported and its schema is unchanged.
-- Manifest v2 adds up to 24 reusable pixel-matrix assets and up to 16 ordered layers.
-- Layers reference named assets and integer x/y positions; '.' is transparent in overlay assets.
-- Optional deterministic motion tracks: drift or bob, on x or y, bounded speed/distance/phase.
-- Every symbol across the base matrix and assets must be defined in every palette.
-- Schema: schemas/scene-manifest.v2.schema.json. Example: examples/scenes/floating-island.v2.json.
+- Current schema: `schemas/scene-manifest.v2.schema.json`.
+- Example: `examples/scenes/floating-island.v2.json`.
+- Reusable assets: up to 24 pixel matrices; ordered layers: up to 16.
+- Overlay dot (.) is transparent; later layers appear above earlier layers.
+- Motion tracks: bounded deterministic `drift` and `bob`, on x or y.
+- Manifest v1 remains backward compatible; its schema is retained.
 - No arbitrary remote image loading, eval, or executable plugin callbacks.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-daylight-switch-gsvegetable",
-  "version": "3.0.1",
-  "description": "A draggable pixel-art day/night switch with layered, animated community scenes.",
+  "version": "3.1.1",
+  "description": "A pixel-art day/night switch plus a standalone reusable WebGL2 refractive glass engine.",
   "keywords": [
     "pixel-art",
     "day-night",
@@ -17,7 +17,11 @@
     "scene-plugin",
     "pixel-world",
     "scene-manifest",
-    "pixel-art-scenes"
+    "pixel-art-scenes",
+    "refractive-glass",
+    "glass-engine",
+    "webgl2-glass",
+    "lens-shader"
   ],
   "author": "GSvegetable",
   "license": "Unlicense",
@@ -44,6 +48,11 @@
     "./scene-plugin": {
       "import": "./scene-plugin.js",
       "require": "./scene-plugin.js"
+    },
+    "./glass-engine": {
+      "types": "./index.d.ts",
+      "import": "./glass-engine.mjs",
+      "require": "./glass-engine.js"
     }
   },
   "files": [
@@ -53,13 +62,17 @@
     "README.md",
     "LICENSE",
     "llms.txt",
-    "INTEGRATIONS.md",
-    "SCENE_PLUGINS.md",
+    "docs/INTEGRATIONS.md",
+    "docs/SCENE_PLUGINS.md",
     "scene-plugin.js",
     "schemas",
     "examples",
     "browser.mjs",
-    "index.d.ts"
+    "index.d.ts",
+    "docs/CHANGELOG.md",
+    "glass-engine.js",
+    "docs/GLASS_ENGINE.md",
+    "glass-engine.mjs"
   ],
   "sideEffects": [
     "./app.js"
@@ -71,8 +84,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node tests/package-smoke.cjs && node tests/scene-plugin-smoke.cjs && node tests/mobile-smoke.cjs && node tests/embed-smoke.cjs",
-    "test:browser": "playwright test",
+    "test": "node tests/package-smoke.cjs && node tests/scene-plugin-smoke.cjs && node tests/mobile-smoke.cjs && node tests/embed-smoke.cjs && node tests/glass-engine-smoke.cjs",
+    "test:browser": "playwright test --config config/playwright.config.cjs",
     "mobile:prepare": "node scripts/prepare-mobile.cjs",
     "mobile:android": "npm run mobile:prepare && cap sync android && node scripts/set-android-version.cjs android/app/build.gradle",
     "mobile:ios": "npm run mobile:prepare && cap sync ios",