pixel-daylight-switch-gsvegetable 3.0.0 → 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,40 +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 を登録します。
+
+```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 の機能
+
+- 最大 24 個の再利用可能な文字ベースのピクセル素材と、最大 16 個の順序付きレイヤー。
+- 整数のシーン座標を使用し、後のレイヤーほど手前に合成されます。
+- オーバーレイ素材のドット文字 `.` は透明ピクセルとして扱われます。
+- `drift` と `bob` の決定論的なモーショントラックに対応し、X/Y 軸上で動作します。
+- 既存の Manifest v1 と 5 つの組み込みシーンは引き続きサポートされます。
+
+[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) も維持されています。
 
-- [プラグイン開発ガイド](SCENE_PLUGINS.md)
-- [Manifest v1 JSON Schema](schemas/scene-manifest.v1.schema.json)
-- [Sakura Evening サンプル](examples/scenes/sakura-evening.json)
+現在の素材形式は文字ベースのピクセルマトリックスです。PNG/JPEG のアップロードや任意の実行コードには対応していません。
 
-v1 は外部画像/Sprite、レイヤー式 Tile Map、独自アニメーショントラックにはまだ対応していません。これらは任意コードの実行を許可せず、将来の独立した Schema 拡張として追加します。5 つの組み込みシーンは従来の描画・アニメーション実装を維持します。
 
 ## 設定属性
 
@@ -238,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,52 +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:
+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).
 
-```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>
+```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();
 ```
 
-Register a manifest before mounting the component:
+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
-const unregister = PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
-PixelDaylightSwitch.mount(document.querySelector('[data-ld-part="toggle-daylight"]'));
-```
+## Community scenes
 
-With npm:
+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.
+
+### Register a scene
+
+For npm projects:
 
 ```js
 import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
-import sakura from './sakura-evening.json';
+import scene from './floating-island.v2.json';
+
+const unregister = registerScene(scene);
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+root.dataset.scene = scene.id;
+PixelDaylightSwitch.mount(root);
+```
 
-registerScene(sakura);
-PixelDaylightSwitch.mount(document.querySelector('[data-ld-part="toggle-daylight"]'));
+For direct browser usage, load `scene-plugin.js` before `app.js`, then register the manifest before mounting:
+
+```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
 
@@ -251,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,40 +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：
+
+```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 能力
+
+- 最多 24 个可复用字符像素素材、最多 16 个顺序合成图层。
+- 图层使用整数场景坐标，后声明的图层显示在前面图层之上。
+- 叠加素材中的点号 `.` 表示透明像素。
+- 支持 `drift`（往返漂移）和 `bob`（正弦浮动）两种受限动画轨道，可沿水平或垂直方向运行。
+- 继续兼容已有 v1 Manifest，原有五个内置场景保持不变。
+
+查看 [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) 仍然保留。
 
-- [完整插件开发指南](SCENE_PLUGINS.md)
-- [Manifest v1 JSON Schema](schemas/scene-manifest.v1.schema.json)
-- [樱花黄昏示例](examples/scenes/sakura-evening.json)
+当前素材采用字符像素矩阵，不支持 PNG/JPEG 上传，也不会执行社区提交的任意脚本。
 
-v1 暂不支持外部图片/Sprite、分层 Tile Map 和自定义动画轨道；这些能力会通过后续独立版本的 Schema 扩展，不会开放任意代码执行。五个内置场景仍保留原有绘制与动态逻辑。
 
 ## 配置参数
 
@@ -238,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/app.js

@@ -931,6 +931,7 @@ function mount(root) {
     Object.keys(palette).forEach((symbol) => { colors[symbol.charCodeAt(0)] = parsePluginColor(palette[symbol]); });
     return [name, colors];
   })) : null;
+  let pluginAnimClock = 0;
   const renderPluginWorld = (hour) => {
     const stops = pluginScene.timeCycle;
     let left = stops[0]; let right = stops[stops.length - 1]; let sampleHour = hour;
@@ -945,14 +946,43 @@ function mount(root) {
     const aPalette = pluginPaletteRgb[left.palette];
     const bPalette = pluginPaletteRgb[right.palette];
     const width = pluginScene.canvas.width; const height = pluginScene.canvas.height;
+    let scenePixels = pluginScene.pixels;
+    if (pluginScene.schemaVersion === 2 && Array.isArray(pluginScene.layers)) {
+      const composed = pluginScene.pixels.map(row => row.split(''));
+      for (const layer of pluginScene.layers) {
+        const asset = pluginScene.assets[layer.asset];
+        const motion = layer.animation;
+        let dx = 0, dy = 0;
+        if (motion) {
+          const phase = pluginAnimClock * motion.speed + (motion.phase || 0);
+          const wave = motion.type === 'drift' ? (2 / Math.PI) * Math.asin(Math.sin(phase)) : Math.sin(phase);
+          const offset = wave * motion.distance;
+          if (motion.axis === 'x') dx = Math.round(offset);
+          else dy = Math.round(offset);
+        }
+        const originX = layer.x + dx, originY = layer.y + dy;
+        for (let sy = 0; sy < asset.height; sy++) {
+          const targetY = originY + sy;
+          if (targetY < 0 || targetY >= height) continue;
+          const row = asset.pixels[sy];
+          for (let sx = 0; sx < asset.width; sx++) {
+            const targetX = originX + sx;
+            if (targetX < 0 || targetX >= width) continue;
+            const symbol = row[sx];
+            if (symbol !== '.') composed[targetY][targetX] = symbol;
+          }
+        }
+      }
+      scenePixels = composed.map(row => row.join(''));
+    }
     const scale = Math.min(bw / width, bh / height);
     const drawW = Math.max(1, Math.round(width * scale)); const drawH = Math.max(1, Math.round(height * scale));
     const offsetX = Math.floor((bw - drawW) / 2); const offsetY = Math.floor((bh - drawH) / 2);
-    const background = pluginScene.pixels[0].charCodeAt(0);
+    const background = scenePixels[0].charCodeAt(0);
     for (let py = 0; py < bh; py++) {
       const insideY = py >= offsetY && py < offsetY + drawH;
       const sy = insideY ? clamp(Math.floor(((py - offsetY) / drawH) * height), 0, height - 1) : 0;
-      const row = pluginScene.pixels[sy];
+      const row = scenePixels[sy];
       for (let px = 0; px < bw; px++) {
         const inside = insideY && px >= offsetX && px < offsetX + drawW;
         const sx = inside ? clamp(Math.floor(((px - offsetX) / drawW) * width), 0, width - 1) : 0;
@@ -1083,7 +1113,7 @@ function mount(root) {
   const pickKeys = (h) => { for (let i = 0; i < KEYS.length - 1; i++) { if (h >= KEYS[i][0] && h < KEYS[i + 1][0]) { keyA = i; keyB = i + 1; keyP = clamp(((h - KEYS[i][0]) / (KEYS[i + 1][0] - KEYS[i][0]) - 0.32) / 0.36); return; } } keyA = 0; keyB = 1; keyP = 0; };
   const renderWorld = (clock, dt, hurry) => {
     const h = hourOf(clock);
-    if (pluginScene) { renderPluginWorld(h); return; }
+    if (pluginScene) { if (!calm) pluginAnimClock += dt; renderPluginWorld(h); return; }
     if (!calm) anim += dt; matBuf.set(baseBuf); varBuf.fill(0); emitList.length = 0;
     for (const c of sources) { c.w = 0; c.x = 0; c.y = 0; }
     lampFlick = calm ? 1 : 0.95 + 0.05 * Math.sin(anim * 13) * Math.sin(anim * 5.3);

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;