@clikvn/agent-widget-embedded 1.1.12-dev-01 → 1.1.12-dev-02

package/docs/brand-ui-command-actions-tools.md

@@ -1,269 +1,269 @@
-# UI Command Actions Tools Specification
-
-## Overview
-
-This document defines the available command action tools that AI agents can use to interact with virtual tour/showroom UI interfaces. These tools enable contextual, interactive responses within virtual environments.
-
-## Product Display Tools
-
-### 1. `show_hotspot_guided_tour`
-
-**Description:** Launches an interactive guided tour with hotspot interactions for the currently viewed product.
-
-**Parameters:**
-
-- `product_id` (string, required): The unique identifier of the product being viewed
-- `tour_type` (string, optional): Type of guided tour ("interactive", "auto", "manual"). Default: "interactive"
-- `start_hotspot` (string, optional): Starting hotspot identifier. Default: first available hotspot
-
-**Usage Context:** When user is viewing a specific product and wants detailed guided exploration with interactive hotspots.
-
-**Expected Behavior:**
-
-- Initiates guided tour overlay on current product view
-- Highlights interactive hotspots with contextual information
-- Provides step-by-step navigation through product features
-
----
-
-### 2. `show_product_AR`
-
-**Description:** Displays the currently viewed product in Augmented Reality mode, allowing users to visualize the product in their real environment.
-
-**Parameters:**
-
-- `product_id` (string, required): The unique identifier of the product being viewed
-- `ar_mode` (string, optional): AR display mode ("placement", "viewer", "try_on"). Default: "placement"
-- `scale_factor` (number, optional): Initial scale factor for AR display. Range: 0.1-5.0. Default: 1.0
-
-**Usage Context:** When user wants to see how a product would look in their actual space using device camera.
-
-**Expected Behavior:**
-
-- Activates device camera for AR visualization
-- Overlays 3D product model in real environment
-- Provides controls for scaling, rotation, and positioning
-
----
-
-### 3. `show_product_360_image`
-
-**Description:** Shows a 360-degree interactive view of the currently viewed product, allowing full rotation and detailed inspection.
-
-**Parameters:**
-
-- `product_id` (string, required): The unique identifier of the product being viewed
-- `initial_angle` (number, optional): Starting rotation angle in degrees. Range: 0-360. Default: 0
-- `auto_rotate` (boolean, optional): Whether to automatically rotate the product. Default: false
-- `rotation_speed` (number, optional): Auto-rotation speed if enabled. Range: 1-10. Default: 3
-
-**Usage Context:** When user needs comprehensive visual inspection of product from all angles.
-
-**Expected Behavior:**
-
-- Displays interactive 360° product viewer
-- Enables mouse/touch drag controls for manual rotation
-- Provides zoom capabilities for detailed inspection
-
----
-
-### 4. `show_product_image_gallery`
-
-**Description:** Opens a comprehensive image gallery for the currently viewed product, displaying multiple views, details, and lifestyle images.
-
-**Parameters:**
-
-- `product_id` (string, required): The unique identifier of the product being viewed
-- `gallery_type` (string, optional): Gallery display mode ("grid", "carousel", "lightbox"). Default: "lightbox"
-- `start_image` (number, optional): Index of initial image to display. Default: 0
-- `show_thumbnails` (boolean, optional): Whether to display thumbnail navigation. Default: true
-
-**Usage Context:** When user wants to see all available images and details of the product in a dedicated gallery view.
-
-**Expected Behavior:**
-
-- Opens full-screen or modal gallery interface
-- Displays high-resolution product images with navigation
-- Includes zoom functionality and image metadata
-
----
-
-### 5. `show_product_info`
-
-**Description:** Displays detailed product information including specifications, pricing, availability, and related details.
-
-**Parameters:**
-
-- `product_id` (string, required): The unique identifier of the product being viewed
-- `info_sections` (array, optional): Specific information sections to display. Options: ["specs", "pricing", "availability", "reviews", "related"]. Default: all sections
-- `display_mode` (string, optional): Information display format ("panel", "modal", "inline"). Default: "panel"
-
-**Usage Context:** When user needs comprehensive product details, specifications, or purchasing information.
-
-**Expected Behavior:**
-
-- Opens detailed product information panel or modal
-- Displays organized sections of product data
-- Includes interactive elements like reviews, related products
-
-## Scene Interaction Tools
-
-### 6. `change_room_style`
-
-**Description:** Modifies the visual style/theme of the current scene/room, allowing users to see different aesthetic presentations.
-
-**Parameters:**
-
-- `scene_id` (string, required): The unique identifier of the current scene
-- `style_theme` (string, required): The style theme to apply. Options: ["modern", "classic", "minimalist", "industrial", "scandinavian", "traditional"]
-- `apply_to_products` (boolean, optional): Whether to update product materials to match style. Default: true
-- `transition_effect` (boolean, optional): Whether to use animated transition. Default: true
-
-**Usage Context:** When user is in a scene and wants to explore different aesthetic styles or design themes.
-
-**Expected Behavior:**
-
-- Changes room colors, textures, and overall aesthetic
-- Updates lighting to match selected style
-- Optionally updates product finishes to complement new style
-
----
-
-### 7. `swap_product_material`
-
-**Description:** Changes materials, textures, or finishes of products within the current scene.
-
-**Parameters:**
-
-- `scene_id` (string, required): The unique identifier of the current scene
-- `product_id` (string, optional): Specific product to modify. If omitted, applies to all compatible products
-- `material_type` (string, required): Material to apply. Options: ["wood", "metal", "fabric", "leather", "glass", "stone", "ceramic"]
-- `material_variant` (string, optional): Specific variant of the material (e.g., "oak", "mahogany" for wood)
-- `finish` (string, optional): Surface finish. Options: ["matte", "glossy", "satin", "textured"]. Default: "satin"
-
-**Usage Context:** When user wants to see how different materials or finishes would look on products in the scene.
-
-**Expected Behavior:**
-
-- Updates product materials/textures in real-time
-- Maintains proper lighting and reflection properties
-- Shows realistic material appearance in current lighting conditions
-
----
-
-### 8. `open_close_door`
-
-**Description:** Toggles door states (open/closed) in the virtual environment to show different spatial configurations.
-
-**Parameters:**
-
-- `scene_id` (string, required): The unique identifier of the current scene
-- `door_id` (string, optional): Specific door to toggle. If omitted, cycles through available doors
-- `action` (string, required): Door action. Options: ["open", "close", "toggle"]
-- `animation_duration` (number, optional): Animation duration in milliseconds. Range: 100-2000. Default: 500
-
-**Usage Context:** When user is in a scene with doors/cabinets and wants to see different open/closed configurations.
-
-**Expected Behavior:**
-
-- Animates door opening/closing smoothly
-- Updates interior visibility and spatial perception
-- May reveal additional products or storage spaces
-
----
-
-### 9. `change_room_lighting`
-
-**Description:** Adjusts lighting conditions in the current scene to show different ambiances and times of day.
-
-**Parameters:**
-
-- `scene_id` (string, required): The unique identifier of the current scene
-- `lighting_preset` (string, required): Lighting configuration. Options: ["natural_day", "natural_evening", "warm_ambient", "bright_task", "dim_mood", "spotlight"]
-- `intensity` (number, optional): Light intensity level. Range: 0.1-2.0. Default: 1.0
-- `color_temperature` (number, optional): Color temperature in Kelvin. Range: 2700-6500. Default: 4000
-
-**Usage Context:** When user wants to see how the scene and products look under different lighting conditions.
-
-**Expected Behavior:**
-
-- Smoothly transitions between lighting conditions
-- Updates shadows, reflections, and material appearance
-- Shows realistic lighting effects on all scene elements
-
----
-
-### 10. `open_scene_product_list`
-
-**Description:** Displays a comprehensive list of all products present in the current scene with quick access options.
-
-**Parameters:**
-
-- `scene_id` (string, required): The unique identifier of the current scene
-- `list_format` (string, optional): List display format. Options: ["grid", "list", "carousel"]. Default: "grid"
-- `sort_by` (string, optional): Sorting criteria. Options: ["name", "price", "category", "popularity"]. Default: "category"
-- `show_details` (boolean, optional): Whether to show product details in list. Default: true
-- `enable_filtering` (boolean, optional): Whether to enable category/price filtering. Default: true
-
-**Usage Context:** When user wants to see and access all products available in the current scene.
-
-**Expected Behavior:**
-
-- Opens organized product list interface
-- Provides search and filtering capabilities
-- Allows quick navigation to specific products in scene
-
----
-
-### 11. `play_scene_guided_tour`
-
-**Description:** Starts an automated guided tour of the current scene, highlighting products and features with contextual information.
-
-**Parameters:**
-
-- `scene_id` (string, required): The unique identifier of the current scene
-- `tour_duration` (number, optional): Approximate tour duration in seconds. Range: 30-300. Default: 120
-- `focus_areas` (array, optional): Specific areas to highlight. Options: ["products", "features", "layout", "materials"]. Default: all areas
-- `narration` (boolean, optional): Whether to include audio narration. Default: false
-- `auto_advance` (boolean, optional): Whether to automatically advance between points. Default: true
-- `interaction_level` (string, optional): Level of interactivity. Options: ["passive", "interactive", "explorative"]. Default: "interactive"
-
-**Usage Context:** When user wants a comprehensive overview of the scene with guided exploration of key elements.
-
-**Expected Behavior:**
-
-- Initiates smooth camera movements around the scene
-- Highlights important products and features with overlays
-- Provides contextual information and interaction prompts
-
-## Implementation Notes
-
-### Parameter Validation
-
-- All required parameters must be validated before command execution
-- Optional parameters should use specified defaults when omitted
-- Invalid parameter values should return descriptive error messages
-
-### State Management
-
-- Commands should respect current UI state and user context
-- Multiple commands may be chained for complex interactions
-- State changes should be reversible where applicable
-
-### Performance Considerations
-
-- Commands involving 3D rendering (AR, 360°) should include loading states
-- Image-heavy operations should implement progressive loading
-- Animations should be optimized for smooth performance
-
-### Accessibility
-
-- All commands should support keyboard navigation alternatives
-- Visual changes should include appropriate ARIA labels
-- Motion-sensitive users should have reduced animation options
-
-### Error Handling
-
-- Commands should gracefully handle missing resources
-- Network-dependent features should have offline fallbacks
-- User feedback should be provided for long-running operations
+# UI Command Actions Tools Specification
+
+## Overview
+
+This document defines the available command action tools that AI agents can use to interact with virtual tour/showroom UI interfaces. These tools enable contextual, interactive responses within virtual environments.
+
+## Product Display Tools
+
+### 1. `show_hotspot_guided_tour`
+
+**Description:** Launches an interactive guided tour with hotspot interactions for the currently viewed product.
+
+**Parameters:**
+
+- `product_id` (string, required): The unique identifier of the product being viewed
+- `tour_type` (string, optional): Type of guided tour ("interactive", "auto", "manual"). Default: "interactive"
+- `start_hotspot` (string, optional): Starting hotspot identifier. Default: first available hotspot
+
+**Usage Context:** When user is viewing a specific product and wants detailed guided exploration with interactive hotspots.
+
+**Expected Behavior:**
+
+- Initiates guided tour overlay on current product view
+- Highlights interactive hotspots with contextual information
+- Provides step-by-step navigation through product features
+
+---
+
+### 2. `show_product_AR`
+
+**Description:** Displays the currently viewed product in Augmented Reality mode, allowing users to visualize the product in their real environment.
+
+**Parameters:**
+
+- `product_id` (string, required): The unique identifier of the product being viewed
+- `ar_mode` (string, optional): AR display mode ("placement", "viewer", "try_on"). Default: "placement"
+- `scale_factor` (number, optional): Initial scale factor for AR display. Range: 0.1-5.0. Default: 1.0
+
+**Usage Context:** When user wants to see how a product would look in their actual space using device camera.
+
+**Expected Behavior:**
+
+- Activates device camera for AR visualization
+- Overlays 3D product model in real environment
+- Provides controls for scaling, rotation, and positioning
+
+---
+
+### 3. `show_product_360_image`
+
+**Description:** Shows a 360-degree interactive view of the currently viewed product, allowing full rotation and detailed inspection.
+
+**Parameters:**
+
+- `product_id` (string, required): The unique identifier of the product being viewed
+- `initial_angle` (number, optional): Starting rotation angle in degrees. Range: 0-360. Default: 0
+- `auto_rotate` (boolean, optional): Whether to automatically rotate the product. Default: false
+- `rotation_speed` (number, optional): Auto-rotation speed if enabled. Range: 1-10. Default: 3
+
+**Usage Context:** When user needs comprehensive visual inspection of product from all angles.
+
+**Expected Behavior:**
+
+- Displays interactive 360° product viewer
+- Enables mouse/touch drag controls for manual rotation
+- Provides zoom capabilities for detailed inspection
+
+---
+
+### 4. `show_product_image_gallery`
+
+**Description:** Opens a comprehensive image gallery for the currently viewed product, displaying multiple views, details, and lifestyle images.
+
+**Parameters:**
+
+- `product_id` (string, required): The unique identifier of the product being viewed
+- `gallery_type` (string, optional): Gallery display mode ("grid", "carousel", "lightbox"). Default: "lightbox"
+- `start_image` (number, optional): Index of initial image to display. Default: 0
+- `show_thumbnails` (boolean, optional): Whether to display thumbnail navigation. Default: true
+
+**Usage Context:** When user wants to see all available images and details of the product in a dedicated gallery view.
+
+**Expected Behavior:**
+
+- Opens full-screen or modal gallery interface
+- Displays high-resolution product images with navigation
+- Includes zoom functionality and image metadata
+
+---
+
+### 5. `show_product_info`
+
+**Description:** Displays detailed product information including specifications, pricing, availability, and related details.
+
+**Parameters:**
+
+- `product_id` (string, required): The unique identifier of the product being viewed
+- `info_sections` (array, optional): Specific information sections to display. Options: ["specs", "pricing", "availability", "reviews", "related"]. Default: all sections
+- `display_mode` (string, optional): Information display format ("panel", "modal", "inline"). Default: "panel"
+
+**Usage Context:** When user needs comprehensive product details, specifications, or purchasing information.
+
+**Expected Behavior:**
+
+- Opens detailed product information panel or modal
+- Displays organized sections of product data
+- Includes interactive elements like reviews, related products
+
+## Scene Interaction Tools
+
+### 6. `change_room_style`
+
+**Description:** Modifies the visual style/theme of the current scene/room, allowing users to see different aesthetic presentations.
+
+**Parameters:**
+
+- `scene_id` (string, required): The unique identifier of the current scene
+- `style_theme` (string, required): The style theme to apply. Options: ["modern", "classic", "minimalist", "industrial", "scandinavian", "traditional"]
+- `apply_to_products` (boolean, optional): Whether to update product materials to match style. Default: true
+- `transition_effect` (boolean, optional): Whether to use animated transition. Default: true
+
+**Usage Context:** When user is in a scene and wants to explore different aesthetic styles or design themes.
+
+**Expected Behavior:**
+
+- Changes room colors, textures, and overall aesthetic
+- Updates lighting to match selected style
+- Optionally updates product finishes to complement new style
+
+---
+
+### 7. `swap_product_material`
+
+**Description:** Changes materials, textures, or finishes of products within the current scene.
+
+**Parameters:**
+
+- `scene_id` (string, required): The unique identifier of the current scene
+- `product_id` (string, optional): Specific product to modify. If omitted, applies to all compatible products
+- `material_type` (string, required): Material to apply. Options: ["wood", "metal", "fabric", "leather", "glass", "stone", "ceramic"]
+- `material_variant` (string, optional): Specific variant of the material (e.g., "oak", "mahogany" for wood)
+- `finish` (string, optional): Surface finish. Options: ["matte", "glossy", "satin", "textured"]. Default: "satin"
+
+**Usage Context:** When user wants to see how different materials or finishes would look on products in the scene.
+
+**Expected Behavior:**
+
+- Updates product materials/textures in real-time
+- Maintains proper lighting and reflection properties
+- Shows realistic material appearance in current lighting conditions
+
+---
+
+### 8. `open_close_door`
+
+**Description:** Toggles door states (open/closed) in the virtual environment to show different spatial configurations.
+
+**Parameters:**
+
+- `scene_id` (string, required): The unique identifier of the current scene
+- `door_id` (string, optional): Specific door to toggle. If omitted, cycles through available doors
+- `action` (string, required): Door action. Options: ["open", "close", "toggle"]
+- `animation_duration` (number, optional): Animation duration in milliseconds. Range: 100-2000. Default: 500
+
+**Usage Context:** When user is in a scene with doors/cabinets and wants to see different open/closed configurations.
+
+**Expected Behavior:**
+
+- Animates door opening/closing smoothly
+- Updates interior visibility and spatial perception
+- May reveal additional products or storage spaces
+
+---
+
+### 9. `change_room_lighting`
+
+**Description:** Adjusts lighting conditions in the current scene to show different ambiances and times of day.
+
+**Parameters:**
+
+- `scene_id` (string, required): The unique identifier of the current scene
+- `lighting_preset` (string, required): Lighting configuration. Options: ["natural_day", "natural_evening", "warm_ambient", "bright_task", "dim_mood", "spotlight"]
+- `intensity` (number, optional): Light intensity level. Range: 0.1-2.0. Default: 1.0
+- `color_temperature` (number, optional): Color temperature in Kelvin. Range: 2700-6500. Default: 4000
+
+**Usage Context:** When user wants to see how the scene and products look under different lighting conditions.
+
+**Expected Behavior:**
+
+- Smoothly transitions between lighting conditions
+- Updates shadows, reflections, and material appearance
+- Shows realistic lighting effects on all scene elements
+
+---
+
+### 10. `open_scene_product_list`
+
+**Description:** Displays a comprehensive list of all products present in the current scene with quick access options.
+
+**Parameters:**
+
+- `scene_id` (string, required): The unique identifier of the current scene
+- `list_format` (string, optional): List display format. Options: ["grid", "list", "carousel"]. Default: "grid"
+- `sort_by` (string, optional): Sorting criteria. Options: ["name", "price", "category", "popularity"]. Default: "category"
+- `show_details` (boolean, optional): Whether to show product details in list. Default: true
+- `enable_filtering` (boolean, optional): Whether to enable category/price filtering. Default: true
+
+**Usage Context:** When user wants to see and access all products available in the current scene.
+
+**Expected Behavior:**
+
+- Opens organized product list interface
+- Provides search and filtering capabilities
+- Allows quick navigation to specific products in scene
+
+---
+
+### 11. `play_scene_guided_tour`
+
+**Description:** Starts an automated guided tour of the current scene, highlighting products and features with contextual information.
+
+**Parameters:**
+
+- `scene_id` (string, required): The unique identifier of the current scene
+- `tour_duration` (number, optional): Approximate tour duration in seconds. Range: 30-300. Default: 120
+- `focus_areas` (array, optional): Specific areas to highlight. Options: ["products", "features", "layout", "materials"]. Default: all areas
+- `narration` (boolean, optional): Whether to include audio narration. Default: false
+- `auto_advance` (boolean, optional): Whether to automatically advance between points. Default: true
+- `interaction_level` (string, optional): Level of interactivity. Options: ["passive", "interactive", "explorative"]. Default: "interactive"
+
+**Usage Context:** When user wants a comprehensive overview of the scene with guided exploration of key elements.
+
+**Expected Behavior:**
+
+- Initiates smooth camera movements around the scene
+- Highlights important products and features with overlays
+- Provides contextual information and interaction prompts
+
+## Implementation Notes
+
+### Parameter Validation
+
+- All required parameters must be validated before command execution
+- Optional parameters should use specified defaults when omitted
+- Invalid parameter values should return descriptive error messages
+
+### State Management
+
+- Commands should respect current UI state and user context
+- Multiple commands may be chained for complex interactions
+- State changes should be reversible where applicable
+
+### Performance Considerations
+
+- Commands involving 3D rendering (AR, 360°) should include loading states
+- Image-heavy operations should implement progressive loading
+- Animations should be optimized for smooth performance
+
+### Accessibility
+
+- All commands should support keyboard navigation alternatives
+- Visual changes should include appropriate ARIA labels
+- Motion-sensitive users should have reduced animation options
+
+### Error Handling
+
+- Commands should gracefully handle missing resources
+- Network-dependent features should have offline fallbacks
+- User feedback should be provided for long-running operations