pixel-daylight-switch-gsvegetable 2.2.0 → 3.0.1

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,51 @@ 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)
+
+### Manifest v2：レイヤー付きピクセルワールド（v3.0.1）
+
+3.0.1 では Manifest v1 を変更せずに v2 を追加しました。v2 は最大 24 個の再利用可能なピクセルアセットと、最大 16 個の順序付きレイヤーに対応します。レイヤーはシーン座標に配置でき、drift または bob の宣言型モーショントラックで横・縦方向に動かせます。重ねるアセット内の . は透明として扱い、それ以外の文字は昼夜パレットで着色されます。
+
+- [Manifest v2 JSON Schema](schemas/scene-manifest.v2.schema.json)
+- [Floating Island レイヤーサンプル](examples/scenes/floating-island.v2.json)
+- [シーンプラグイン開発ガイド](SCENE_PLUGINS.md)
+
+v2 のアセットは文字ベースのピクセルマップです。PNG/JPEG の外部ダウンロードには対応しません。これによりピクセル表現と昼夜の色変化を一貫させ、外部画像の CORS や任意コード実行を避けます。
+
+5 つの組み込みシーンは従来の描画・アニメーション実装を維持します。
+
 ## 設定属性
 
 すべて任意の設定で、マウント要素に指定します。省略時または無効な値の場合はデフォルト値が使われます。
@@ -176,7 +228,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,73 @@ 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 v2 — layered pixel worlds (v3.0.1)
+
+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.
+
+```js
+import PixelDaylightSwitch, { registerScene } from 'pixel-daylight-switch-gsvegetable';
+import island from './floating-island.v2.json';
+
+registerScene(island);
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+root.dataset.scene = island.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)
+
+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.
+
+## 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 +251,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,51 @@ 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)
+
+### Manifest v2：分层像素世界（v3.0.1）
+
+3.0.1 在不改变 Manifest v1 的前提下增加了 v2。v2 支持最多 24 个可复用像素素材、最多 16 个按顺序合成的图层。图层可以指定场景坐标，并使用 drift 或 bob 声明式运动轨道沿水平或垂直方向移动。叠加素材中的点号 . 表示透明，其余字符由昼夜色板统一着色。
+
+- [Manifest v2 JSON Schema](schemas/scene-manifest.v2.schema.json)
+- [Floating Island 分层场景示例](examples/scenes/floating-island.v2.json)
+- [完整场景插件开发指南](SCENE_PLUGINS.md)
+
+当前 v2 素材采用原生字符像素矩阵，而不是远程 PNG/JPEG 图片；这样可以保持像素边缘清晰、昼夜调色一致，也不需要额外的跨域图片加载或执行第三方代码。
+
+五个内置场景仍保留原有绘制与动态逻辑。
+
 ## 配置参数
 
 所有参数均为可选项，写在挂载元素上。省略参数或参数值无效时使用默认值。
@@ -176,7 +228,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,94 @@
+# 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.
+
+## 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`: `1` for the original single-matrix format or `2` for layered pixel assets and motion.
+- `id`: unique lowercase ID, 3–64 characters. Built-in scene IDs are reserved.
+- `name`, `author`, `license`: scene metadata.
+- `canvas`: width 1–192 and height 1–112.
+- `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).
+
+## Layered scenes and pixel assets (Manifest v2)
+
+Version 3.0.1 adds reusable pixel-art assets, compositing layers and deterministic motion tracks. Manifest v1 remains supported without changes; use `schemaVersion: 2` to opt in.
+
+A v2 manifest keeps the base `canvas`, `pixels`, `palettes` and `timeCycle`, and adds:
+
+- `assets`: up to 24 named pixel matrices (each up to 192 × 112).
+- `layers`: 1–16 ordered placements that reference an asset and specify integer `x` / `y` coordinates.
+- `animation`: optional `drift` or `bob` motion on either axis, with bounded speed, distance and phase.
+
+The dot character (`.`) is transparent when an asset is composited as a layer. All other characters are palette symbols, so every palette must define colors for symbols used by the base matrix and every asset. Layers are drawn in array order; later layers appear above earlier ones. Motion is deterministic and uses the scene's animation clock; it does not execute plugin code.
+
+Example: [Floating Island v2](examples/scenes/floating-island.v2.json). The v2 contract is [schemas/scene-manifest.v2.schema.json](schemas/scene-manifest.v2.schema.json); the original v1 contract remains at [schemas/scene-manifest.v1.schema.json](schemas/scene-manifest.v1.schema.json).
+
+The current asset format is deliberately pixel-matrix based. Arbitrary PNG/JPEG downloads and executable animation callbacks are not part of v3.0.1; this keeps rendering crisp, portable, CSP-friendly and safe for community contributions.
+
+## API
+
+- `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; Manifest v2 adds bounded pixel-matrix assets, ordered layers and declarative drift/bob tracks. Neither version executes plugin JavaScript, evaluates expressions, loads arbitrary code or downloads external images. Raster image imports and tile-atlas tooling are outside the v3.0.1 scope.
+
+All five built-in scenes continue to use their original hand-authored painters and scene-specific live behavior. Community scenes use the data-driven renderer and do not replace or mutate built-in scene definitions.

package/app.js

@@ -915,12 +915,90 @@ 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;
+  let pluginAnimClock = 0;
+  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;
+    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 = 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 = 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;
+        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 +1112,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) { 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);
     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 +1406,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;