senangwebs-tour 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "senangwebs-tour",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "type": "module",
   "description": "VR 360° virtual tour system with visual editor and viewer library",
   "main": "dist/swt.js",

package/src/editor/js/data-transform.js

@@ -0,0 +1,42 @@
+/**
+ * Data Transform Utilities
+ * 
+ * With the unified format, editor and library use the same structure:
+ * - scenes: Array of scene objects with `panorama`
+ * - hotspots: nested properties (action, appearance, tooltip)
+ * 
+ * These utilities handle building the tour config for the SWT library.
+ */
+
+/**
+ * Build a complete tour configuration for the SWT library
+ * Since unified format is used, this just wraps the scenes array with config
+ * @param {Object} config - Config with initialSceneId, etc.
+ * @param {Array} scenes - Array of scenes (already in unified format)
+ * @returns {Object} Complete tour config
+ */
+export function buildTourConfig(config, scenes) {
+  // Determine initial scene
+  let initialScene = config.initialSceneId;
+  if (!initialScene && scenes && scenes.length > 0) {
+    initialScene = scenes[0].id;
+  }
+
+  return {
+    initialScene: initialScene,
+    scenes: scenes || [],
+  };
+}
+
+/**
+ * Build tour config for preview (sets initial scene to current scene)
+ * @param {Object} currentScene - The scene to show initially
+ * @param {Array} allScenes - All scenes for navigation support
+ * @returns {Object} Complete tour config
+ */
+export function buildPreviewTourConfig(currentScene, allScenes) {
+  return buildTourConfig(
+    { initialSceneId: currentScene.id },
+    allScenes
+  );
+}

package/src/editor/js/editor.js

@@ -55,8 +55,8 @@ class TourEditor {
         // Setup event listeners
         this.setupEventListeners();
         
-        // Populate icon grid
-        this.uiController.populateIconGrid();
+        // Populate icon grid (async to wait for custom element registration)
+        await this.uiController.populateIconGrid();
         
         // Load saved project if exists (but only if it has valid data)
         if (this.storageManager.hasProject()) {
@@ -149,19 +149,19 @@ class TourEditor {
         });
 
         document.getElementById('hotspotTitle')?.addEventListener('input', debounce((e) => {
-            this.updateCurrentHotspot('title', e.target.value);
+            this.updateCurrentHotspot('tooltip.text', e.target.value);
         }, 300));
         
         document.getElementById('hotspotDescription')?.addEventListener('input', debounce((e) => {
-            this.updateCurrentHotspot('description', e.target.value);
+            this.updateCurrentHotspot('tooltip.description', e.target.value);
         }, 300));
         
         document.getElementById('hotspotTarget')?.addEventListener('change', (e) => {
-            this.updateCurrentHotspot('targetSceneId', e.target.value);
+            this.updateCurrentHotspot('action.target', e.target.value);
         });
         
         document.getElementById('hotspotColor')?.addEventListener('input', (e) => {
-            this.updateCurrentHotspot('color', e.target.value);
+            this.updateCurrentHotspot('appearance.color', e.target.value);
         });
 
         // Icon grid button clicks
@@ -173,7 +173,7 @@ class TourEditor {
                 document.querySelectorAll('#hotspotIconGrid .icon-btn').forEach(b => b.classList.remove('active'));
                 btn.classList.add('active');
                 // Update hotspot
-                this.updateCurrentHotspot('icon', iconValue);
+                this.updateCurrentHotspot('appearance.icon', iconValue);
             }
         });
 
@@ -502,7 +502,8 @@ class TourEditor {
         const index = this.sceneManager.currentSceneIndex;
         if (index < 0) return;
         
-        if (this.sceneManager.updateScene(index, 'imageUrl', imageUrl)) {
+        // Use panorama for unified format
+        if (this.sceneManager.updateScene(index, 'panorama', imageUrl)) {
             const scene = this.sceneManager.getCurrentScene();
             if (scene) {
                 scene.thumbnail = imageUrl;
@@ -569,6 +570,7 @@ class TourEditor {
     render() {
         this.uiController.renderSceneList();
         this.uiController.renderHotspotList();
+        this.uiController.populateIconGrid(); // Re-render icon grid to ensure icons display
         
         const currentScene = this.sceneManager.getCurrentScene();
         const currentHotspot = this.hotspotEditor.getCurrentHotspot();

package/src/editor/js/export-manager.js

@@ -1,6 +1,7 @@
 // Export Manager - Handles JSON generation for SWT library
 import { downloadTextAsFile, showModal, copyToClipboard } from "./utils.js";
 import { IconRenderer } from "../../IconRenderer.js";
+import { buildTourConfig } from "./data-transform.js";
 
 class ExportManager {
   constructor(editor) {
@@ -11,75 +12,13 @@ class ExportManager {
   /**
    * Generate JSON compatible with SWT library
    * Follows the tourConfig structure from example-simple.html
+   * Uses shared data-transform utilities for consistent transformation
    */
   generateJSON() {
     const scenes = this.editor.sceneManager.getAllScenes();
     const config = this.editor.config;
 
-    // Build scenes object (keyed by scene ID)
-    const scenesData = {};
-    scenes.forEach((scene) => {
-      scenesData[scene.id] = {
-        name: scene.name,
-        panorama: scene.imageUrl,
-        hotspots: scene.hotspots.map((hotspot) => {
-          const hotspotData = {
-            position: hotspot.position,
-          };
-
-          // Add action based on hotspot type
-          if (hotspot.type === "navigation" && hotspot.targetSceneId) {
-            hotspotData.action = {
-              type: "navigateTo",
-              target: hotspot.targetSceneId,
-            };
-          } else if (hotspot.type === "info") {
-            hotspotData.action = {
-              type: "showInfo",
-            };
-          }
-
-          // Add appearance
-          hotspotData.appearance = {
-            color: hotspot.color || "#FF6B6B",
-            scale: hotspot.scale || "2 2 2",
-          };
-          
-          // Add icon if set
-          if (hotspot.icon) {
-            hotspotData.appearance.icon = hotspot.icon;
-          }
-
-          // Add tooltip if title exists
-          if (hotspot.title) {
-            hotspotData.tooltip = {
-              text: hotspot.title,
-            };
-          }
-
-          return hotspotData;
-        }),
-      };
-      
-      // Add starting position if set
-      if (scene.startingPosition) {
-        scenesData[scene.id].startingPosition = scene.startingPosition;
-      }
-    });
-
-    // Determine initial scene
-    let initialScene = config.initialSceneId;
-    if (!initialScene && scenes.length > 0) {
-      initialScene = scenes[0].id;
-    }
-
-    // Build final JSON matching SWT tourConfig format
-    const jsonData = {
-      initialScene: initialScene,
-      scenes: scenesData,
-    };
-
-    return jsonData;
+    return buildTourConfig(config, scenes);
   }
 
   /**
@@ -90,9 +29,8 @@ class ExportManager {
     const jsonData = this.generateJSON();
     
     // Process all scenes and convert icon names to data URLs
-    for (const sceneId of Object.keys(jsonData.scenes)) {
-      const scene = jsonData.scenes[sceneId];
-      
+    // Scenes are an array in unified format
+    for (const scene of jsonData.scenes) {
       for (let i = 0; i < scene.hotspots.length; i++) {
         const hotspot = scene.hotspots[i];
         const icon = hotspot.appearance?.icon;

package/src/editor/js/hotspot-editor.js

@@ -20,17 +20,24 @@ class HotspotEditor {
             return null;
         }
 
+        // Use unified library format with nested structure
         const hotspot = {
             id: generateId('hotspot'),
-            type: 'navigation',
             position: position,
-            cameraOrientation: cameraOrientation, // Store camera pitch/yaw for reliable pointing
-            targetSceneId: targetSceneId,
-            title: 'New Hotspot',
-            description: '',
-            color: '#00ff00',
-            icon: '',
-            scale: '1 1 1'
+            cameraOrientation: cameraOrientation,
+            action: {
+                type: 'navigateTo',
+                target: targetSceneId
+            },
+            appearance: {
+                color: '#00ff00',
+                scale: '1 1 1',
+                icon: ''
+            },
+            tooltip: {
+                text: 'New Hotspot',
+                description: ''
+            }
         };
 
         scene.hotspots.push(hotspot);
@@ -69,6 +76,7 @@ class HotspotEditor {
 
     /**
      * Update hotspot property
+     * Supports nested properties like 'appearance.color', 'action.target', 'tooltip.text'
      */
     updateHotspot(index, property, value) {
         const scene = this.editor.sceneManager.getCurrentScene();
@@ -76,7 +84,23 @@ class HotspotEditor {
             return false;
         }
 
-        scene.hotspots[index][property] = value;
+        const hotspot = scene.hotspots[index];
+        
+        // Handle nested properties (e.g., 'appearance.color')
+        if (property.includes('.')) {
+            const parts = property.split('.');
+            let obj = hotspot;
+            for (let i = 0; i < parts.length - 1; i++) {
+                if (!obj[parts[i]]) {
+                    obj[parts[i]] = {};
+                }
+                obj = obj[parts[i]];
+            }
+            obj[parts[parts.length - 1]] = value;
+        } else {
+            hotspot[property] = value;
+        }
+        
         return true;
     }
 
@@ -143,7 +167,9 @@ class HotspotEditor {
         const original = scene.hotspots[index];
         const duplicate = deepClone(original);
         duplicate.id = generateId('hotspot');
-        duplicate.title = original.title + ' (Copy)';
+        if (duplicate.tooltip) {
+            duplicate.tooltip.text = (original.tooltip?.text || 'Hotspot') + ' (Copy)';
+        }
         
         // Offset position slightly
         duplicate.position = {

package/src/editor/js/preview-controller.js

@@ -1,5 +1,6 @@
 // Preview Controller - Manages A-Frame preview integration using SWT library
 import { showToast } from "./utils.js";
+import { buildPreviewTourConfig } from "./data-transform.js";
 
 class PreviewController {
   constructor(editor) {
@@ -49,14 +50,16 @@ class PreviewController {
 
   /**
    * Load scene into preview using SWT library
+   * Scenes and hotspots now use unified library format directly
    */
   async loadScene(scene, preserveCameraRotation = true) {
     if (!this.isInitialized || !scene) {
       return;
     }
 
-    // Validate scene has required data
-    if (!scene.imageUrl || !scene.id) {
+    // Validate scene has required data (panorama or imageUrl for backward compatibility)
+    const panoramaUrl = scene.panorama || scene.imageUrl;
+    if (!panoramaUrl || !scene.id) {
       console.error("Invalid scene data:", scene);
       return;
     }
@@ -122,67 +125,10 @@ class PreviewController {
     // Give A-Frame a moment to start initializing before we proceed
     await new Promise((resolve) => setTimeout(resolve, 100));
 
-    // Build tour config for this single scene
-    // Transform editor scene format to library format
-    const transformedHotspots = (scene.hotspots || []).map((h) => ({
-      id: h.id,
-      position: h.position,
-      action: {
-        type: h.type === "navigation" ? "navigateTo" : h.type,
-        target: h.targetSceneId,
-      },
-      appearance: {
-        color: h.color || "#00ff00",
-        icon: h.icon || null,
-        scale: h.scale || "1 1 1",
-      },
-      tooltip: {
-        text: h.title || "Hotspot",
-      },
-    }));
-
-    const libraryScene = {
-      id: scene.id,
-      name: scene.name,
-      panorama: scene.imageUrl, // Editor uses 'imageUrl', library expects 'panorama'
-      hotspots: transformedHotspots,
-    };
-
-    // Build scenes object with ALL scenes (for navigation to work)
-    const allScenes = {};
+    // Build tour config using shared transform utilities
+    // This includes ALL scenes for navigation support
     const editorScenes = this.editor.sceneManager.scenes || [];
-    editorScenes.forEach((s) => {
-      const sceneHotspots = (s.hotspots || []).map((h) => ({
-        id: h.id,
-        position: h.position,
-        action: {
-          type: h.type === "navigation" ? "navigateTo" : h.type,
-          target: h.targetSceneId,
-        },
-        appearance: {
-          color: h.color || "#00ff00",
-          icon: h.icon || null,
-          scale: h.scale || "1 1 1",
-        },
-        tooltip: {
-          text: h.title || "Hotspot",
-        },
-      }));
-
-      allScenes[s.id] = {
-        id: s.id,
-        name: s.name,
-        panorama: s.imageUrl,
-        hotspots: sceneHotspots,
-        startingPosition: s.startingPosition || null,
-      };
-    });
-
-    const tourConfig = {
-      title: scene.name,
-      initialScene: scene.id,
-      scenes: allScenes,
-    };
+    const tourConfig = buildPreviewTourConfig(scene, editorScenes);
 
     try {
       // Create new tour instance

package/src/editor/js/scene-manager.js

@@ -18,7 +18,7 @@ class SceneManagerEditor {
    * @param {File|Object} fileOrConfig - Either a File object or a scene config object
    * @param {string} fileOrConfig.id - Scene ID (if config object)
    * @param {string} fileOrConfig.name - Scene name (if config object)
-   * @param {string} fileOrConfig.imageUrl - Image URL (if config object)
+   * @param {string} fileOrConfig.panorama - Panorama URL (if config object)
    * @param {string} fileOrConfig.thumbnail - Thumbnail URL (if config object)
    * @param {Array} fileOrConfig.hotspots - Hotspots array (if config object)
    */
@@ -35,17 +35,17 @@ class SceneManagerEditor {
         scene = {
           id: sanitizeId(fileOrConfig.name.replace(/\.[^/.]+$/, "")),
           name: fileOrConfig.name.replace(/\.[^/.]+$/, ""),
-          imageUrl: imageDataUrl,
+          panorama: imageDataUrl,
           thumbnail: thumbnail,
           hotspots: [],
         };
       } else if (typeof fileOrConfig === "object" && fileOrConfig !== null) {
-        // Handle config object with URL strings
+        // Handle config object - support both panorama and imageUrl for backward compatibility
         scene = {
           id: fileOrConfig.id || sanitizeId(`scene-${Date.now()}`),
           name: fileOrConfig.name || "Untitled Scene",
-          imageUrl: fileOrConfig.imageUrl || "",
-          thumbnail: fileOrConfig.thumbnail || fileOrConfig.imageUrl || "",
+          panorama: fileOrConfig.panorama || fileOrConfig.imageUrl || "",
+          thumbnail: fileOrConfig.thumbnail || fileOrConfig.panorama || fileOrConfig.imageUrl || "",
           hotspots: fileOrConfig.hotspots || [],
           ...(fileOrConfig.startingPosition && { startingPosition: fileOrConfig.startingPosition }),
         };
@@ -115,12 +115,13 @@ class SceneManagerEditor {
     if (index >= 0 && index < this.scenes.length) {
       this.scenes[index][property] = value;
 
-      // If updating ID, update all hotspot target references
+      // If updating ID, update all hotspot target references (uses nested action.target)
       if (property === "id") {
+        const oldId = this.scenes[index].id;
         this.scenes.forEach((scene) => {
           scene.hotspots.forEach((hotspot) => {
-            if (hotspot.targetSceneId === this.scenes[index].id) {
-              hotspot.targetSceneId = value;
+            if (hotspot.action?.target === oldId) {
+              hotspot.action.target = value;
             }
           });
         });

package/src/editor/js/storage-manager.js

@@ -78,8 +78,10 @@ class ProjectStorageManager {
         return false;
       }
 
-      // imageUrl is required for scenes to be valid
-      if (!scene.imageUrl || typeof scene.imageUrl !== "string") {
+      // panorama or imageUrl is required for scenes to be valid (support both formats)
+      const hasImage = (scene.panorama && typeof scene.panorama === "string") ||
+                       (scene.imageUrl && typeof scene.imageUrl === "string");
+      if (!hasImage) {
         return false;
       }
 

package/src/editor/js/ui-controller.js

@@ -53,9 +53,9 @@ class UIController {
     dragHandle.innerHTML =
       '<ss-icon icon="arrow-up-down-left-right" thickness="2.2"></ss-icon>';
 
-    // Thumbnail
+    // Thumbnail - use thumbnail, panorama, or imageUrl (backward compatibility)
     const thumbnail = document.createElement("img");
-    thumbnail.src = scene.thumbnail || scene.imageUrl;
+    thumbnail.src = scene.thumbnail || scene.panorama || scene.imageUrl;
     thumbnail.alt = scene.name;
 
     // Info
@@ -187,18 +187,25 @@ class UIController {
 
   /**
    * Create hotspot list item
+   * Uses unified format with nested appearance, action, and tooltip
    */
   createHotspotItem(hotspot, index, isActive) {
     const item = document.createElement("div");
     item.className = "hotspot-item" + (isActive ? " active" : "");
 
+    // Get values from nested structure
+    const color = hotspot.appearance?.color || "#00ff00";
+    const icon = hotspot.appearance?.icon || "";
+    const title = hotspot.tooltip?.text || "Untitled Hotspot";
+    const targetSceneId = hotspot.action?.target || "";
+
     const colorIndicator = document.createElement("div");
     colorIndicator.className = "hotspot-color";
-    colorIndicator.style.backgroundColor = hotspot.color;
+    colorIndicator.style.backgroundColor = color;
     
     // If hotspot has an icon, show it with the color applied
-    if (hotspot.icon) {
-      colorIndicator.innerHTML = `<ss-icon icon="${hotspot.icon}" thickness="2.2" style="color: ${hotspot.color}; width: 20px; height: 20px;"></ss-icon>`;
+    if (icon) {
+      colorIndicator.innerHTML = `<ss-icon icon="${icon}" thickness="2.2" style="color: ${color}; width: 20px; height: 20px;"></ss-icon>`;
       colorIndicator.style.backgroundColor = "transparent";
       colorIndicator.style.display = "flex";
       colorIndicator.style.alignItems = "center";
@@ -208,24 +215,24 @@ class UIController {
     const info = document.createElement("div");
     info.className = "hotspot-info";
 
-    const title = document.createElement("div");
-    title.className = "hotspot-title";
-    title.textContent = hotspot.title || "Untitled Hotspot";
+    const titleEl = document.createElement("div");
+    titleEl.className = "hotspot-title";
+    titleEl.textContent = title;
 
     const target = document.createElement("div");
     target.className = "hotspot-target";
-    if (hotspot.targetSceneId) {
+    if (targetSceneId) {
       const targetScene = this.editor.sceneManager.getSceneById(
-        hotspot.targetSceneId
+        targetSceneId
       );
       target.textContent = targetScene
         ? `→ ${targetScene.name}`
-        : `→ ${hotspot.targetSceneId}`;
+        : `→ ${targetSceneId}`;
     } else {
       target.textContent = "No target";
     }
 
-    info.appendChild(title);
+    info.appendChild(titleEl);
     info.appendChild(target);
 
     const actions = document.createElement("div");
@@ -274,11 +281,27 @@ class UIController {
 
   /**
    * Populate icon grid from SenangStart icons (baked in at build time)
+   * Waits for ss-icon custom element to be defined to avoid race conditions
    */
-  populateIconGrid() {
+  async populateIconGrid() {
     const grid = document.getElementById("hotspotIconGrid");
     if (!grid) return;
 
+    // Wait for ss-icon custom element to be defined before populating
+    // This prevents race conditions where icons don't render if the
+    // custom element isn't registered yet when this method runs
+    try {
+      if (customElements.get('ss-icon') === undefined) {
+        // Give a reasonable timeout to avoid infinite waiting
+        await Promise.race([
+          customElements.whenDefined('ss-icon'),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('ss-icon timeout')), 5000))
+        ]);
+      }
+    } catch (err) {
+      console.warn('ss-icon custom element not available, icon grid may not render properly:', err.message);
+    }
+
     // Clear existing content
     grid.innerHTML = "";
 
@@ -307,6 +330,7 @@ class UIController {
 
   /**
    * Update properties panel for hotspot
+   * Uses unified format with nested appearance, action, and tooltip
    */
   updateHotspotProperties(hotspot) {
     const hotspotAll = document.getElementById("hotspotAll");
@@ -336,21 +360,26 @@ class UIController {
     if (hotspotAll) hotspotAll.style.display = "block";
     if (hotspotProperties) hotspotProperties.style.display = "block";
 
-    document.getElementById("hotspotTitle").value = hotspot.title || "";
-    document.getElementById("hotspotDescription").value =
-      hotspot.description || "";
-    document.getElementById("hotspotTarget").value =
-      hotspot.targetSceneId || "";
-    document.getElementById("hotspotColor").value = hotspot.color || "#00ff00";
+    // Get values from nested structure
+    const title = hotspot.tooltip?.text || "";
+    const description = hotspot.tooltip?.description || "";
+    const targetSceneId = hotspot.action?.target || "";
+    const color = hotspot.appearance?.color || "#00ff00";
+    const icon = hotspot.appearance?.icon || "";
+
+    document.getElementById("hotspotTitle").value = title;
+    document.getElementById("hotspotDescription").value = description;
+    document.getElementById("hotspotTarget").value = targetSceneId;
+    document.getElementById("hotspotColor").value = color;
 
     // Update color text input if it exists
     const colorText = document.getElementById("hotspotColorText");
     if (colorText) {
-      colorText.value = hotspot.color || "#00ff00";
+      colorText.value = color;
     }
 
     // Update icon grid active button
-    this.setActiveIconButton(hotspot.icon || "");
+    this.setActiveIconButton(icon);
 
     // Update position inputs
     const pos = hotspot.position || { x: 0, y: 0, z: 0 };
@@ -380,7 +409,8 @@ class UIController {
 
     document.getElementById("sceneId").value = scene.id || "";
     document.getElementById("sceneName").value = scene.name || "";
-    document.getElementById("sceneImageUrl").value = scene.imageUrl || "";
+    // Support both panorama (unified) and imageUrl (legacy)
+    document.getElementById("sceneImageUrl").value = scene.panorama || scene.imageUrl || "";
     
     // Update starting position display
     if (startingPosDisplay) {

package/src/index.js

@@ -30,6 +30,9 @@ class Tour {
     this.config = tourConfig;
     this.isStarted = false;
 
+    // Normalize scenes to array format (backward compatibility with object format)
+    this.scenesArray = this.normalizeScenesArray(tourConfig.scenes);
+
     // Initialize managers
     this.assetManager = new AssetManager(this.sceneEl);
     this.sceneManager = new SceneManager(this.sceneEl, this.assetManager);
@@ -54,6 +57,32 @@ class Tour {
     this.ensureCursor();
   }
 
+  /**
+   * Normalize scenes to array format
+   * Supports both array and object (keyed by ID) formats for backward compatibility
+   * @param {Array|Object} scenes - Scenes in either format
+   * @returns {Array} - Scenes as array with id property
+   */
+  normalizeScenesArray(scenes) {
+    if (Array.isArray(scenes)) {
+      return scenes;
+    }
+    // Convert object format to array format
+    return Object.entries(scenes).map(([id, sceneData]) => ({
+      id,
+      ...sceneData,
+    }));
+  }
+
+  /**
+   * Get scene data by ID
+   * @param {string} sceneId - The scene ID to find
+   * @returns {Object|undefined} - Scene data or undefined if not found
+   */
+  getSceneById(sceneId) {
+    return this.scenesArray.find((scene) => scene.id === sceneId);
+  }
+
   /**
    * Ensure the scene has a cursor for interaction
    */
@@ -81,7 +110,7 @@ class Tour {
     }
 
     const initialSceneId = this.config.initialScene;
-    const initialSceneData = this.config.scenes[initialSceneId];
+    const initialSceneData = this.getSceneById(initialSceneId);
 
     if (!initialSceneData) {
       throw new Error(
@@ -123,7 +152,7 @@ class Tour {
    * @returns {Promise}
    */
   async navigateTo(sceneId) {
-    const sceneData = this.config.scenes[sceneId];
+    const sceneData = this.getSceneById(sceneId);
 
     if (!sceneData) {
       throw new Error(`Scene "${sceneId}" not found in tour configuration`);