@clikvn/showroom-visualizer 0.3.0-dev-05 → 0.3.0-dev-07

package/CLAUDE.md

@@ -0,0 +1,140 @@
+# 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 **tracking middleware** system for analytics and monitoring:
+
+**Architecture**:
+
+- Middleware function passed to `initVisualizer({ middleware: (event) => {...} })`
+- `useActionMiddleware` hook provides `trackAction()` function to components
+- Tracks 12 action types across UI layer and Krpano/POI layer
+- **Tracking-only** - does not block or cancel actions (fire-and-forget pattern)
+- Works independently of listeners (fires even without listeners configured)
+
+**Implementation Locations**:
+
+1. **UI Components** (`src/components/SkinLayer/`)
+   - `PinActionButtons` - Pin action clicks
+   - `SceneCategories` - Scene navigation
+   - `TourScenarios` - Scenario playback
+   - `HotspotOverview` - View more, gallery, texture interactions
+
+2. **Krpano/POI Layer** (`src/hooks/Visualizer/useTourVisualizer.ts`)
+   - POI clicks, moving POI, texture POI
+   - Background sound toggle
+   - Function button opens
+   - Minimap fullscreen toggle
+
+**See**: `Planning/README-middleware.md` for complete documentation with all tracked actions and usage examples.
+
+### 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`.