immersive-media-spots 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug Report
+about: Report a problem with an IMS widget
+labels: bug
+---
+
+**Widget**: (e.g., ims-spinner, ims-video, ims-pano)
+
+**Version**: 
+
+**Browser**: 
+
+**Description**:
+A clear description of the bug.
+
+**Steps to Reproduce**:
+1. 
+2. 
+3. 
+
+**Expected Behavior**:
+
+**Actual Behavior**:
+
+**Config JSON** (if applicable):
+```json
+
+```
+
+**Screenshots** (if applicable):

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+labels: enhancement
+---
+
+**Widget**: (e.g., ims-spinner, ims-video, ims-pano, new widget, all)
+
+**Description**:
+A clear description of the feature you'd like.
+
+**Use Case**:
+Why would this feature be useful?
+
+**Proposed Solution** (optional):
+How you'd approach implementing this.
+
+**Alternatives Considered** (optional):
+Other approaches you've considered.

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm test
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install
+      - run: npm run types

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Package exports map for clean subpath imports
+- `.npmignore` to reduce published package size
+- CSS custom properties design system for theming
+- TypeScript type definitions for all public APIs and data classes
+
+### Fixed
+- README importmap version mismatch (Symbiote.js 2.x → 3.x)
+
+## [0.2.2] - 2024-12-01
+
+### Added
+- `ims-video` widget with HLS support, captions, and customizable controls
+- `ims-viewer` universal component with dynamic CDN loading
+- `ims-diff` image comparison widget
+- `ims-gallery` interactive image gallery
+- `ims-pano` 360° panorama viewer
+- `ims-spinner` 360° object viewer
+- Adaptive content loading and DPI support
+- Full-screen display mode
+- Data-to-image steganographic encoding utilities
+- Mobile device compatibility

package/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to IMS
+
+Thank you for your interest in contributing to Interactive Media Spots!
+
+## Development Setup
+
+```bash
+git clone https://github.com/rnd-pro/immersive-media-spots.git
+cd immersive-media-spots
+npm install
+```
+
+## Project Structure
+
+```
+lib/              — Shared base classes and utilities
+  ImsBaseClass.js — Base class for all widgets
+  FullscreenMgr.js — Fullscreen API manager
+  ImageReader.js  — Image sequence loader with progress
+  tokens.css      — CSS design tokens
+  validateConfig.js — Runtime config validation
+
+wgt/              — Widget implementations
+  diff/           — Image comparison
+  gallery/        — Image gallery
+  pano/           — 360° panorama viewer
+  spinner/        — 360° object viewer
+  video/          — Video player with HLS
+  viewer/         — Universal CDN-driven loader
+
+tests/            — Unit tests (Node.js test runner)
+```
+
+## Widget Anatomy
+
+Each widget follows this structure:
+- `index.js` — Component class extending `ImsBaseClass`
+- `template.js` — HTML template
+- `styles.js` — Shadow DOM styles
+- `ImsXxxData.js` — Data schema class
+- `test.html` — Manual test page
+- `test-data.json` — Test fixture data
+
+## Running Tests
+
+```bash
+npm test
+```
+
+## Code Style
+
+- Single quotes for strings
+- 2-space indentation
+- Semicolons required
+- ESM only (no `require`)
+- Use `#` for private class fields
+- JSDoc for type annotations
+- Modern CSS nesting
+- No external CSS frameworks
+
+## Submitting Changes
+
+1. Fork and create a feature branch
+2. Make your changes following the code style above
+3. Add/update tests for new functionality
+4. Ensure `npm test` passes
+5. Submit a PR with a clear description
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RND-PRO.com (team@rnd-pro.com). All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+[![npm version](https://badge.fury.io/js/immersive-media-spots.svg)](https://badge.fury.io/js/immersive-media-spots)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# IMS — Immersive Media Spots
+
+<img src="https://rnd-pro.com/svg/ims/index.svg" width="200" alt="IMS: Immersive Media Spots">
+
+**Simple web components that turn static pages into immersive, interactive media experiences.** Drop a single HTML tag — get a full-featured 360° spinner, panorama viewer, image comparison slider, or video player.
+
+## ✨ Why IMS?
+
+- **One tag — one widget.** Just `<ims-viewer src-data="data.json">` and you're done.
+- **Universal.** Works in any stack: vanilla HTML, React, Vue, Angular, Svelte — anything that renders DOM.
+- **Smart loading.** Adaptive resolution based on viewport & DPI, lazy loading via IntersectionObserver, on-demand dependency imports.
+- **Hypermedia navigation.** Link widgets together with interactive hotspots — let users explore 3D products, then dive into 360° interiors, then watch a demo video, all in one seamless flow.
+- **Themeable.** Full CSS custom properties for colors, sizing, and layout. No CSS framework lock-in.
+- **Lightweight.** Built on [Symbiote.js](https://github.com/nicothed/symbiote.js) — each widget loads only what it needs.
+
+## 🧩 Widgets
+
+| Widget | Description | Docs |
+|--------|-------------|------|
+| **ims-spinner** | 360° product viewer with frame-by-frame rotation, autoplay, and drag interaction | [docs](./docs/spinner.md) |
+| **ims-gallery** | Touch-friendly image gallery with navigation, looping, and fullscreen | [docs](./docs/gallery.md) |
+| **ims-diff** | Before/after image comparison with a draggable slider | [docs](./docs/diff.md) |
+| **ims-pano** | 360° panorama with inertia-based pan, zoom, and auto-rotation (Three.js) | [docs](./docs/pano.md) |
+| **ims-model** | 3D model viewer for GLTF/GLB with orbit controls and auto-rotation (Three.js) | [docs](./docs/model.md) |
+| **ims-video** | Video player with HLS adaptive streaming, subtitles, and quality switching | [docs](./docs/video.md) |
+| **ims-audio** | Audio player with real-time waveform visualization (Web Audio API) | [docs](./docs/audio.md) |
+| **ims-hotspots** | Interactive overlay spots with state-bound positioning and keyframe animation | [docs](./docs/hotspots.md) |
+| **ims-viewer** | Universal loader — auto-imports any widget by type with version control, manages hotspot navigation and history | [docs](./docs/viewer.md) |
+
+## 🚀 Quick Start
+
+**1.** Set up [dependencies](./docs/dependencies.md) — add an importmap or install via npm (only Symbiote.js is required; Three.js and hls.js are needed only for the widgets that use them)
+
+**2. Load the viewer** (it pulls widget code on demand):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/immersive-media-spots@<VERSION>/viewer/+esm"></script>
+```
+
+**3. Use it:**
+
+```html
+<ims-viewer src-data="./product.json"></ims-viewer>
+```
+
+That's it. The viewer reads `imsType` from `product.json` and dynamically imports the right widget.
+
+### Direct widget usage
+
+Skip the viewer and load a specific widget directly:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/immersive-media-spots@<VERSION>/spinner/+esm"></script>
+
+<ims-spinner src-data="./data.json" autoplay="true"></ims-spinner>
+```
+
+### npm
+
+```bash
+npm install immersive-media-spots
+```
+
+## 🔗 Hypermedia Navigation
+
+Combine `ims-viewer` with `ims-hotspots` to create connected experiences:
+
+```html
+<ims-viewer
+  src-data="./exterior-spin.json"
+  url-template="./{{imsType}}/index.js"
+  hotspots="./exterior-hotspots.json">
+</ims-viewer>
+```
+
+Hotspots link widgets together — click a spot on a 360° product to open a detail gallery, then jump to a panoramic interior, all with animated back navigation. [→ Hotspots docs](./docs/hotspots.md)
+
+## ⚙️ Common Features
+
+All widgets share a base architecture that provides:
+
+- 🎯 **Adaptive loading** — automatically selects the best resolution variant for the viewport and DPI
+- 🔄 **Lazy loading** — `lazy` attribute defers initialization until the element enters the viewport
+- 🖥️ **Fullscreen** — native Fullscreen API with CSS fallback
+- 📱 **Mobile-ready** — touch gestures, responsive sizing, pointer event support
+- 🎨 **CSS theming** — design tokens for toolbar, colors, spacing, and transitions
+- 🔌 **Plugin system** — extend lifecycle hooks with custom plugins
+- 📡 **Events** — standard lifecycle events: `ims-load`, `ims-ready`, `ims-error` ([→ events docs](./docs/events.md))
+- 🏷️ **Attribute overrides** — override any JSON config property via HTML attributes
+
+## 📚 Documentation
+
+Full per-widget API reference, config schemas, and CSS custom properties:
+
+| | | |
+|---|---|---|
+| [Spinner](./docs/spinner.md) | [Gallery](./docs/gallery.md) | [Diff](./docs/diff.md) |
+| [Pano](./docs/pano.md) | [Model](./docs/model.md) | [Video](./docs/video.md) |
+| [Audio](./docs/audio.md) | [Hotspots](./docs/hotspots.md) | [Viewer](./docs/viewer.md) |
+| [Events](./docs/events.md) | [Dependencies](./docs/dependencies.md) | |
+
+## 📰 Articles & Demos
+
+- [Concept details and live demo](https://rnd-pro.com/pulse/immersive-media-spots/)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © [rnd-pro.com](https://rnd-pro.com)

package/docs/audio.md

@@ -0,0 +1,44 @@
+# ims-audio
+
+Audio player with waveform visualization.
+
+## Tag
+
+```html
+<ims-audio src-data="path/to/data.json"></ims-audio>
+```
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `src-data` | URL to JSON config |
+| `lazy` | Enable lazy loading |
+| `no-preloader` | Disable loading spinner |
+
+## Config (`ImsAudioData`)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `imsType` | `string` | `'audio'` | Widget type identifier |
+| `srcList` | `string[]` | — | Audio file URL(s) |
+| `autoplay` | `boolean` | `false` | Auto-play on load |
+| `loop` | `boolean` | `false` | Loop playback |
+| `waveformColor` | `string` | — | Waveform fill color |
+| `progressColor` | `string` | — | Progress indicator color |
+| `hideUi` | `boolean` | `false` | Hide toolbar |
+
+## Public API
+
+| Method | Description |
+|---|---|
+| `play()` | Start playback |
+| `pause()` | Pause playback |
+| `togglePlay()` | Toggle play/pause |
+| `seek(seconds)` | Seek to position in seconds |
+| `setVolume(val)` | Set volume (0–100) |
+| `toggleMute()` | Toggle mute |
+
+## Events
+
+See [events.md](./events.md) for standard IMS lifecycle events.

package/docs/dependencies.md

@@ -0,0 +1,69 @@
+# Dependencies
+
+IMS widgets are designed to keep a minimal footprint. Heavy third-party libraries are **only required by the widgets that actually use them** — if you never render a panorama or 3D model, Three.js is never loaded.
+
+## Core
+
+| Package | Specifier | Used by |
+|---------|-----------|---------|
+| [Symbiote.js](https://github.com/nicothed/symbiote.js) | `@symbiotejs/symbiote` | All widgets |
+
+Symbiote.js is the only mandatory dependency. It provides the reactive web component base class used by every IMS widget.
+
+## Optional (per-widget)
+
+| Package | Specifier | Used by | Purpose |
+|---------|-----------|---------|---------|
+| [Three.js](https://threejs.org/) | `three` | ims-pano, ims-model | WebGL rendering for 360° panoramas and 3D models |
+| Three.js addons | `three/addons/` | ims-model | GLTFLoader for `.glb`/`.gltf` model files |
+| [hls.js](https://github.com/nicothed/hls.js/) | `hls.js/dist/hls.mjs` | ims-video | HLS adaptive streaming (only when `hlsSrc` is configured) |
+
+> **If you only use `ims-spinner`, `ims-gallery`, `ims-diff`, `ims-audio`, or `ims-hotspots` — no optional dependencies are needed at all.**
+
+## Setup via importmap
+
+The simplest way to provide dependencies is an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) — no build step needed:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@symbiotejs/symbiote": "https://cdn.jsdelivr.net/npm/@symbiotejs/symbiote@3/+esm",
+      "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/+esm",
+      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/",
+      "hls.js/dist/hls.mjs": "https://cdn.jsdelivr.net/npm/hls.js@1.5/+esm"
+    }
+  }
+</script>
+```
+
+Only include the entries you actually need. For example, if you only use `ims-spinner`:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@symbiotejs/symbiote": "https://cdn.jsdelivr.net/npm/@symbiotejs/symbiote@3/+esm"
+    }
+  }
+</script>
+```
+
+## Bundled setup
+
+When using a bundler (Vite, esbuild, Webpack, etc.), install the required packages via npm and let the bundler resolve them:
+
+```bash
+# Core (required)
+npm install @symbiotejs/symbiote
+
+# Optional — only if you use the corresponding widgets
+npm install three       # ims-pano, ims-model
+npm install hls.js      # ims-video with HLS
+```
+
+The bundler will tree-shake unused widgets and their dependencies automatically.
+
+## CDN resolution (ims-viewer)
+
+When using `ims-viewer`, widget code is **loaded dynamically** at runtime based on the `imsType` field in the source data. The importmap must be present at page load so that dynamically imported modules can resolve their dependencies correctly.

package/docs/diff.md

@@ -0,0 +1,68 @@
+# ims-diff
+
+Before/after image comparison with multiple modes.
+
+## Tag
+
+```html
+<ims-diff src-data="path/to/data.json"></ims-diff>
+```
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `src-data` | URL to JSON config |
+| `lazy` | Enable lazy loading |
+| `no-preloader` | Disable loading spinner |
+| `vertical` | Set automatically when orientation is vertical |
+
+## Config (`ImsDiffData`)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `imsType` | `string` | `'diff'` | Widget type identifier |
+| `srcList` | `string[]` | — | Image URLs (pairs for comparison) |
+| `mode` | `string` | `'slider'` | Comparison mode: `'slider'` or `'onion'` |
+| `orientation` | `string` | `'horizontal'` | Split orientation: `'horizontal'` or `'vertical'` |
+| `startPosition` | `number` | `50` | Initial slider position (0–100) |
+| `animateSpeed` | `number` | `2000` | Animated sweep duration (ms per full sweep) |
+| `filters` | `string[]` | — | CSS filter strings per image |
+| `hideUi` | `boolean` | `false` | Hide toolbar |
+| `urlTemplate` | `string` | — | URL template with placeholders |
+| `variants` | `string[]` | — | Available size variants |
+
+## Comparison Modes
+
+### Slider (default)
+Drag to reveal — splits images with a movable divider line. In horizontal mode the split is left/right, in vertical mode it's top/bottom.
+
+### Onion-skin
+Overlays the second image on top of the first. Drag controls the opacity (0–1) of the overlay.
+
+## Public API
+
+| Method | Description |
+|---|---|
+| `setShare(percent)` | Set slider/opacity position (0–100) |
+| `goTo(index)` | Switch to a specific diff pair (0-based) |
+| `setMode(mode)` | Set mode: `'slider'` or `'onion'` |
+| `toggleMode()` | Toggle between slider and onion |
+| `toggleOrientation()` | Toggle horizontal/vertical split |
+| `startAnimate()` | Start animated sweep |
+| `stopAnimate()` | Stop animated sweep |
+| `toggleAnimate()` | Toggle animated sweep |
+
+## Toolbar
+
+| Button | Action |
+|---|---|
+| Mode | Toggle slider ↔ onion |
+| Orientation | Toggle horizontal ↔ vertical |
+| Play/Pause | Toggle animated sweep |
+| ◀ / ▶ | Previous/next pair (visible when `srcList > 2`) |
+| Fullscreen | Toggle fullscreen |
+
+## Events
+
+See [events.md](./events.md) for standard IMS lifecycle events.

package/docs/events.md

@@ -0,0 +1,29 @@
+# Events
+
+All IMS widgets emit standard lifecycle events via `CustomEvent`. Enable with `dispatchEvents: true` in config or listen directly on the widget element.
+
+## Event Types
+
+| Event | Constant | Detail | Description |
+|---|---|---|---|
+| `ims-load` | `ImsEvents.LOAD` | `{ progress: number }` | Data loading started |
+| `ims-ready` | `ImsEvents.READY` | `{ srcData }` | Widget initialized and ready |
+| `ims-error` | `ImsEvents.ERROR` | `{ error }` | Loading or initialization error |
+| `ims-resize` | `ImsEvents.RESIZE` | — | Widget resized |
+| `ims-destroy` | `ImsEvents.DESTROY` | — | Widget removed from DOM |
+
+## Usage
+
+```js
+import { ImsEvents } from 'immersive-media-spots';
+
+let spinner = document.querySelector('ims-spinner');
+
+spinner.addEventListener(ImsEvents.READY, (e) => {
+  console.log('Widget ready:', e.detail.srcData);
+});
+
+spinner.addEventListener(ImsEvents.ERROR, (e) => {
+  console.error('Widget error:', e.detail.error);
+});
+```

package/docs/gallery.md

@@ -0,0 +1,79 @@
+# ims-gallery
+
+Image gallery with navigation, crossfade transitions, and optional captions.
+
+## Tag
+
+```html
+<ims-gallery src-data="path/to/data.json"></ims-gallery>
+```
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `src-data` | URL to JSON config |
+| `lazy` | Enable lazy loading |
+| `no-preloader` | Disable loading spinner |
+
+## Config (`ImsGalleryData`)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `imsType` | `string` | `'gallery'` | Widget type identifier |
+| `srcList` | `string[]` | — | Image URLs |
+| `captions` | `string[]` | `[]` | Per-image captions (parallel to srcList) |
+| `transitionDuration` | `number` | `300` | Crossfade duration in ms |
+| `autoplayInterval` | `number` | `3000` | Autoplay slide interval in ms |
+| `loop` | `boolean` | `true` | Wrap around at ends |
+| `hideUi` | `boolean` | `false` | Hide toolbar |
+| `urlTemplate` | `string` | — | URL template with placeholders |
+| `variants` | `string[]` | — | Available size variants |
+
+## Public API
+
+| Method | Description |
+|---|---|
+| `goTo(index)` | Go to image by 0-based index |
+| `next()` | Next image (wraps if `loop: true`) |
+| `prev()` | Previous image (wraps if `loop: true`) |
+| `startAutoplay()` | Start slideshow |
+| `stopAutoplay()` | Stop slideshow |
+| `toggleAutoplay()` | Toggle slideshow |
+
+## Features
+
+### Crossfade Transitions
+Images crossfade using canvas globalAlpha blending. Duration controlled by `transitionDuration`.
+
+### Touch Swipe
+Horizontal swipe on the canvas triggers `next()`/`prev()`. Threshold: 50px.
+
+### Image Counter
+Toolbar shows current position (e.g. "3 / 12").
+
+### Captions
+Per-image captions from the `captions` config array are set as the widget's `title` attribute (browser tooltip). A `<slot>` element is available for custom caption components:
+
+```html
+<ims-gallery src-data="data.json">
+  <my-custom-caption></my-custom-caption>
+</ims-gallery>
+```
+
+### Autoplay
+Timer-based auto-advance, toggleable from toolbar.
+
+## Toolbar
+
+| Button | Action |
+|---|---|
+| ◀ | Previous image |
+| Counter | Shows position |
+| ▶ | Next image |
+| Play/Pause | Toggle autoplay |
+| Fullscreen | Toggle fullscreen |
+
+## Events
+
+See [events.md](./events.md) for standard IMS lifecycle events.