@clikvn/showroom-visualizer 0.3.4-dev-09 → 0.3.4-dev-10

package/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(npm run build:*)",
+      "Bash(grep:*)",
+      "Bash(rm:*)",
+      "Bash(ls:*)",
+      "Bash(sed:*)",
+      "Bash(yarn build)",
+      "Bash(yalc push:*)",
+      "Bash(yarn dev)",
+      "Bash(yarn list:*)",
+      "Bash(mv:*)",
+      "Bash(rg:*)"
+    ],
+    "deny": []
+  }
+}

package/CLAUDE.md

@@ -1,145 +1,145 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is a React-based 3D showroom visualizer library built with TypeScript that renders interactive 360-degree virtual tours. The library is published as `@clikvn/showroom-visualizer` and integrates with Krpano panoramic viewer technology to create immersive experiences with POIs (Points of Interest), scenarios, and multimedia content.
-
-## Build Commands
-
-```bash
-# Development with hot reload
-yarn dev
-
-# Production build
-yarn build
-
-# Linting
-yarn lint
-yarn lint:fix
-
-# Code formatting
-yarn prettier
-
-# Publish to npm
-yarn deploy  # Builds and publishes
-```
-
-## Code Architecture
-
-### Entry Points
-
-- `src/web.ts` - Main entry point that exports the visualizer API to `window.ShowroomVisualizer`
-- `src/window.ts` - Handles browser integration: `initVisualizer()` and `destroy()` methods
-- `src/features/ShowroomVisualizer/index.tsx` - Root React component that sets up providers and layout
-
-### Core Architecture Layers
-
-The codebase follows a layered architecture:
-
-1. **Visualizer Layer** (`src/models/Visualizer/`) - Domain models that manage 3D tour logic
-   - `Tour.ts` - Central orchestrator managing scenes, POIs, sounds, and scenarios
-   - `Krpano.ts` - Wrapper around Krpano API with coordinate transformation utilities
-   - `Scene.ts` - Individual 360° panorama scenes
-   - `Poi/` - Various POI types (Gallery, Info, Navigation, Multimedia, Texture, etc.)
-   - `TourScenario/` - Automated tour playback with actions (LookingAt, Moving, Rotation, Sleep, etc.)
-   - `Plugins/` - Gyro, Radar, Sound plugins
-
-2. **SkinLayer** (`src/components/SkinLayer/`) - React UI components
-   - Components overlay on the 3D viewer providing interactivity
-   - Key components: Floorplan/Minimap, HotspotOverview, PlayBar, SearchAndDiscovery, PoiDetailSlideIn
-   - Uses Ant Design components with custom styling
-
-3. **State Management** (`src/hooks/useStore.tsx`)
-   - Context-based global state management
-   - Manages UI state, active POIs, scenarios, galleries, slide-ins
-   - Provides selectors for component consumption
-
-4. **Services Layer** (`src/services/Visualizer/`)
-   - `tour.service.ts` - Fetches tour data from API
-   - `poi.service.ts` - POI-related API calls
-   - `webRotate.service.ts` - Web rotation functionality
-   - `request.ts` - HTTP client wrapper
-
-### Key Architectural Patterns
-
-**Krpano Integration**: The `Krpano` class wraps the Krpano viewer API and provides coordinate transformation utilities (`screentosphere`, `spheretoscreen`, `spheretospace`, `spacetosphere`). All 3D position calculations go through this abstraction.
-
-**POI System**: POIs are polymorphic with a base `Poi` class and specialized subtypes (PoiInfo, PoiGallery, PoiVideo, PoiSound, etc.). Each type handles its own rendering and interaction logic within the Krpano viewer.
-
-**Tour Scenario System**: Scenarios are composed of `TourScenarioStep` objects containing `TourScenarioAction` implementations. The `TourScenarioPlayer` executes actions sequentially (LookingAt → Moving → Rotation → Sleep patterns). Actions can have associated sounds managed by `ScenarioSound`.
-
-**Signal-based Events**: Uses the `signals` library extensively for decoupled event handling between Visualizer and SkinLayer.
-
-**Web Component Registration**: The library registers `<showroom-visualizer>` as a custom element (see `src/register.ts`) for easy embedding.
-
-### Configuration System
-
-Configuration flows through multiple layers:
-
-- External config passed to `initVisualizer()`
-- `ConfigurationProvider` (src/hooks/useConfiguration.tsx) merges API host, override configs, listeners, middleware
-- `StoreProvider` maintains runtime state
-- `TourContext` provides global access to the Tour instance
-
-### Middleware System
-
-The library supports a comprehensive **tracking middleware** system for analytics and monitoring:
-
-**Architecture**:
-
-- Middleware function passed to `initVisualizer({ middleware: (event) => {...} })`
-- `useActionMiddleware` hook provides `trackAction()` function to components
-- **35+ tracking actions** covering all user interactions
-- **Tracking-only** - does not block or cancel actions (fire-and-forget pattern)
-- Works independently of listeners (fires even without listeners configured)
-
-**Complete Coverage**:
-
-1. **Search & Discovery** - All category clicks, search, individual item clicks (products, POIs, features, etc.)
-2. **POI Detail Panel** - Open/close, action buttons (AI, Save, Audio, Share), tab switching, gallery clicks
-3. **Scenario Playback** - Play/pause, skip, loop, sound toggle, scenario selection
-4. **Navigation** - Scene groups, floorplan changes, minimap controls
-5. **UI Components** - Guide, playbar, all interactive elements
-
-**Key Features**:
-
-- **Deep-level tracking** - Tracks not just categories but individual items within each category
-- **Rich payloads** - Each event includes codes, names, types, and contextual data
-- **User journey mapping** - Complete visibility into user interactions from discovery to engagement
-- **Analytics-ready** - Designed for integration with GA4, Mixpanel, or custom backends
-
-**Documentation**:
-
-- 📚 **[Complete Tracking Guide](Planning/README-tracking-complete.md)** - Full reference of all 35+ tracking actions with examples
-- 📖 **[Middleware Architecture](Planning/README-middleware.md)** - Core middleware system documentation
-- 📝 **[Changes Summary](Planning/TRACKING-CHANGES-SUMMARY.md)** - List of all modified files and implementation details
-
-### Multi-language Support
-
-Uses `i18next` with JSON translation files in `src/assets/locales/{en,cn,jp,kr,vi}/` covering chatbot, common, guide, nav, onboarding-screen, and skin-layer namespaces.
-
-## Development Notes
-
-**TypeScript Paths**: Uses path aliases with `baseUrl: "./src"` so imports like `import { Tour } from 'models/Visualizer/Tour'` work without relative paths.
-
-**Rollup Build**: Configured for ESM output with PostCSS (Tailwind), TypeScript compilation, and tree-shaking. Development mode skips uglify/terser/babel for faster rebuilds.
-
-**CSS Architecture**: Mix of component-scoped CSS files (`src/assets/*.css`) and Tailwind utilities. Custom CSS variables set dynamically for modal positioning and hotspot states.
-
-**State Persistence**: No localStorage/sessionStorage - state is ephemeral per session. Tours are fetched fresh via SWR caching.
-
-**Mobile vs Desktop**: The `mobile` prop controls UI layout significantly - different slide-in behaviors, hotspot positioning, and touch controls.
-
-## Common Patterns
-
-**Finding POIs**: Use `tour.getPoiByType(POI_TYPE.*)` or `tour.getPoisByIds(ids)`
-
-**Scene Navigation**: `tour.changeScene(sceneCode)` or through navigation POIs
-
-**Coordinate Conversion**: Always use `krpano.screentosphere()` / `spheretoscreen()` for position calculations between screen and 3D space
-
-**Adding Listeners**: Tour emits signals for scene changes, POI interactions, scenario events - hook into these via `tour.signals.*`
-
-**ESLint Rules**: The project uses TypeScript ESLint with Prettier integration. Note that `no-console` allows `info`, `warn`, `error` but not plain `log`.
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a React-based 3D showroom visualizer library built with TypeScript that renders interactive 360-degree virtual tours. The library is published as `@clikvn/showroom-visualizer` and integrates with Krpano panoramic viewer technology to create immersive experiences with POIs (Points of Interest), scenarios, and multimedia content.
+
+## Build Commands
+
+```bash
+# Development with hot reload
+yarn dev
+
+# Production build
+yarn build
+
+# Linting
+yarn lint
+yarn lint:fix
+
+# Code formatting
+yarn prettier
+
+# Publish to npm
+yarn deploy  # Builds and publishes
+```
+
+## Code Architecture
+
+### Entry Points
+
+- `src/web.ts` - Main entry point that exports the visualizer API to `window.ShowroomVisualizer`
+- `src/window.ts` - Handles browser integration: `initVisualizer()` and `destroy()` methods
+- `src/features/ShowroomVisualizer/index.tsx` - Root React component that sets up providers and layout
+
+### Core Architecture Layers
+
+The codebase follows a layered architecture:
+
+1. **Visualizer Layer** (`src/models/Visualizer/`) - Domain models that manage 3D tour logic
+   - `Tour.ts` - Central orchestrator managing scenes, POIs, sounds, and scenarios
+   - `Krpano.ts` - Wrapper around Krpano API with coordinate transformation utilities
+   - `Scene.ts` - Individual 360° panorama scenes
+   - `Poi/` - Various POI types (Gallery, Info, Navigation, Multimedia, Texture, etc.)
+   - `TourScenario/` - Automated tour playback with actions (LookingAt, Moving, Rotation, Sleep, etc.)
+   - `Plugins/` - Gyro, Radar, Sound plugins
+
+2. **SkinLayer** (`src/components/SkinLayer/`) - React UI components
+   - Components overlay on the 3D viewer providing interactivity
+   - Key components: Floorplan/Minimap, HotspotOverview, PlayBar, SearchAndDiscovery, PoiDetailSlideIn
+   - Uses Ant Design components with custom styling
+
+3. **State Management** (`src/hooks/useStore.tsx`)
+   - Context-based global state management
+   - Manages UI state, active POIs, scenarios, galleries, slide-ins
+   - Provides selectors for component consumption
+
+4. **Services Layer** (`src/services/Visualizer/`)
+   - `tour.service.ts` - Fetches tour data from API
+   - `poi.service.ts` - POI-related API calls
+   - `webRotate.service.ts` - Web rotation functionality
+   - `request.ts` - HTTP client wrapper
+
+### Key Architectural Patterns
+
+**Krpano Integration**: The `Krpano` class wraps the Krpano viewer API and provides coordinate transformation utilities (`screentosphere`, `spheretoscreen`, `spheretospace`, `spacetosphere`). All 3D position calculations go through this abstraction.
+
+**POI System**: POIs are polymorphic with a base `Poi` class and specialized subtypes (PoiInfo, PoiGallery, PoiVideo, PoiSound, etc.). Each type handles its own rendering and interaction logic within the Krpano viewer.
+
+**Tour Scenario System**: Scenarios are composed of `TourScenarioStep` objects containing `TourScenarioAction` implementations. The `TourScenarioPlayer` executes actions sequentially (LookingAt → Moving → Rotation → Sleep patterns). Actions can have associated sounds managed by `ScenarioSound`.
+
+**Signal-based Events**: Uses the `signals` library extensively for decoupled event handling between Visualizer and SkinLayer.
+
+**Web Component Registration**: The library registers `<showroom-visualizer>` as a custom element (see `src/register.ts`) for easy embedding.
+
+### Configuration System
+
+Configuration flows through multiple layers:
+
+- External config passed to `initVisualizer()`
+- `ConfigurationProvider` (src/hooks/useConfiguration.tsx) merges API host, override configs, listeners, middleware
+- `StoreProvider` maintains runtime state
+- `TourContext` provides global access to the Tour instance
+
+### Middleware System
+
+The library supports a comprehensive **tracking middleware** system for analytics and monitoring:
+
+**Architecture**:
+
+- Middleware function passed to `initVisualizer({ middleware: (event) => {...} })`
+- `useActionMiddleware` hook provides `trackAction()` function to components
+- **35+ tracking actions** covering all user interactions
+- **Tracking-only** - does not block or cancel actions (fire-and-forget pattern)
+- Works independently of listeners (fires even without listeners configured)
+
+**Complete Coverage**:
+
+1. **Search & Discovery** - All category clicks, search, individual item clicks (products, POIs, features, etc.)
+2. **POI Detail Panel** - Open/close, action buttons (AI, Save, Audio, Share), tab switching, gallery clicks
+3. **Scenario Playback** - Play/pause, skip, loop, sound toggle, scenario selection
+4. **Navigation** - Scene groups, floorplan changes, minimap controls
+5. **UI Components** - Guide, playbar, all interactive elements
+
+**Key Features**:
+
+- **Deep-level tracking** - Tracks not just categories but individual items within each category
+- **Rich payloads** - Each event includes codes, names, types, and contextual data
+- **User journey mapping** - Complete visibility into user interactions from discovery to engagement
+- **Analytics-ready** - Designed for integration with GA4, Mixpanel, or custom backends
+
+**Documentation**:
+
+- 📚 **[Complete Tracking Guide](Planning/README-tracking-complete.md)** - Full reference of all 35+ tracking actions with examples
+- 📖 **[Middleware Architecture](Planning/README-middleware.md)** - Core middleware system documentation
+- 📝 **[Changes Summary](Planning/TRACKING-CHANGES-SUMMARY.md)** - List of all modified files and implementation details
+
+### Multi-language Support
+
+Uses `i18next` with JSON translation files in `src/assets/locales/{en,cn,jp,kr,vi}/` covering chatbot, common, guide, nav, onboarding-screen, and skin-layer namespaces.
+
+## Development Notes
+
+**TypeScript Paths**: Uses path aliases with `baseUrl: "./src"` so imports like `import { Tour } from 'models/Visualizer/Tour'` work without relative paths.
+
+**Rollup Build**: Configured for ESM output with PostCSS (Tailwind), TypeScript compilation, and tree-shaking. Development mode skips uglify/terser/babel for faster rebuilds.
+
+**CSS Architecture**: Mix of component-scoped CSS files (`src/assets/*.css`) and Tailwind utilities. Custom CSS variables set dynamically for modal positioning and hotspot states.
+
+**State Persistence**: No localStorage/sessionStorage - state is ephemeral per session. Tours are fetched fresh via SWR caching.
+
+**Mobile vs Desktop**: The `mobile` prop controls UI layout significantly - different slide-in behaviors, hotspot positioning, and touch controls.
+
+## Common Patterns
+
+**Finding POIs**: Use `tour.getPoiByType(POI_TYPE.*)` or `tour.getPoisByIds(ids)`
+
+**Scene Navigation**: `tour.changeScene(sceneCode)` or through navigation POIs
+
+**Coordinate Conversion**: Always use `krpano.screentosphere()` / `spheretoscreen()` for position calculations between screen and 3D space
+
+**Adding Listeners**: Tour emits signals for scene changes, POI interactions, scenario events - hook into these via `tour.signals.*`
+
+**ESLint Rules**: The project uses TypeScript ESLint with Prettier integration. Note that `no-console` allows `info`, `warn`, `error` but not plain `log`.

package/DEVELOPMENT.md

@@ -1,120 +1,120 @@
-# 🛠️ Development Guide
-
-Hướng dẫn phát triển thư viện `@clikvn/showroom-visualizer`.
-
-## 📦 Cấu trúc Project
-
-```
-showroom-visualizer/
-├── src/                    # Source code của thư viện
-├── dist/                   # Build output (NPM package & Web Component)
-├── example/                # Example app để test local (Vite + React)
-├── rollup.config.js        # Build configuration
-└── package.json
-```
-
-## 🚀 Development Workflows
-
-### Workflow 1: Test trong Example App (Khuyến nghị ⭐)
-
-**Ưu điểm:**
-- ✅ Import trực tiếp từ source (`src/`) - không cần build
-- ✅ Hot reload cực nhanh
-- ✅ Debug dễ dàng với source maps
-- ✅ Test custom layout overrides và tất cả features
-- ✅ Không cần publish hoặc yalc
-
-**Cách dùng:**
-
-```bash
-# Bước 1: Cài đặt dependencies cho example (chỉ lần đầu)
-cd example
-yarn install
-
-# Bước 2: Chạy example app
-yarn dev
-# hoặc từ root: yarn dev:demo
-
-# App sẽ chạy tại: http://localhost:3001
-```
-
-**Modify và test:**
-- Thay đổi code trong `src/` → Auto reload
-- Thay đổi code trong `example/src/App.tsx` → Auto reload
-- Test custom layout bằng checkbox trong UI
-
-### Workflow 2: Build và Test Web Component
-
-**Test Web Component:**
-
-```bash
-# Build
-yarn build
-
-# Serve dist folder
-cd dist
-npx serve
-# hoặc: python3 -m http.server 8080
-
-# Mở browser: http://localhost:8080
-```
-
-Xem file `dist/index.html` để biết cách dùng Web Component.
-
----
-
-## 🏗️ Build Strategy
-
-Thư viện này có **2 build outputs**:
-
-### 1. NPM Package (`dist/index.js`)
-- **Dùng cho:** React/Next.js apps
-- **React:** External (dùng React của project)
-- **Hỗ trợ:** Custom layout overrides, custom components
-- **Import:** 
-  ```tsx
-  import { ShowroomVisualizer } from '@clikvn/showroom-visualizer';
-  ```
-
-### 2. Web Component (`dist/web.js`)
-- **Dùng cho:** Vanilla HTML/JS
-- **React:** Bundled (React 18 đã được bundle sẵn)
-- **Không hỗ trợ:** Custom layout overrides
-- **Import:**
-  ```html
-  <script type="module" src="web.js"></script>
-  <showroom-visualizer api-url="..." showroom-id="..."></showroom-visualizer>
-  ```
-
----
-
-## 📝 Common Tasks
-
-### Thêm feature mới
-
-1. Code trong `src/`
-2. Test trong `example/` app
-3. Build: `yarn build`
-
-
-## 🐛 Troubleshooting
-
-### Build errors
-
-```bash
-# Clean và rebuild
-rm -rf dist
-yarn build
-```
----
-
-## ✨ Tips
-
-1. **Luôn dùng Example app khi develop** - Nhanh và tiện nhất
-2. **Commit example app vào git** để team members cùng dùng
-3. **Không commit `dist/` vào git** - Chỉ build khi deploy
-
----
-
-Happy coding! 🚀
-
+# 🛠️ Development Guide
+
+Hướng dẫn phát triển thư viện `@clikvn/showroom-visualizer`.
+
+## 📦 Cấu trúc Project
+
+```
+showroom-visualizer/
+├── src/                    # Source code của thư viện
+├── dist/                   # Build output (NPM package & Web Component)
+├── example/                # Example app để test local (Vite + React)
+├── rollup.config.js        # Build configuration
+└── package.json
+```
+
+## 🚀 Development Workflows
+
+### Workflow 1: Test trong Example App (Khuyến nghị ⭐)
+
+**Ưu điểm:**
+- ✅ Import trực tiếp từ source (`src/`) - không cần build
+- ✅ Hot reload cực nhanh
+- ✅ Debug dễ dàng với source maps
+- ✅ Test custom layout overrides và tất cả features
+- ✅ Không cần publish hoặc yalc
+
+**Cách dùng:**
+
+```bash
+# Bước 1: Cài đặt dependencies cho example (chỉ lần đầu)
+cd example
+yarn install
+
+# Bước 2: Chạy example app
+yarn dev
+# hoặc từ root: yarn dev:demo
+
+# App sẽ chạy tại: http://localhost:3001
+```
+
+**Modify và test:**
+- Thay đổi code trong `src/` → Auto reload
+- Thay đổi code trong `example/src/App.tsx` → Auto reload
+- Test custom layout bằng checkbox trong UI
+
+### Workflow 2: Build và Test Web Component
+
+**Test Web Component:**
+
+```bash
+# Build
+yarn build
+
+# Serve dist folder
+cd dist
+npx serve
+# hoặc: python3 -m http.server 8080
+
+# Mở browser: http://localhost:8080
+```
+
+Xem file `dist/index.html` để biết cách dùng Web Component.
+
+---
+
+## 🏗️ Build Strategy
+
+Thư viện này có **2 build outputs**:
+
+### 1. NPM Package (`dist/index.js`)
+- **Dùng cho:** React/Next.js apps
+- **React:** External (dùng React của project)
+- **Hỗ trợ:** Custom layout overrides, custom components
+- **Import:** 
+  ```tsx
+  import { ShowroomVisualizer } from '@clikvn/showroom-visualizer';
+  ```
+
+### 2. Web Component (`dist/web.js`)
+- **Dùng cho:** Vanilla HTML/JS
+- **React:** Bundled (React 18 đã được bundle sẵn)
+- **Không hỗ trợ:** Custom layout overrides
+- **Import:**
+  ```html
+  <script type="module" src="web.js"></script>
+  <showroom-visualizer api-url="..." showroom-id="..."></showroom-visualizer>
+  ```
+
+---
+
+## 📝 Common Tasks
+
+### Thêm feature mới
+
+1. Code trong `src/`
+2. Test trong `example/` app
+3. Build: `yarn build`
+
+
+## 🐛 Troubleshooting
+
+### Build errors
+
+```bash
+# Clean và rebuild
+rm -rf dist
+yarn build
+```
+---
+
+## ✨ Tips
+
+1. **Luôn dùng Example app khi develop** - Nhanh và tiện nhất
+2. **Commit example app vào git** để team members cùng dùng
+3. **Không commit `dist/` vào git** - Chỉ build khi deploy
+
+---
+
+Happy coding! 🚀
+