pixel-daylight-switch-gsvegetable 2.2.0 → 3.0.1

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

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

package/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,65 @@
+export interface ScenePalette {
+  [symbol: string]: `#${string}`;
+}
+export interface SceneTimeStop { at: number; palette: string; }
+export interface ScenePixelAsset {
+  width: number;
+  height: number;
+  /** One printable-ASCII character per pixel. A dot is transparent when used as a layer. */
+  pixels: string[];
+}
+export interface SceneLayerAnimation {
+  /** drift and bob are deterministic sinusoidal motion tracks. */
+  type: 'drift' | 'bob';
+  axis: 'x' | 'y';
+  /** Angular speed in radians per second, from 0 to 4. */
+  speed: number;
+  /** Motion amplitude in scene pixels, from 1 to 64. */
+  distance: number;
+  /** Optional phase in radians, from 0 to 2π. */
+  phase?: number;
+}
+export interface SceneLayer {
+  id: string;
+  asset: string;
+  x: number;
+  y: number;
+  animation?: SceneLayerAnimation;
+}
+export interface SceneManifestBase {
+  id: string;
+  name: string;
+  author: string;
+  license: string;
+  canvas: { width: number; height: number };
+  pixels: string[];
+  palettes: Record<string, ScenePalette>;
+  timeCycle: SceneTimeStop[];
+}
+/** Manifest v1 preserves the original single pixel-matrix format. */
+export interface SceneManifestV1 extends SceneManifestBase { schemaVersion: 1; }
+/** Manifest v2 adds reusable pixel assets, compositing layers and declarative motion. */
+export interface SceneManifestV2 extends SceneManifestBase {
+  schemaVersion: 2;
+  assets: Record<string, ScenePixelAsset>;
+  layers: SceneLayer[];
+}
+export type SceneManifest = SceneManifestV1 | SceneManifestV2;
+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,122 @@
 # 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
+```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>
+```
 
-- 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.
+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.
 
-## Data Attributes
+## npm
 
-All attributes are optional unless stated. Numeric values that are invalid use the default. Numeric values with documented ranges are clamped to those ranges.
+```bash
+npm install pixel-daylight-switch-gsvegetable
+```
 
-| 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`. |
+```js
+import PixelDaylightSwitch, { mount, unmount } from 'pixel-daylight-switch-gsvegetable';
 
-## CSS Custom Properties
+const root = document.querySelector('[data-ld-part="toggle-daylight"]');
+mount(root);
+// Before removing the root:
+unmount(root);
+```
 
-Set these on the component root. Values shown are the runtime fallbacks.
+CommonJS: `const PixelDaylightSwitch = require('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. |
+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.
 
-## JavaScript API
+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.mount(element)`
+## Community scene plugins (v3.0.0)
 
-- 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)`.
+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).
 
-### `PixelDaylightSwitch.unmount(element)`
+## Scenes and weather
 
-- 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.
+| 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` |
 
-### ESM and CommonJS
+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.
 
-```js
-import PixelDaylightSwitch, { mount, unmount } from 'pixel-daylight-switch-gsvegetable';
+## Visual and motion parameters
 
-// Or CommonJS:
-// const PixelDaylightSwitch = require('pixel-daylight-switch-gsvegetable');
+| 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.
 
-const root = document.querySelector('[data-ld-part="toggle-daylight"]');
-mount(root);
-// Later:
-unmount(root);
-```
+## Links
 
-## Event
+- [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)
 
-### `daylight:change`
 
-- Dispatched on the component root when the switch reaches a changed day/night state.
-- Bubbles and is composed.
-- `event.detail.night` is a boolean.
+## Scene plugins (v3.0.0)
 
-```js
-document.addEventListener('daylight:change', (event) => {
-  const isNight = event.detail.night;
-  document.documentElement.classList.toggle('dark', isNight);
-});
-```
+- 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.
 
-## Rendering and Compatibility
 
-- 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.
+## Scene Manifest v2 (v3.0.1)
+
+- Manifest v1 remains supported and its schema is unchanged.
+- Manifest v2 adds up to 24 reusable pixel-matrix assets and up to 16 ordered layers.
+- Layers reference named assets and integer x/y positions; '.' is transparent in overlay assets.
+- Optional deterministic motion tracks: drift or bob, on x or y, bounded speed/distance/phase.
+- Every symbol across the base matrix and assets must be defined in every palette.
+- Schema: schemas/scene-manifest.v2.schema.json. Example: examples/scenes/floating-island.v2.json.
+- No arbitrary remote image loading, eval, or executable plugin callbacks.

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.1",
+  "description": "A draggable pixel-art day/night switch with layered, animated community scenes.",
   "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"
 }