pixel-daylight-switch-gsvegetable 2.2.0 → 3.0.0

package/INTEGRATIONS.md

@@ -0,0 +1,139 @@
+# Framework integration recipes
+
+The core package has no React or Vue runtime dependency. Use the same HTML root and mount/unmount lifecycle from your framework. The component owns its internal canvas and interaction elements; your framework owns the surrounding container.
+
+## React
+
+Install the core package:
+
+```bash
+npm install pixel-daylight-switch-gsvegetable
+```
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { mount, unmount } from 'pixel-daylight-switch-gsvegetable';
+
+export function DaylightSwitch({ scene = 'countryside', weather = 'default' }) {
+  const rootRef = useRef(null);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return undefined;
+
+    mount(root);
+    return () => unmount(root);
+  }, [scene, weather]);
+
+  return (
+    <div style={{ width: 'min(100%, 800px)', marginInline: 'auto' }}>
+      <div
+        ref={rootRef}
+        data-ld-part="toggle-daylight"
+        data-scene={scene}
+        data-weather={weather}
+      />
+    </div>
+  );
+}
+```
+
+The effect cleans up the previous instance before applying changed scene or weather attributes, so the renderer always reads the latest configuration.
+
+## Vue 3
+
+```vue
+<script setup>
+import { onMounted, onBeforeUnmount, ref } from 'vue';
+import { mount, unmount } from 'pixel-daylight-switch-gsvegetable';
+
+const root = ref(null);
+onMounted(() => mount(root.value));
+onBeforeUnmount(() => {
+  if (root.value) unmount(root.value);
+});
+</script>
+
+<template>
+  <div class="daylight-switch-wrap">
+    <div
+      ref="root"
+      data-ld-part="toggle-daylight"
+      data-scene="japanese-street"
+      data-weather="default"
+    />
+  </div>
+</template>
+
+<style scoped>
+.daylight-switch-wrap {
+  width: min(100%, 800px);
+  margin-inline: auto;
+}
+</style>
+```
+
+## Plain HTML / CDN
+
+For one default switch with no build step, use the one-line embed:
+
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
+```
+
+Set supported options on the script tag when you want a particular scene or weather:
+
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js" data-scene="seaside" data-weather="snow" data-start-night="true"></script>
+```
+
+For custom configuration, place a root element where you want it and load the runtime:
+
+```html
+<div style="width:min(100%, 800px);margin-inline:auto">
+  <div
+    data-ld-part="toggle-daylight"
+    data-scene="seaside"
+    data-weather="snow"
+    data-start-night="true"
+  ></div>
+</div>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
+```
+
+The runtime injects component-scoped styles. Do not import `style.css` just to use the component; that file also contains styles for the repository's standalone demo page.
+
+## Community scene plugins
+
+Register a JSON scene manifest before mounting a root. The package entry point exports `registerScene`, `validateScene`, `getScene` and `listScenes` alongside `mount` and `unmount`.
+
+```js
+import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
+import scene from './my-scene.json';
+
+const unregister = registerScene(scene);
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+root.dataset.scene = scene.id;
+PixelDaylightSwitch.mount(root);
+
+// Before removing a dynamically registered scene:
+PixelDaylightSwitch.unmount(root);
+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.
+
+## Lifecycle and events
+
+- Call `mount(root)` after the root is attached to the DOM.
+- Call `unmount(root)` before the framework removes the root.
+- Mounting the same root repeatedly is safe; it is idempotent.
+- Listen for `daylight:change` on the root to synchronize application state. The event's `detail.night` property is a boolean.
+- The root must be allowed to measure its width. A width of `100%` inside a parent with a real layout width is the usual choice.
+- The component keeps its intrinsic 1.6439 aspect ratio and scales to the available width.
+
+## Configuration
+
+See [README.md](README.md) for the complete list of `data-*` attributes, CSS custom properties, rendering behavior and supported scene identifiers.

package/README.ja.md

@@ -23,6 +23,7 @@ Pixel Daylight Switch は、ドラッグ操作で昼・夕暮れ・夜を切り
 | コンポーネントを見る | [Preview](https://gsvegetable.github.io/pixel-daylight-switch/preview.html) |
 | Web サイトに埋め込む | [embed.js](embed.js) |
 | JavaScript プロジェクトで使う | [npm](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable) |
+| React / Vue の導入例 | [フレームワーク統合ガイド](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) |
@@ -61,7 +62,13 @@ HTML にマウント要素を配置し、ランタイムを読み込みます。
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-ローダーがコンテナ、スタイル、ランタイムを自動挿入します。現在は既定設定のインスタンスを 1 つ生成し、最大表示サイズを固定します。レイアウトや属性を細かく制御する場合は、上記のマウント要素方式を使用してください。
+script タグにシーンや天候を直接指定することもできます。
+
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js" data-scene="seaside" data-weather="snow" data-start-night="true"></script>
+```
+
+レスポンシブなインスタンスを 1 つ作成してランタイムを読み込みます。スタイルはコンポーネント内に限定され、ホストページの `body` や `main` などのグローバル要素を変更しません。script タグに `data-scene`、`data-weather`、`data-start-night` などを直接指定できます。複数インスタンスや配置の細かな制御には、上記のマウント方式を使用してください。
 
 ## npm からインストール
 
@@ -89,6 +96,41 @@ const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable');
 
 ESM と CommonJS の両方を提供します。SSR 環境でもインポートできますが、`mount()` はブラウザー上で対象要素が存在してから呼び出してください。
 
+## コミュニティシーンプラグイン（v3.0.0）
+
+3.0.0 では JSON Manifest によるカスタムピクセルワールドの登録に対応しました。初めての方はピクセルマップをそのまま使い、昼夜パレットの色だけを変更できます。上級者はピクセルマップと時間パレットを自由に設計できます。プラグインは宣言型データのみを受け取り、レンダラー内で第三者 JavaScript を実行しません。
+
+**ブラウザーで使用：**
+
+```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>
+```
+
+コンポーネントをマウントする前に Manifest を登録してください。npm の場合：
+
+```js
+import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
+import myScene from './my-scene.json';
+
+const unregister = registerScene(myScene);
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+root.dataset.scene = myScene.id;
+PixelDaylightSwitch.mount(root);
+```
+
+Manifest v1 はシーン ID、作者・ライセンス、ピクセルキャンバス、文字ベースのピクセルマップ、複数の昼夜パレット、24 時間のタイムラインで構成されます。キャンバスは最大 192 × 112 ピクセルです。すべてのピクセル記号に各パレットの色を定義する必要があります。時間ノード間の色はレンダラーが補間します。
+
+- [プラグイン開発ガイド](SCENE_PLUGINS.md)
+- [Manifest v1 JSON Schema](schemas/scene-manifest.v1.schema.json)
+- [Sakura Evening サンプル](examples/scenes/sakura-evening.json)
+
+v1 は外部画像/Sprite、レイヤー式 Tile Map、独自アニメーショントラックにはまだ対応していません。これらは任意コードの実行を許可せず、将来の独立した Schema 拡張として追加します。5 つの組み込みシーンは従来の描画・アニメーション実装を維持します。
+
 ## 設定属性
 
 すべて任意の設定で、マウント要素に指定します。省略時または無効な値の場合はデフォルト値が使われます。
@@ -176,7 +218,7 @@ Capacitor 8 アプリには、田園の家、日本の街並み、モダンな
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-スタイルとデフォルトシーンのスイッチを自動挿入します。シーンや天気のカスタマイズ、複数インスタンス、配置の制御には、上記の npm API と `data-scene` / `data-weather` 属性を使用してください。
+レスポンシブなデフォルトシーンのスイッチを自動作成してランタイムを読み込みます。デモページ用スタイルは挿入せず、サイトのグローバルスタイルも変更しません。シーンや天気のカスタマイズ、複数インスタンス、配置の制御には、上記の npm API と `data-scene` / `data-weather` 属性を使用してください。
 
 ### 独自の Android / iOS Capacitor アプリへの統合
 

package/README.md

@@ -23,6 +23,8 @@ Pixel Daylight Switch is a draggable day/night UI component. Move its glass cont
 | Inspect the component | [Preview page](https://gsvegetable.github.io/pixel-daylight-switch/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) |
 | 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) |
@@ -61,7 +63,13 @@ For a self-inserting embed, add this script where you want the component to appe
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-The loader inserts its own container, stylesheet and runtime. It currently creates one default instance with a fixed maximum display size; use the mount-point approach above when you need precise layout or custom attributes.
+Configure the generated instance directly on the script tag:
+
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js" data-scene="seaside" data-weather="snow" data-start-night="true"></script>
+```
+
+The loader inserts one responsive instance and loads only the component runtime. Its styles are isolated to the component and do not reset or modify your page's `body`, `main`, or other global elements. You can set `data-scene`, `data-weather`, `data-start-night` and the other documented `data-*` options directly on the script tag. For multiple instances or exact placement, use the mount-point approach above.
 
 ## Install from npm
 
@@ -89,6 +97,53 @@ 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.
+
+### 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:
+
+```js
+const unregister = PixelDaylightSwitchScenePlugins.registerScene(sceneManifest);
+PixelDaylightSwitch.mount(document.querySelector('[data-ld-part="toggle-daylight"]'));
+```
+
+With npm:
+
+```js
+import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
+import sakura from './sakura-evening.json';
+
+registerScene(sakura);
+PixelDaylightSwitch.mount(document.querySelector('[data-ld-part="toggle-daylight"]'));
+```
+
+### Manifest v1
+
+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.
+
+- 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 [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.
+
+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
 
 Set optional attributes on the mount element. Defaults apply when an attribute is omitted or invalid.
@@ -176,7 +231,7 @@ For one basic day/night switch, no package installation is required. Paste this
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-The loader injects its styles and one default-scene switch. For custom scenes, weather, multiple instances or full control over placement, use the npm API above and its `data-scene` / `data-weather` attributes.
+The loader creates a responsive default-scene switch and loads the runtime. It does not inject the demo page stylesheet or alter your site's global styles. For custom scenes, weather, multiple instances or full control over placement, use the npm API above and its `data-scene` / `data-weather` attributes.
 
 ### Integrate with your own Android / iOS Capacitor app
 

package/README.zh-CN.md

@@ -23,6 +23,7 @@ Pixel Daylight Switch 是一个可拖动的昼夜切换 UI 组件。拖动玻璃
 | 查看组件预览 | [Preview 页面](https://gsvegetable.github.io/pixel-daylight-switch/preview.html) |
 | 用一个脚本嵌入网站 | [嵌入加载器源码](embed.js) |
 | 在 JavaScript 项目中使用 | [npm 包](https://www.npmjs.com/package/pixel-daylight-switch-gsvegetable) |
+| React / Vue 接入示例 | [框架集成指南](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) |
@@ -61,7 +62,13 @@ Pixel Daylight Switch 是一个可拖动的昼夜切换 UI 组件。拖动玻璃
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-加载器会自动插入容器、样式和运行脚本。目前它创建一个默认实例，并使用固定的最大展示尺寸；如果需要精确控制布局或配置属性，请使用上面的挂载节点方式。
+也可以直接在 script 标签上配置场景和天气：
+
+```html
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js" data-scene="seaside" data-weather="snow" data-start-night="true"></script>
+```
+
+加载器会自动创建响应式实例并加载运行时。组件样式仅作用于组件本身，不会重置或修改宿主网页的 `body`、`main` 等全局元素。你也可以直接在 script 标签上设置 `data-scene`、`data-weather`、`data-start-night` 等参数。若要创建多个实例或精确控制位置，请使用上面的挂载节点方式。
 
 ## 通过 npm 安装
 
@@ -89,6 +96,41 @@ 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。
+
+**浏览器使用：**
+
+```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>
+```
+
+请在组件挂载前注册 Manifest。使用 npm 时：
+
+```js
+import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
+import myScene from './my-scene.json';
+
+const unregister = registerScene(myScene);
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+root.dataset.scene = myScene.id;
+PixelDaylightSwitch.mount(root);
+```
+
+Manifest v1 包含场景 ID、作者与许可证、像素画布、字符像素矩阵、多个昼夜色板和 24 小时时间节点。画布最大为 192 × 112；每个像素符号都必须在每套色板中定义颜色。渲染器会在相邻时间节点之间插值颜色。
+
+- [完整插件开发指南](SCENE_PLUGINS.md)
+- [Manifest v1 JSON Schema](schemas/scene-manifest.v1.schema.json)
+- [樱花黄昏示例](examples/scenes/sakura-evening.json)
+
+v1 暂不支持外部图片/Sprite、分层 Tile Map 和自定义动画轨道；这些能力会通过后续独立版本的 Schema 扩展，不会开放任意代码执行。五个内置场景仍保留原有绘制与动态逻辑。
+
 ## 配置参数
 
 所有参数均为可选项，写在挂载元素上。省略参数或参数值无效时使用默认值。
@@ -176,7 +218,7 @@ Capacitor 移动端现已提供完整的场景控制界面：可在乡间小屋
 <script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-这是一键式基础嵌入，当前展示单个默认场景开关；如果需要自定义场景、天气或多个实例，请使用上面的 npm API（`data-scene`、`data-weather` 等参数）。
+这是一键式基础嵌入，会创建响应式的默认场景开关；不会注入演示页面样式，也不会修改网站全局样式。如果需要自定义场景、天气或多个实例，请使用上面的 npm API（`data-scene`、`data-weather` 等参数）。
 
 ### 集成到自己的 Android / iOS Capacitor 工程
 

package/SCENE_PLUGINS.md

@@ -0,0 +1,78 @@
+# Scene Plugin Guide
+
+Pixel Daylight Switch 3.0.0 introduces a declarative community-scene format. A scene is JSON data, not an executable JavaScript plugin. The renderer validates the manifest and draws the resulting pixel world through the existing refractive-glass pipeline.
+
+## 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.
+
+**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.
+
+## Register with npm
+
+```bash
+npm install pixel-daylight-switch-gsvegetable
+```
+
+```js
+import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
+import myScene from './my-scene.json';
+
+const unregister = registerScene(myScene);
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+root.dataset.scene = myScene.id;
+PixelDaylightSwitch.mount(root);
+
+// Call when this scene is no longer needed:
+unregister();
+```
+
+The scene must be registered before its root is mounted. Registering a scene returns an idempotent unregister function.
+
+## Register in a browser
+
+Load the registry before the renderer:
+
+```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>
+```
+
+If the runtime auto-mounts on `DOMContentLoaded`, register the manifest before that event. For deterministic ordering, load both scripts with `defer` and register from a later deferred script, or register before loading `app.js`.
+
+The one-line `embed.js` loader loads the registry before the renderer, but it does not fetch or execute arbitrary remote scene scripts. Register your manifest in your own page before the component mounts.
+
+## Manifest v1
+
+Required fields:
+
+- `schemaVersion`: currently `1`.
+- `id`: unique lowercase ID, 3–64 characters. Built-in scene IDs are reserved.
+- `name`, `author`, `license`: scene metadata.
+- `canvas`: width 1–192 and height 1–112.
+- `pixels`: one printable-ASCII string per row; every row must match the declared width.
+- `palettes`: one or more named maps from single characters to `#RGB` or `#RRGGBB`.
+- `timeCycle`: strictly increasing time stops, beginning at hour 0 and ending at hour 24. Each stop references a defined palette.
+
+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).
+
+## API
+
+- `registerScene(manifest)`: validate, snapshot and register a scene; returns an unregister function.
+- `validateScene(manifest)`: return `{ valid, errors }` without registering.
+- `getScene(id)`: return a registered, deeply frozen manifest or `null`.
+- `listScenes()`: return a new array of registered manifests.
+
+Registration rejects duplicate IDs, built-in IDs, malformed dimensions, invalid colors, missing palette symbols, unsupported manifest fields and invalid timelines. Registered manifests are copied and deeply frozen so later edits to the original object cannot silently alter a running scene.
+
+## Scope and safety
+
+Manifest v1 supports palette-driven pixel maps. It intentionally does not execute plugin JavaScript, evaluate expressions, or load arbitrary code. External image/sprite assets, layered tile maps and custom animation tracks are not part of v1; they should be introduced through a separately versioned schema extension with explicit asset limits and lifecycle rules.
+
+All five built-in scenes continue to use their original hand-authored painters and scene-specific live behavior. Community scenes use the data-driven renderer and do not replace or mutate built-in scene definitions.

package/app.js

@@ -915,12 +915,60 @@ function mount(root) {
     }
   };
 
-  const scene = ['countryside', 'japanese-street', 'apartment', 'seaside', 'mountain-cabin'].includes(dataset.scene) ? dataset.scene : 'countryside';
+  const scenePlugins = typeof window !== 'undefined' ? window.PixelDaylightSwitchScenePlugins : null;
+  const pluginScene = scenePlugins && typeof scenePlugins.getScene === 'function' ? scenePlugins.getScene(dataset.scene) : null;
+  const builtInScene = ['countryside', 'japanese-street', 'apartment', 'seaside', 'mountain-cabin'].includes(dataset.scene);
+  const scene = builtInScene ? dataset.scene : (pluginScene ? dataset.scene : 'countryside');
   const LIVE = { seaside: liveSeaside, 'mountain-cabin': liveCabin, 'japanese-street': liveStreet, apartment: liveApartment };
   const drawSceneLive = (h, dt) => { const fn = LIVE[scene]; if (fn) fn(h, dt); };
+  const parsePluginColor = (value) => {
+    const hex = value.slice(1);
+    const full = hex.length === 3 ? hex.split('').map((v) => v + v).join('') : hex;
+    return [parseInt(full.slice(0, 2), 16), parseInt(full.slice(2, 4), 16), parseInt(full.slice(4, 6), 16)];
+  };
+  const pluginPaletteRgb = pluginScene ? Object.fromEntries(Object.entries(pluginScene.palettes).map(([name, palette]) => {
+    const colors = new Array(128);
+    Object.keys(palette).forEach((symbol) => { colors[symbol.charCodeAt(0)] = parsePluginColor(palette[symbol]); });
+    return [name, colors];
+  })) : null;
+  const renderPluginWorld = (hour) => {
+    const stops = pluginScene.timeCycle;
+    let left = stops[0]; let right = stops[stops.length - 1]; let sampleHour = hour;
+    if (hour < stops[0].at) sampleHour += 24;
+    for (let i = 0; i < stops.length - 1; i++) {
+      const a = stops[i]; const b = stops[i + 1];
+      if (sampleHour >= a.at && sampleHour <= b.at) { left = a; right = b; break; }
+    }
+    if (sampleHour > stops[stops.length - 1].at) { left = stops[stops.length - 1]; right = stops[0]; right = { at: right.at + 24, palette: right.palette }; }
+    const span = Math.max(0.0001, right.at - left.at);
+    const t = clamp((sampleHour - left.at) / span);
+    const aPalette = pluginPaletteRgb[left.palette];
+    const bPalette = pluginPaletteRgb[right.palette];
+    const width = pluginScene.canvas.width; const height = pluginScene.canvas.height;
+    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);
+    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];
+      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;
+        const symbol = inside ? row.charCodeAt(sx) : background;
+        const ca = aPalette[symbol]; const cb = bPalette[symbol];
+        const r = Math.round(mix(ca[0], cb[0], t));
+        const g = Math.round(mix(ca[1], cb[1], t));
+        const b = Math.round(mix(ca[2], cb[2], t));
+        pixels[py * bw + px] = (255 << 24) | (b << 16) | (g << 8) | r;
+      }
+    }
+  };
 
 
   const buildBase = () => {
+    if (pluginScene) { matBuf.fill(0); baseBuf.set(matBuf); skyKeys = []; return; }
     matBuf.fill(0); if (scene === 'countryside') { paintGround(); paintFence(); paintBush(22, 78, 16, 8, 61); paintBush(176, 80, 14, 7, 62); paintBush(-6, 81, 11, 6, 63); paintBush(204, 81, 10, 5, 64); paintTrunk(); paintHouse(); paintFlowers(96, 126, 85, 92, 26, 91); paintFlowers(14, 38, 86, 96, 16, 92); paintFlowers(150, 205, 90, 106, 24, 93); paintFlowers(-14, 14, 88, 104, 12, 95); paintFlowers(40, 62, 90, 104, 12, 94); buildCanopy(); } else { canopy = []; if (scene === 'japanese-street') paintJapaneseStreet(); else if (scene === 'apartment') paintApartment(); else if (scene === 'seaside') paintSeaside(); else paintMountainCabin(); } baseBuf.set(matBuf);
     const r = seeded(808); stars = [];
     for (let i = 0; i < 95; i++) { stars.push({ x: Math.floor(r() * (CORE_W + 40)) - 20, y: Math.floor(r() * 66), seed: r(), big: r() < 0.14 }); }
@@ -1034,7 +1082,9 @@ function mount(root) {
   let keyA = 0; let keyB = 1; let keyP = 0;
   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 (!calm) anim += dt; matBuf.set(baseBuf); varBuf.fill(0); emitList.length = 0;
+    const h = hourOf(clock);
+    if (pluginScene) { 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);
     if (!calm) { birds.next -= dt; if (birds.t >= 0) { birds.t += dt; if (birds.t > 9) birds.t = -1; } else if (birds.next <= 0) { birds.t = 0; birds.next = 12 + Math.random() * 14; birds.y = 10 + Math.random() * 24; birds.dir = Math.random() < 0.5 ? 1 : -1; } shoot.next -= dt; if (shoot.t >= 0) { shoot.t += dt; if (shoot.t > 0.6) shoot.t = -1; } else if (shoot.next <= 0) { shoot.t = 0; shoot.next = 9 + Math.random() * 16; shoot.x = 10 + Math.random() * 130; shoot.y = 2 + Math.random() * 20; } }
@@ -1326,7 +1376,14 @@ function unmountOne(root) {
 }
 function mountAll() { document.querySelectorAll(SELECTOR).forEach(mountOne); }
 const api = { mount: mountOne, unmount: unmountOne };
-if (typeof document !== 'undefined') {
+if (typeof window !== 'undefined' && window.PixelDaylightSwitchScenePlugins) {
+  const sceneApi = window.PixelDaylightSwitchScenePlugins;
+  api.registerScene = sceneApi.registerScene;
+  api.validateScene = sceneApi.validateScene;
+  api.getScene = sceneApi.getScene;
+  api.listScenes = sceneApi.listScenes;
+}
+if (typeof document !== 'undefined' && !(typeof window !== 'undefined' && window.__PDS_DEFER_AUTO_MOUNT__)) {
   if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', mountAll, { once: true });
   else mountAll();
 }

package/browser.mjs

@@ -0,0 +1,20 @@
+import './scene-plugin.js';
+
+// Browser ESM consumers need to register their scene before mounting.
+// Suppress the classic script's automatic DOM scan until the caller invokes mount().
+globalThis.__PDS_DEFER_AUTO_MOUNT__ = true;
+try {
+  await import('./app.js');
+} finally {
+  delete globalThis.__PDS_DEFER_AUTO_MOUNT__;
+}
+
+const api = globalThis.PixelDaylightSwitch;
+const scenes = globalThis.PixelDaylightSwitchScenePlugins;
+export const mount = api.mount;
+export const unmount = api.unmount;
+export const registerScene = scenes.registerScene;
+export const validateScene = scenes.validateScene;
+export const getScene = scenes.getScene;
+export const listScenes = scenes.listScenes;
+export default api;

package/examples/scenes/sakura-evening.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "id": "sakura-evening",
+  "name": "Sakura Evening",
+  "author": "Community Artist",
+  "license": "CC-BY-4.0",
+  "canvas": { "width": 16, "height": 8 },
+  "pixels": [
+    "................",
+    "......ccc.......",
+    ".....ccccc......",
+    "...tt..s..tt....",
+    "..ttttsss.tttt..",
+    "......sss.......",
+    "gggggggggggggggg",
+    "gggggggggggggggg"
+  ],
+  "palettes": {
+    "day": {
+      ".": "#9bd8f5", "c": "#f4a7c8", "t": "#8a5a72", "s": "#f6d6df", "g": "#78ad72"
+    },
+    "dusk": {
+      ".": "#ef9b83", "c": "#dc83b4", "t": "#563e69", "s": "#f0c0cf", "g": "#526f62"
+    },
+    "night": {
+      ".": "#171d3b", "c": "#9879b5", "t": "#292744", "s": "#c3a4c8", "g": "#283f45"
+    }
+  },
+  "timeCycle": [
+    { "at": 0, "palette": "night" },
+    { "at": 5.5, "palette": "night" },
+    { "at": 7, "palette": "day" },
+    { "at": 16.5, "palette": "day" },
+    { "at": 19, "palette": "dusk" },
+    { "at": 21, "palette": "night" },
+    { "at": 24, "palette": "night" }
+  ]
+}

package/index.cjs

@@ -1,4 +1,11 @@
 'use strict';
 
-// The browser runtime is inert during SSR and exposes mount/unmount when a DOM exists.
-module.exports = require('./app.js');
+// Load the declarative scene registry before the browser runtime so registered
+// community scenes are available when mount() initializes a root.
+const scenes = require('./scene-plugin.js');
+const api = require('./app.js');
+api.registerScene = scenes.registerScene;
+api.validateScene = scenes.validateScene;
+api.getScene = scenes.getScene;
+api.listScenes = scenes.listScenes;
+module.exports = api;

package/index.d.ts

@@ -0,0 +1,52 @@
+export interface ScenePalette {
+  [symbol: string]: `#${string}`;
+}
+
+export interface SceneTimeStop {
+  /** Local scene time in hours, from 0 through 24. */
+  at: number;
+  /** Key in SceneManifest.palettes. */
+  palette: string;
+}
+
+export interface SceneManifest {
+  schemaVersion: 1;
+  /** Unique lowercase community scene identifier (3-64 characters). */
+  id: string;
+  name: string;
+  author: string;
+  /** SPDX identifier or a clearly stated license label. */
+  license: string;
+  canvas: { width: number; height: number };
+  /** One printable-ASCII character per pixel; rows match canvas dimensions. */
+  pixels: string[];
+  /** Each palette maps every used pixel symbol to a #RGB or #RRGGBB color. */
+  palettes: Record<string, ScenePalette>;
+  /** Strictly increasing palette stops; must begin at 0 and end at 24. */
+  timeCycle: SceneTimeStop[];
+}
+
+export interface SceneValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+export type UnregisterScene = () => boolean;
+
+export interface PixelDaylightSwitchAPI {
+  mount(root: Element | null): (() => void) | null;
+  unmount(root: Element | null): void;
+  registerScene(manifest: SceneManifest): UnregisterScene;
+  validateScene(manifest: unknown): SceneValidationResult;
+  getScene(id: string): SceneManifest | null;
+  listScenes(): SceneManifest[];
+}
+
+declare const PixelDaylightSwitch: PixelDaylightSwitchAPI;
+export declare const mount: PixelDaylightSwitchAPI['mount'];
+export declare const unmount: PixelDaylightSwitchAPI['unmount'];
+export declare const registerScene: PixelDaylightSwitchAPI['registerScene'];
+export declare const validateScene: PixelDaylightSwitchAPI['validateScene'];
+export declare const getScene: PixelDaylightSwitchAPI['getScene'];
+export declare const listScenes: PixelDaylightSwitchAPI['listScenes'];
+export default PixelDaylightSwitch;

package/index.mjs

@@ -2,4 +2,8 @@ import api from './index.cjs';
 
 export const mount = api.mount;
 export const unmount = api.unmount;
+export const registerScene = api.registerScene;
+export const validateScene = api.validateScene;
+export const getScene = api.getScene;
+export const listScenes = api.listScenes;
 export default api;

package/llms.txt

@@ -1,118 +1,111 @@
 # Pixel Daylight Switch
 
-> A dependency-free, draggable pixel-art day/night switch. A tiny animated world lives inside a refractive glass lens.
+> A dependency-free, draggable pixel-art day/night UI component. Five living pixel-art environments sit inside a refractive glass lens, with continuous day-to-night color, lighting and animation transitions.
 
-## Quick Start
+## Zero-setup browser embed
 
-### CDN
+Paste one line where the component should appear:
 
 ```html
-<div data-ld-part="toggle-daylight"></div>
-<script src="https://cdn.jsdelivr.net/npm/pixel-daylight-switch-gsvegetable@1.3.0/app.js"></script>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/embed.js"></script>
 ```
 
-### NPM
+The loader creates a responsive instance and loads the runtime. Component styles are scoped; the loader does not inject the demo stylesheet or reset the host page's body, main, footer, typography or layout. Set supported `data-*` options (including `data-scene` and `data-weather`) on the script tag to configure this instance. Use the mount API for multiple instances or custom placement.
 
-- Install: `npm install pixel-daylight-switch-gsvegetable`
-- ESM: `import PixelDaylightSwitch from 'pixel-daylight-switch-gsvegetable'`
-- Named imports: `import { mount, unmount } from 'pixel-daylight-switch-gsvegetable'`
-- CommonJS: `const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable')`
-- The runtime auto-mounts matching elements present when the script is evaluated.
-- Call `mount(element)` for elements created later. Call `unmount(element)` before removing a mounted element.
-- SSR-safe to import: DOM work only runs when `document` exists.
+## Direct browser usage
 
-## Markup
-
-- Mount selector: `[data-ld-part="toggle-daylight"]`
-- The component creates its canvas, interaction button, and live status element if they are missing.
-- Multiple independent instances are supported.
-- The root element should have a measurable width. Its aspect ratio is 1.6439.
-
-## Data Attributes
+```html
+<div style="width:min(100%, 800px);margin-inline:auto">
+  <div data-ld-part="toggle-daylight" data-scene="japanese-street"></div>
+</div>
+<script src="https://gsvegetable.github.io/pixel-daylight-switch/app.js"></script>
+```
 
-All attributes are optional unless stated. Numeric values that are invalid use the default. Numeric values with documented ranges are clamped to those ranges.
+No stylesheet import is required. The runtime injects component-scoped CSS and automatically mounts matching elements. The host/container must have a measurable width. The component preserves its 1.6439 aspect ratio and scales to its available width.
 
-| Attribute | Default | Accepted values / range | Effect |
-| --- | --- | --- | --- |
-| `data-ld-part` | required | `toggle-daylight` | Identifies a component root for automatic mounting. |
-| `data-label` | localized label | Any text | Accessible label for the switch button. |
-| `data-speed` | `9.5` | Positive number | Base motion response speed. |
-| `data-refraction` | `1.24` | Positive number | Refraction strength of the glass lens. |
-| `data-bezel` | `0.046` | Positive number | Glass bezel thickness ratio. |
-| `data-start-night` | `false` | `true` / `false` | Start in night mode when exactly `true`. |
-| `data-friction` | `0.6` | `0.1–0.9` | Release inertia damping. Lower values retain more glide. |
-| `data-bounce` | `3.2` | `0–12` | Edge rebound impulse. |
-| `data-dispersion` | `0.05` | `0–0.25` | RGB chromatic dispersion at the lens edge. |
-| `data-shine` | `0.44` | `0–1.5` | Daylight lens highlight intensity. |
-| `data-time-speed` | `1.0` | `0–8` | Pixel-world simulation speed; zero freezes world time. |
-| `data-weather` | `default` | `default`, `snow` | Selects the weather effect. Unknown values use `default`. |
-| `data-scene` | `countryside` | `countryside`, `japanese-street`, `apartment`, `seaside`, `mountain-cabin` | Selects the pixel environment. Unknown values use `countryside`. |
+## npm
 
-## CSS Custom Properties
+```bash
+npm install pixel-daylight-switch-gsvegetable
+```
 
-Set these on the component root. Values shown are the runtime fallbacks.
+```js
+import PixelDaylightSwitch, { mount, unmount } from 'pixel-daylight-switch-gsvegetable';
 
-| Variable | Default | Effect |
-| --- | --- | --- |
-| `--ld-bg` | `#f5ecd9` | Component background palette input. |
-| `--ld-surface` | `#8c9a62` | Surface and environment palette input. |
-| `--ld-fg` | `#1b2146` | Foreground palette input. |
-| `--ld-muted` | `#7f97b3` | Muted palette input. |
-| `--ld-accent` | `#efa02c` | Focus and accent color. |
-| `--ld-radius` | `9999px` | Interaction button corner radius. |
-| `--ld-font` | `system-ui, sans-serif` | Component font family. |
-| `--ld-space` | `8px` | Focus outline offset scale. |
-| `--ld-shadow` | `0 8px 24px rgb(27 33 70 / .2)` | Reserved theme token; current renderer does not consume it. |
-| `--ld-motion` | `200ms` | Focus outline transition duration. |
-| `--night` | Runtime: `0–1` | Read-only live night intensity; 0 is day, 1 is night. |
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+mount(root);
+// Before removing the root:
+unmount(root);
+```
 
-## JavaScript API
+CommonJS: `const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable')`.
 
-### `PixelDaylightSwitch.mount(element)`
+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.
 
-- Mounts one component root element.
-- Returns a cleanup function when mounting succeeds; returns `null` if mounting fails.
-- Idempotent: mounting the same element twice does not create duplicate instances.
-- Example: `const destroy = PixelDaylightSwitch.mount(element)`.
+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).
 
-### `PixelDaylightSwitch.unmount(element)`
+## Community scene plugins (v3.0.0)
 
-- Stops rendering, removes observers and event listeners, and releases the WebGL context for that element.
-- Call before removing the element from the document.
-- Does not remove the root element itself.
+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).
 
-### ESM and CommonJS
+## Scenes and weather
 
-```js
-import PixelDaylightSwitch, { mount, unmount } from 'pixel-daylight-switch-gsvegetable';
+| Attribute | Default | Accepted values |
+| --- | --- | --- |
+| `data-scene` | `countryside` | `countryside`, `japanese-street`, `apartment`, `seaside`, `mountain-cabin` |
+| `data-weather` | `default` | `default`, `snow` |
+| `data-start-night` | `false` | `true`, `false` |
 
-// Or CommonJS:
-// const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable');
+All five scenes are authored environments, not static background images. They use time-of-day palette keys and scene-specific lighting/animation: for example, the seaside lighthouse sweeps a beam across the bay, the apartment changes window and room lighting and animates its cat/resident, and the mountain cabin includes snow/pines and aurora behavior. Scene details continue to evolve as the clock moves between dawn, day, dusk and night.
 
-const root = document.querySelector('[data-ld-part="toggle-daylight"]');
-mount(root);
-// Later:
-unmount(root);
-```
+## Visual and motion parameters
 
-## Event
+| Attribute | Default | Accepted values / range |
+| --- | --- | --- |
+| `data-speed` | `9.5` | Positive number |
+| `data-refraction` | `1.24` | Positive number |
+| `data-bezel` | `0.046` | Positive number |
+| `data-friction` | `0.6` | `0.1–0.9` |
+| `data-bounce` | `3.2` | `0–12` |
+| `data-dispersion` | `0.05` | `0–0.25` |
+| `data-shine` | `0.44` | `0–1.5` |
+| `data-time-speed` | `1` | `0–8`; zero freezes world time |
+
+Invalid values fall back to defaults; documented numeric ranges are clamped.
+
+## JavaScript API and events
+
+- `mount(element)`: mount one root; idempotent.
+- `unmount(element)`: stop rendering and clean up observers and event listeners.
+- The runtime auto-mounts existing `[data-ld-part="toggle-daylight"]` elements.
+- Use `mount(element)` for elements created later.
+- Listen for `daylight:change` on the root. `event.detail.night` is a boolean and the event fires when the committed day/night state changes, not every animation frame.
+- The root exposes transition progress through CSS custom property `--night` (0 day, 1 night).
+
+## Rendering, accessibility and performance
+
+- WebGL2 renders the refractive glass; Canvas 2D is the fallback.
+- Keyboard interaction, switch semantics, accessible labels and live status are provided.
+- Respects `prefers-reduced-motion`.
+- Rendering pauses while the page is hidden or the component is outside the viewport.
+- Multiple independent instances are supported.
 
-### `daylight:change`
+## Links
 
-- Dispatched on the component root when the switch reaches a changed day/night state.
-- Bubbles and is composed.
-- `event.detail.night` is a boolean.
+- [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)
+- [English README](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
+- [Changelog](CHANGELOG.md)
 
-```js
-document.addEventListener('daylight:change', (event) => {
-  const isNight = event.detail.night;
-  document.documentElement.classList.toggle('dark', isNight);
-});
-```
 
-## Rendering and Compatibility
+## Scene plugins (v3.0.0)
 
-- WebGL2 renders the refractive glass; Canvas 2D is used as a fallback.
-- Respects `prefers-reduced-motion`.
-- Pauses unnecessary rendering when the page is hidden or the component is offscreen.
-- No runtime dependencies.
+- 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixel-daylight-switch-gsvegetable",
-  "version": "2.2.0",
-  "description": "A draggable pixel-art day/night switch with a living world inside a refractive glass lens.",
+  "version": "3.0.0",
+  "description": "A draggable pixel-art day/night switch with a community-extensible scene plugin system.",
   "keywords": [
     "pixel-art",
     "day-night",
@@ -13,7 +13,11 @@
     "vanilla-js",
     "capacitor",
     "android",
-    "ios"
+    "ios",
+    "scene-plugin",
+    "pixel-world",
+    "scene-manifest",
+    "pixel-art-scenes"
   ],
   "author": "GSvegetable",
   "license": "Unlicense",
@@ -27,14 +31,20 @@
   },
   "main": "./index.cjs",
   "module": "./index.mjs",
-  "browser": "./app.js",
+  "browser": "./browser.mjs",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
+      "browser": "./browser.mjs",
       "import": "./index.mjs",
       "require": "./index.cjs"
     },
     "./app.js": "./app.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./scene-plugin": {
+      "import": "./scene-plugin.js",
+      "require": "./scene-plugin.js"
+    }
   },
   "files": [
     "app.js",
@@ -42,7 +52,14 @@
     "index.mjs",
     "README.md",
     "LICENSE",
-    "llms.txt"
+    "llms.txt",
+    "INTEGRATIONS.md",
+    "SCENE_PLUGINS.md",
+    "scene-plugin.js",
+    "schemas",
+    "examples",
+    "browser.mjs",
+    "index.d.ts"
   ],
   "sideEffects": [
     "./app.js"
@@ -54,7 +71,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node tests/package-smoke.cjs && node tests/mobile-smoke.cjs",
+    "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",
     "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",
@@ -69,5 +86,6 @@
     "@capacitor/core": "8.6.0",
     "@capacitor/android": "8.6.0",
     "@capacitor/ios": "8.6.0"
-  }
+  },
+  "types": "./index.d.ts"
 }

package/scene-plugin.js

@@ -0,0 +1,127 @@
+(function (root, factory) {
+  const api = root && root.PixelDaylightSwitchScenePlugins ? root.PixelDaylightSwitchScenePlugins : factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) {
+    root.PixelDaylightSwitchScenePlugins = api;
+    root.PixelDaylightSwitchScenes = api;
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict';
+  const registry = new Map();
+  const MAX_WIDTH = 192, MAX_HEIGHT = 112, MAX_PALETTES = 8, MAX_SYMBOLS = 64, MAX_TIME_STOPS = 48;
+  const ID_RE = /^[a-z0-9][a-z0-9._-]{1,62}[a-z0-9]$/;
+  const COLOR_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+  const SYMBOL_RE = /^[\x20-\x7E]$/;
+  const BUILT_INS = new Set(['countryside', 'japanese-street', 'apartment', 'seaside', 'mountain-cabin']);
+  const isPlainObject = value => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  };
+  const unknownKeys = (value, allowed, path, errors) => {
+    if (isPlainObject(value)) Object.keys(value).forEach(key => { if (!allowed.has(key)) errors.push(path + ' contains unsupported property "' + key + '".'); });
+  };
+  function validateScene(input) {
+    const errors = [];
+    if (!isPlainObject(input)) return { valid:false, errors:['Scene manifest must be a plain object.'] };
+    unknownKeys(input, new Set(['schemaVersion','id','name','author','license','canvas','pixels','palettes','timeCycle']), 'manifest', errors);
+    if (input.schemaVersion !== 1) errors.push('schemaVersion must be 1.');
+    if (typeof input.id !== 'string' || !ID_RE.test(input.id)) errors.push('id must be 3-64 lowercase letters, numbers, dots, underscores or hyphens.');
+    if (BUILT_INS.has(input.id)) errors.push('Built-in scene IDs are reserved.');
+    if (typeof input.name !== 'string' || !input.name.trim() || input.name.length > 80) errors.push('name must be a non-empty string of at most 80 characters.');
+    if (typeof input.author !== 'string' || !input.author.trim() || input.author.length > 80) errors.push('author must be a non-empty string of at most 80 characters.');
+    if (typeof input.license !== 'string' || !input.license.trim() || input.license.length > 64) errors.push('license must be a non-empty SPDX identifier or license label.');
+    const canvas = input.canvas;
+    if (!isPlainObject(canvas)) errors.push('canvas must be an object.');
+    else unknownKeys(canvas, new Set(['width','height']), 'canvas', errors);
+    const width = canvas && canvas.width, height = canvas && canvas.height;
+    if (!Number.isInteger(width) || width < 1 || width > MAX_WIDTH) errors.push('canvas.width must be an integer from 1 to 192.');
+    if (!Number.isInteger(height) || height < 1 || height > MAX_HEIGHT) errors.push('canvas.height must be an integer from 1 to 112.');
+    if (!Array.isArray(input.pixels) || input.pixels.length === 0) errors.push('pixels must be a non-empty array of strings.');
+    else {
+      if (input.pixels.length > MAX_HEIGHT) errors.push('pixels cannot contain more than 112 rows.');
+      if (Number.isInteger(height) && input.pixels.length !== height) errors.push('pixels must contain exactly canvas.height rows.');
+      input.pixels.forEach((row,index) => {
+        if (typeof row !== 'string' || !Number.isInteger(width) || row.length !== width) errors.push('pixels[' + index + '] must be a string exactly canvas.width characters long.');
+        else if (!Array.from(row).every(symbol => SYMBOL_RE.test(symbol))) errors.push('pixels[' + index + '] may contain printable ASCII characters only.');
+      });
+    }
+    const palettes = input.palettes;
+    if (!isPlainObject(palettes)) errors.push('palettes must be an object of named color maps.');
+    else {
+      const names = Object.keys(palettes);
+      if (!names.length) errors.push('palettes must define at least one palette.');
+      if (names.length > MAX_PALETTES) errors.push('palettes cannot contain more than 8 palettes.');
+      names.forEach(name => {
+        const palette = palettes[name];
+        if (!isPlainObject(palette)) errors.push('palette "' + name + '" must be a color map.');
+        else {
+          const symbols = Object.keys(palette);
+          if (symbols.length > MAX_SYMBOLS) errors.push('palette "' + name + '" cannot contain more than 64 symbols.');
+          symbols.forEach(symbol => {
+            if (!SYMBOL_RE.test(symbol)) errors.push('Palette keys must be one printable ASCII character.');
+            if (typeof palette[symbol] !== 'string' || !COLOR_RE.test(palette[symbol])) errors.push('Palette color for "' + symbol + '" must be #RGB or #RRGGBB.');
+          });
+        }
+      });
+    }
+    const timeCycle = input.timeCycle;
+    if (!Array.isArray(timeCycle) || timeCycle.length < 2) errors.push('timeCycle must contain at least two time stops.');
+    else {
+      if (timeCycle.length > MAX_TIME_STOPS) errors.push('timeCycle may contain at most 48 stops.');
+      let previous = -1;
+      timeCycle.forEach((stop,index) => {
+        if (!isPlainObject(stop)) { errors.push('timeCycle[' + index + '] must be an object.'); return; }
+        unknownKeys(stop, new Set(['at','palette']), 'timeCycle[' + index + ']', errors);
+        if (!Number.isFinite(stop.at) || stop.at < 0 || stop.at > 24 || stop.at <= previous) errors.push('timeCycle[' + index + '].at must be strictly increasing from 0 to 24.');
+        else previous = stop.at;
+        if (typeof stop.palette !== 'string' || !isPlainObject(palettes) || !Object.prototype.hasOwnProperty.call(palettes,stop.palette)) errors.push('timeCycle[' + index + '] references an unknown palette.');
+      });
+      if (timeCycle[0] && timeCycle[0].at !== 0) errors.push('timeCycle must start at hour 0.');
+      if (timeCycle[timeCycle.length-1] && timeCycle[timeCycle.length-1].at !== 24) errors.push('timeCycle must end at hour 24.');
+    }
+    if (Array.isArray(input.pixels) && isPlainObject(palettes)) {
+      const symbols = new Set();
+      input.pixels.forEach(row => { if (typeof row === 'string') for (const symbol of row) symbols.add(symbol); });
+      if (symbols.size > MAX_SYMBOLS) errors.push('pixels cannot use more than 64 unique symbols.');
+      Object.keys(palettes).forEach(name => {
+        const palette = palettes[name];
+        if (!isPlainObject(palette)) return;
+        symbols.forEach(symbol => { if (!Object.prototype.hasOwnProperty.call(palette,symbol)) errors.push('Palette "' + name + '" is missing pixel symbol "' + symbol + '".'); });
+      });
+    }
+    return { valid:errors.length === 0, errors };
+  }
+  function deepFreeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+    Object.keys(value).forEach(key => deepFreeze(value[key]));
+    return Object.freeze(value);
+  }
+  function registerScene(manifest) {
+    const result = validateScene(manifest);
+    if (!result.valid) {
+      const error = new Error('Invalid Pixel Daylight Switch scene: ' + result.errors.join(' '));
+      error.validationErrors = result.errors;
+      throw error;
+    }
+    if (registry.has(manifest.id)) throw new Error('A scene with id "' + manifest.id + '" is already registered.');
+    let snapshot;
+    try { snapshot = JSON.parse(JSON.stringify(manifest)); }
+    catch (cause) {
+      const error = new Error('Scene manifest must be JSON-serializable.');
+      error.cause = cause;
+      throw error;
+    }
+    const frozen = deepFreeze(snapshot);
+    registry.set(frozen.id, frozen);
+    let active = true;
+    return function unregisterScene() {
+      if (!active) return false;
+      active = false;
+      return registry.delete(frozen.id);
+    };
+  }
+  const getScene = id => registry.get(id) || null;
+  const listScenes = () => Array.from(registry.values());
+  return Object.freeze({ registerScene, validateScene, getScene, listScenes, schemaVersion:1 });
+});

package/schemas/scene-manifest.v1.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gsvegetable.github.io/pixel-daylight-switch/schemas/scene-manifest.v1.schema.json",
+  "title": "Pixel Daylight Switch Scene Manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "name",
+    "author",
+    "license",
+    "canvas",
+    "pixels",
+    "palettes",
+    "timeCycle"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9][a-z0-9._-]{1,62}[a-z0-9]$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "author": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "license": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "canvas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "width",
+        "height"
+      ],
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 192
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 112
+        }
+      }
+    },
+    "pixels": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 112,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 192,
+        "pattern": "^[\\x20-\\x7E]+$"
+      }
+    },
+    "palettes": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 8,
+      "additionalProperties": {
+        "type": "object",
+        "maxProperties": 64,
+        "propertyNames": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1,
+          "pattern": "^[\\u0020-\\u007E]$"
+        },
+        "additionalProperties": {
+          "type": "string",
+          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
+        }
+      }
+    },
+    "timeCycle": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "at",
+          "palette"
+        ],
+        "properties": {
+          "at": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 24
+          },
+          "palette": {
+            "type": "string"
+          }
+        }
+      },
+      "maxItems": 48
+    }
+  }
+}