Update app.py

app.py

@@ -1,4 +1,4 @@
-# app.py (Re-integrated WebSockets for 3D Sync)
+# app.py (Re-integrated WebSockets for 3D Sync - Cleaned)
 import streamlit as st
 import asyncio
 import websockets # Re-added
@@ -28,11 +28,20 @@ from streamlit_js_eval import streamlit_js_eval # Keep for UI interaction if nee
 from PIL import Image
 
 # ==============================================================================
-# Configuration & Constants
+# 1. ⚙️ Configuration & Constants
 # ==============================================================================
-st.set_page_config(page_title="🏗️ Live World Builder ⚡", page_icon="🏗️", layout="wide", initial_sidebar_state="expanded")
+
+# 🛠️ Patch asyncio for nesting
 nest_asyncio.apply()
 
+# 🎨 Page Config
+st.set_page_config(
+    page_title="🏗️ Live World Builder ⚡",
+    page_icon="🏗️",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
 # General Constants
 Site_Name = '🏗️ Live World Builder ⚡'
 MEDIA_DIR = "."
@@ -81,42 +90,78 @@ clients_lock = threading.Lock()
 connected_clients = set() # Holds client_id strings (websocket.id)
 
 # ==============================================================================
-# Utility Functions (Keep relevant ones)
+# 2. ✨ Utility Functions
 # ==============================================================================
 def get_current_time_str(tz='UTC'):
-    try: timezone = pytz.timezone(tz); now_aware = datetime.now(timezone)
-    except Exception: now_aware = datetime.now(pytz.utc)
+    """Gets formatted timestamp string in specified timezone (default UTC)."""
+    try:
+        timezone = pytz.timezone(tz)
+        now_aware = datetime.now(timezone)
+    except pytz.UnknownTimeZoneError:
+        now_aware = datetime.now(pytz.utc)
+    except Exception as e:
+        print(f"❌ Timezone error ({tz}), using UTC. Error: {e}")
+        now_aware = datetime.now(pytz.utc)
     return now_aware.strftime('%Y%m%d_%H%M%S')
 
 def clean_filename_part(text, max_len=25):
+    """Cleans a string part for use in a filename."""
     if not isinstance(text, str): text = "invalid_name"
-    text = re.sub(r'\s+', '_', text); text = re.sub(r'[^\w\-.]', '', text)
+    text = re.sub(r'\s+', '_', text)
+    text = re.sub(r'[^\w\-.]', '', text)
     return text[:max_len]
 
 def run_async(async_func, *args, **kwargs):
     """Runs an async function safely from a sync context using create_task or asyncio.run."""
-    try: loop = asyncio.get_running_loop(); return loop.create_task(async_func(*args, **kwargs))
+    try:
+        loop = asyncio.get_running_loop()
+        return loop.create_task(async_func(*args, **kwargs))
     except RuntimeError:
         try: return asyncio.run(async_func(*args, **kwargs))
         except Exception as e: print(f"❌ Error run_async new loop: {e}"); return None
     except Exception as e: print(f"❌ Error run_async schedule task: {e}"); return None
 
-def ensure_dir(dir_path): os.makedirs(dir_path, exist_ok=True)
+def ensure_dir(dir_path):
+    """Creates directory if it doesn't exist."""
+    os.makedirs(dir_path, exist_ok=True)
 
 # ==============================================================================
-# World State Manager (Using st.cache_resource)
+# 3. 🌍 World State Manager (Using st.cache_resource)
 # ==============================================================================
 
-# Function to load initial state from the most recent file
-# Separated from the cache resource function itself
+def get_saved_worlds(): # Define this before it's used in load_initial_world_from_file
+    """Scans the saved worlds directory for world MD files and parses them."""
+    try:
+        ensure_dir(SAVED_WORLDS_DIR);
+        world_files = glob.glob(os.path.join(SAVED_WORLDS_DIR, f"{WORLD_STATE_FILE_MD_PREFIX}*.md"))
+        parsed_worlds = [parse_world_filename(f) for f in world_files] # parse_world_filename needs to be defined below
+        parsed_worlds.sort(key=lambda x: x.get('dt') if x.get('dt') else datetime.min.replace(tzinfo=pytz.utc), reverse=True)
+        return parsed_worlds
+    except Exception as e: print(f"❌ Error scanning saved worlds: {e}"); st.error(f"Could not scan saved worlds: {e}"); return []
+
+def parse_world_filename(filename): # Define this before get_saved_worlds uses it indirectly via load_initial
+    """Extracts info from filename if possible, otherwise returns defaults."""
+    basename = os.path.basename(filename)
+    if basename.startswith(WORLD_STATE_FILE_MD_PREFIX) and basename.endswith(".md"):
+        core = basename[len(WORLD_STATE_FILE_MD_PREFIX):-3]; parts = core.split('_')
+        if len(parts) >= 5 and parts[-3] == "by":
+            timestamp_str = parts[-2]; username = parts[-4]; world_name = " ".join(parts[:-4]); dt_obj = None
+            try: dt_obj = pytz.utc.localize(datetime.strptime(timestamp_str, '%Y%m%d_%H%M%S'))
+            except Exception: dt_obj = None
+            return {"name": world_name or "Untitled", "user": username, "timestamp": timestamp_str, "dt": dt_obj, "filename": filename}
+    # Fallback
+    dt_fallback = None; try: mtime = os.path.getmtime(filename); dt_fallback = datetime.fromtimestamp(mtime, tz=pytz.utc)
+    except Exception: pass
+    return {"name": basename.replace('.md','').replace(WORLD_STATE_FILE_MD_PREFIX, ''), "user": "Unknown", "timestamp": "Unknown", "dt": dt_fallback, "filename": filename}
+
 def load_initial_world_from_file():
     """Loads the state from the most recent MD file found."""
-    print(f"[{time.time():.1f}] Attempting to load initial world state from files...")
+    print(f"[{time.time():.1f}] ⏳ Attempting to load initial world state from files...")
     loaded_state = defaultdict(dict)
-    saved_worlds = get_saved_worlds() # Assumes get_saved_worlds is defined below
+    saved_worlds = get_saved_worlds()
     if saved_worlds:
         latest_world_file_basename = os.path.basename(saved_worlds[0]['filename'])
-        print(f"Found most recent file: {latest_world_file_basename}")
+        print(f"⏳ Found most recent file: {latest_world_file_basename}")
         load_path = os.path.join(SAVED_WORLDS_DIR, latest_world_file_basename)
         if os.path.exists(load_path):
             try:
@@ -125,11 +170,13 @@ def load_initial_world_from_file():
                 if json_match:
                     world_data_dict = json.loads(json_match.group(1))
                     for k, v in world_data_dict.items(): loaded_state[str(k)] = v
-                    print(f"Successfully loaded {len(loaded_state)} objects for initial state.")
-                else: print("No JSON block found in initial file.")
-            except Exception as e: print(f"Error parsing initial world file {latest_world_file_basename}: {e}")
-        else: print(f"Most recent file {latest_world_file_basename} not found at path {load_path}.")
-    else: print("No saved world files found to load initial state.")
+                    print(f"✅ Successfully loaded {len(loaded_state)} objects for initial state.")
+                    # Store the initially loaded file basename in session state here?
+                    st.session_state._initial_world_file_loaded = latest_world_file_basename
+                else: print("⚠️ No JSON block found in initial file.")
+            except Exception as e: print(f"❌ Error parsing initial world file {latest_world_file_basename}: {e}")
+        else: print(f"⚠️ Most recent file {latest_world_file_basename} not found at path {load_path}.")
+    else: print("🌫️ No saved world files found to load initial state.")
     return loaded_state
 
 @st.cache_resource(ttl=3600) # Cache resource for 1 hour
@@ -138,20 +185,12 @@ def get_world_state_manager():
     Initializes and returns the shared world state dictionary and its lock.
     Loads initial state from the most recent file on first creation.
     """
-    print(f"[{time.time():.1f}] --- Initializing/Retrieving Shared World State Resource ---")
+    print(f"[{time.time():.1f}] --- ✨ Initializing/Retrieving Shared World State Resource ---")
     manager = {
         "lock": threading.Lock(),
         "state": load_initial_world_from_file() # Load initial state here
     }
-    # Set initial current_world_file if state was loaded successfully
-    if manager["state"]:
-         saved_worlds = get_saved_worlds()
-         if saved_worlds:
-              latest_world_file_basename = os.path.basename(saved_worlds[0]['filename'])
-              if 'current_world_file' not in st.session_state: # Initialize only if not set
-                   st.session_state.current_world_file = latest_world_file_basename
-                   print(f"Set initial current_world_file state to: {latest_world_file_basename}")
-
+    # Initial current_world_file is now handled after init_session_state in main logic
     return manager
 
 def get_current_world_state_copy():
@@ -161,7 +200,7 @@ def get_current_world_state_copy():
         return dict(manager["state"]) # Return a copy
 
 # ==============================================================================
-# World State File Handling (Refactored for Cached State)
+# 4. 💾 World State File Handling (Save/Load - Refactored for Cached State)
 # ==============================================================================
 def generate_world_save_filename(username="User", world_name="World"):
     timestamp = get_current_time_str(); clean_user = clean_filename_part(username, 15);
@@ -169,50 +208,14 @@ def generate_world_save_filename(username="User", world_name="World"):
     rand_hash = hashlib.md5(str(time.time()).encode()+username.encode()+world_name.encode()).hexdigest()[:4]
     return f"{WORLD_STATE_FILE_MD_PREFIX}{clean_world}_by_{clean_user}_{timestamp}_{rand_hash}.md"
 
-def parse_world_filename(filename):
-    """Extracts info from filename if possible, otherwise returns defaults."""
-    basename = os.path.basename(filename)
-    # Check prefix and suffix
-    if basename.startswith(WORLD_STATE_FILE_MD_PREFIX) and basename.endswith(".md"):
-        core_name = basename[len(WORLD_STATE_FILE_MD_PREFIX):-3]
-        parts = core_name.split('_')
-        # Check if structure matches Name_by_User_Timestamp_Hash
-        if len(parts) >= 5 and parts[-3] == "by":
-            timestamp_str = parts[-2]
-            username = parts[-4]
-            world_name = " ".join(parts[:-4]) # Join potential name parts
-            dt_obj = None
-            try: # Try parsing timestamp
-                dt_obj = datetime.strptime(timestamp_str, '%Y%m%d_%H%M%S')
-                dt_obj = pytz.utc.localize(dt_obj) # Assume UTC
-            except (ValueError, pytz.exceptions.AmbiguousTimeError, pytz.exceptions.NonExistentTimeError):
-                dt_obj = None # Parsing failed
-            # Return result if standard format parsed okay
-            return {"name": world_name or "Untitled", "user": username, "timestamp": timestamp_str, "dt": dt_obj, "filename": filename}
-
-    # Fallback for unknown format or if parsing above failed
-    # print(f"Using fallback parsing for filename: {basename}") # Debug log
-    dt_fallback = None # Initialize on its own line
-    try: # Start try block on its own line
-        # Indented block under try
-        mtime = os.path.getmtime(filename)
-        dt_fallback = datetime.fromtimestamp(mtime, tz=pytz.utc)
-    except Exception: # Except aligned with try
-        # Indented block under except
-        pass # Ignore errors getting mtime
-    # Return statement aligned with the function's fallback logic scope
-    return {"name": basename.replace('.md','').replace(WORLD_STATE_FILE_MD_PREFIX, ''), "user": "Unknown", "timestamp": "Unknown", "dt": dt_fallback, "filename": filename}
-
-    
-
 def save_world_state_to_md(target_filename_base):
     """Saves the current cached world state to a specific MD file."""
-    manager = get_world_state_manager() # Get resource
+    manager = get_world_state_manager()
     save_path = os.path.join(SAVED_WORLDS_DIR, target_filename_base)
     print(f"💾 Acquiring lock to save world state to: {save_path}...")
     success = False
-    with manager["lock"]: # Use resource's lock
-        world_data_dict = dict(manager["state"]) # Get copy from resource state
+    with manager["lock"]:
+        world_data_dict = dict(manager["state"])
         print(f"💾 Saving {len(world_data_dict)} objects...")
         parsed_info = parse_world_filename(save_path)
         timestamp_save = get_current_time_str()
@@ -234,7 +237,7 @@ def save_world_state_to_md(target_filename_base):
 
 def load_world_state_from_md(filename_base):
     """Loads world state from MD, updates cached state, returns success bool."""
-    manager = get_world_state_manager() # Get resource
+    manager = get_world_state_manager()
     load_path = os.path.join(SAVED_WORLDS_DIR, filename_base)
     print(f"📜 Loading world state from MD file: {load_path}...")
     if not os.path.exists(load_path): st.error(f"World file not found: {filename_base}"); return False
@@ -245,31 +248,19 @@ def load_world_state_from_md(filename_base):
         world_data_dict = json.loads(json_match.group(1))
 
         print(f"⚙️ Acquiring lock to update cached world state from {filename_base}...")
-        with manager["lock"]: # Use resource's lock
-             manager["state"].clear() # Clear the existing cached state dict
-             for k, v in world_data_dict.items(): manager["state"][str(k)] = v # Update with loaded data
+        with manager["lock"]:
+             manager["state"].clear()
+             for k, v in world_data_dict.items(): manager["state"][str(k)] = v
              loaded_count = len(manager["state"])
         print(f"✅ Loaded {loaded_count} objects into cached state. Lock released.")
         st.session_state.current_world_file = filename_base # Track loaded file
-        # Consider clearing the cache resource if behavior is unexpected after loading?
-        # get_world_state_manager.clear() # <-- Use this if needed to force re-init on next access
         return True
 
     except json.JSONDecodeError as e: st.error(f"Invalid JSON in {filename_base}: {e}"); return False
     except Exception as e: st.error(f"Error loading world state from {filename_base}: {e}"); st.exception(e); return False
 
-def get_saved_worlds():
-    """Scans the saved worlds directory for world MD files and parses them."""
-    try:
-        ensure_dir(SAVED_WORLDS_DIR);
-        world_files = glob.glob(os.path.join(SAVED_WORLDS_DIR, f"{WORLD_STATE_FILE_MD_PREFIX}*.md"))
-        parsed_worlds = [parse_world_filename(f) for f in world_files]
-        parsed_worlds.sort(key=lambda x: x['dt'] if x['dt'] else datetime.min.replace(tzinfo=pytz.utc), reverse=True)
-        return parsed_worlds
-    except Exception as e: print(f"❌ Error scanning saved worlds: {e}"); st.error(f"Could not scan saved worlds: {e}"); return []
-
 # ==============================================================================
-# User State & Session Init
+# 5. 👤 User State & Session Init
 # ==============================================================================
 def save_username(username):
     try:
@@ -293,11 +284,11 @@ def init_session_state():
         'download_link_cache': {}, 'username': None, 'autosend': False,
         'last_message': "",
         'selected_object': 'None',
-        # Removed 'initial_world_state_loaded' flag, cache resource handles init
+        # 'initial_world_state_loaded' flag removed, cache resource handles init
         'current_world_file': None, # Track loaded world filename (basename)
         'new_world_name': "MyDreamscape",
         'action_log': deque(maxlen=MAX_ACTION_LOG_SIZE),
-        # Removed 'world_to_load_data' and 'js_object_placed_data' - WS handles live updates
+        # State related to JS interaction moved or removed if WS handles it
     }
     for k, v in defaults.items():
         if k not in st.session_state:
@@ -311,7 +302,7 @@ def init_session_state():
     if not isinstance(st.session_state.action_log, deque): st.session_state.action_log = deque(maxlen=MAX_ACTION_LOG_SIZE)
 
 # ==============================================================================
-# Action Log Helper
+# 6. 📝 Action Log Helper
 # ==============================================================================
 def add_action_log(message, emoji="➡️"):
     """Adds a timestamped message with emoji to the session's action log."""
@@ -321,20 +312,20 @@ def add_action_log(message, emoji="➡️"):
     st.session_state.action_log.appendleft(f"{emoji} [{timestamp}] {message}")
 
 # ==============================================================================
-# Audio / TTS / Chat / File Handling Helpers (Keep implementations)
+# 7. 🎧 Audio / TTS / Chat / File Handling Helpers
 # ==============================================================================
-# --- Text & File Helpers ---
-def clean_text_for_tts(text):
+# (Keep implementations from previous correct version - Placeholder for brevity)
+def clean_text_for_tts(text): # ... implementation ...
     if not isinstance(text, str): return "No text"
     text = re.sub(r'\[([^\]]+)\]\([^\)]+\)', r'\1', text); text = re.sub(r'[#*_`!]', '', text)
     text = ' '.join(text.split()); return text[:250] or "No text"
-def create_file(content, username, file_type="md", save_path=None):
+def create_file(content, username, file_type="md", save_path=None): # ... implementation ...
     if not save_path: filename = generate_filename(content, username, file_type); save_path = os.path.join(MEDIA_DIR, filename)
     ensure_dir(os.path.dirname(save_path))
     try:
         with open(save_path, 'w', encoding='utf-8') as f: f.write(content); return save_path
     except Exception as e: print(f"❌ Error creating file {save_path}: {e}"); return None
-def get_download_link(file_path, file_type="md"):
+def get_download_link(file_path, file_type="md"): # ... implementation ...
     if not file_path or not os.path.exists(file_path): basename = os.path.basename(file_path) if file_path else "N/A"; return f"<small>Not found: {basename}</small>"
     try: mtime = os.path.getmtime(file_path)
     except OSError: mtime = 0
@@ -349,8 +340,7 @@ def get_download_link(file_path, file_type="md"):
             st.session_state.download_link_cache[cache_key] = link_html
         except Exception as e: print(f"❌ Error generating DL link for {file_path}: {e}"); return f"<small>Err</small>"
     return st.session_state.download_link_cache.get(cache_key, "<small>CacheErr</small>")
-# --- Audio / TTS ---
-async def async_edge_tts_generate(text, voice, username):
+async def async_edge_tts_generate(text, voice, username): # ... implementation ...
     if not text: return None
     cache_key = hashlib.md5(f"{text[:150]}_{voice}".encode()).hexdigest();
     if 'audio_cache' not in st.session_state: st.session_state.audio_cache = {}
@@ -365,28 +355,21 @@ async def async_edge_tts_generate(text, voice, username):
         if os.path.exists(save_path) and os.path.getsize(save_path) > 0: st.session_state.audio_cache[cache_key] = save_path; return save_path
         else: print(f"❌ Audio file {save_path} failed generation."); return None
     except Exception as e: print(f"❌ Edge TTS Error: {e}"); return None
-def play_and_download_audio(file_path):
+def play_and_download_audio(file_path): # ... implementation ...
     if file_path and os.path.exists(file_path):
-        try:
-             st.audio(file_path)
-             file_type = file_path.split('.')[-1]
-             st.markdown(get_download_link(file_path, file_type), unsafe_allow_html=True)
+        try: st.audio(file_path); file_type = file_path.split('.')[-1]; st.markdown(get_download_link(file_path, file_type), unsafe_allow_html=True)
         except Exception as e: st.error(f"❌ Audio display error for {os.path.basename(file_path)}: {e}")
-# --- Chat ---
-async def save_chat_entry(username, message, voice, is_markdown=False):
+async def save_chat_entry(username, message, voice, is_markdown=False): # ... implementation ...
     if not message.strip(): return None, None
-    timestamp_str = get_current_time_str();
-    entry = f"[{timestamp_str}] {username} ({voice}): {message}" if not is_markdown else f"[{timestamp_str}] {username} ({voice}):\n```markdown\n{message}\n```"
+    timestamp_str = get_current_time_str(); entry = f"[{timestamp_str}] {username} ({voice}): {message}" if not is_markdown else f"[{timestamp_str}] {username} ({voice}):\n```markdown\n{message}\n```"
     md_filename_base = generate_filename(message, username, "md"); md_file_path = os.path.join(CHAT_DIR, md_filename_base);
     md_file = create_file(entry, username, "md", save_path=md_file_path)
     if 'chat_history' not in st.session_state: st.session_state.chat_history = [];
     st.session_state.chat_history.append(entry)
     audio_file = None;
-    if st.session_state.get('enable_audio', True):
-         tts_message = message
-         audio_file = await async_edge_tts_generate(tts_message, voice, username)
+    if st.session_state.get('enable_audio', True): tts_message = message ; audio_file = await async_edge_tts_generate(tts_message, voice, username)
     return md_file, audio_file
-async def load_chat_history():
+async def load_chat_history(): # ... implementation ...
      if 'chat_history' not in st.session_state: st.session_state.chat_history = []
      if not st.session_state.chat_history:
           ensure_dir(CHAT_DIR); print("📜 Loading chat history from files...")
@@ -399,8 +382,7 @@ async def load_chat_history():
           st.session_state.chat_history = temp_history
           print(f"✅ Loaded {loaded_count} chat entries from files.")
      return st.session_state.chat_history
-# --- File Management ---
-def create_zip_of_files(files_to_zip, prefix="Archive"):
+def create_zip_of_files(files_to_zip, prefix="Archive"): # ... implementation ...
     if not files_to_zip: st.warning("💨 Nothing to gather into an archive."); return None
     timestamp = format_timestamp_prefix(f"Zip_{prefix}"); zip_name = f"{prefix}_{timestamp}.zip"
     try:
@@ -411,10 +393,10 @@ def create_zip_of_files(files_to_zip, prefix="Archive"):
                  else: print(f"💨 Skip zip missing file: {f}")
         print("✅ Zip archive created successfully."); st.success(f"Created {zip_name}"); return zip_name
     except Exception as e: print(f"❌ Zip creation failed: {e}"); st.error(f"Zip creation failed: {e}"); return None
-def delete_files(file_patterns, exclude_files=None):
+def delete_files(file_patterns, exclude_files=None): # ... implementation ...
     protected = [STATE_FILE, "app.py", "index.html", "requirements.txt", "README.md"]
     current_world_base = st.session_state.get('current_world_file')
-    if current_world_base: protected.append(current_world_base) # Protect loaded world
+    if current_world_base: protected.append(current_world_base)
     if exclude_files: protected.extend(exclude_files)
     deleted_count = 0; errors = 0
     for pattern in file_patterns:
@@ -428,19 +410,18 @@ def delete_files(file_patterns, exclude_files=None):
                    if os.path.isfile(f_path) and basename not in protected:
                         try: os.remove(f_path); print(f"🗑️ Deleted: {f_path}"); deleted_count += 1
                         except Exception as e: print(f"❌ Failed delete {f_path}: {e}"); errors += 1
-                   # else: print(f"🚫 Skipping protected/directory: {f_path}") # Debugging
+                   #else: print(f"🚫 Skipping protected/directory: {f_path}") # Debugging
          except Exception as glob_e: print(f"❌ Error matching pattern {pattern}: {glob_e}"); errors += 1
     msg = f"✅ Successfully deleted {deleted_count} files." if errors == 0 and deleted_count > 0 else f"Deleted {deleted_count} files."
     if errors > 0: msg += f" Encountered {errors} errors."; st.warning(msg)
     elif deleted_count > 0: st.success(msg)
     else: st.info("💨 No matching unprotected files found to delete.")
     st.session_state['download_link_cache'] = {}; st.session_state['audio_cache'] = {}
-# --- Image Handling ---
-async def save_pasted_image(image, username):
+async def save_pasted_image(image, username): # ... implementation ...
      if not image: return None
      try: img_hash = hashlib.md5(image.tobytes()).hexdigest()[:8]; timestamp = format_timestamp_prefix(username); filename = f"{timestamp}_pasted_{img_hash}.png"; filepath = os.path.join(MEDIA_DIR, filename); image.save(filepath, "PNG"); print(f"🖼️ Pasted image saved: {filepath}"); return filepath
      except Exception as e: print(f"❌ Failed image save: {e}"); return None
-def paste_image_component():
+def paste_image_component(): # ... implementation ...
       pasted_img = None; img_type = None
       paste_input_value = st.text_area("📋 Paste Image Data Here", key="paste_input_area", height=50, value=st.session_state.get('paste_image_base64_input', ""), help="Paste image data directly (e.g., from clipboard)")
       if st.button("🖼️ Process Pasted Image", key="process_paste_button"):
@@ -451,7 +432,7 @@ def paste_image_component():
                    st.image(pasted_img, caption=f"🖼️ Pasted ({img_type.upper()})", width=150); st.session_state.paste_image_base64 = base64_str
                    st.session_state.paste_image_base64_input = ""
                    st.rerun()
-               except ImportError: st.error("⚠️ Pillow library needed for image pasting.")
+               except ImportError: st.error("⚠️ Pillow library needed.")
                except Exception as e: st.error(f"❌ Img decode err: {e}"); st.session_state.paste_image_base64 = ""; st.session_state.paste_image_base64_input = paste_input_value
            else: st.warning("⚠️ No valid image data pasted."); st.session_state.paste_image_base64 = ""; st.session_state.paste_image_base64_input = paste_input_value
       processed_b64 = st.session_state.get('paste_image_base64', '')
@@ -459,8 +440,7 @@ def paste_image_component():
            try: img_bytes = base64.b64decode(processed_b64); return Image.open(io.BytesIO(img_bytes))
            except Exception: return None
       return None
-# --- PDF Processing ---
-class AudioProcessor: # Keep as is
+class AudioProcessor: # ... implementation ...
       def __init__(self): self.cache_dir=AUDIO_CACHE_DIR; ensure_dir(self.cache_dir); self.metadata=json.load(open(f"{self.cache_dir}/metadata.json", 'r')) if os.path.exists(f"{self.cache_dir}/metadata.json") else {}
       def _save_metadata(self):
             try:
@@ -478,7 +458,7 @@ class AudioProcessor: # Keep as is
                  else: return None
             except Exception as e: print(f"❌ TTS Create Audio Error: {e}"); return None
 
-def process_pdf_tab(pdf_file, max_pages, voice): # Corrected version
+def process_pdf_tab(pdf_file, max_pages, voice): # ... implementation ...
     st.subheader("📜 PDF Processing Results")
     if pdf_file is None: st.info("⬆️ Upload a PDF file and click 'Process PDF' to begin."); return
     audio_processor = AudioProcessor()
@@ -497,7 +477,6 @@ def process_pdf_tab(pdf_file, max_pages, voice): # Corrected version
                       with results_lock: audios[page_num] = audio_path
             except Exception as page_e: print(f"❌ Err process page {page_num+1}: {page_e}")
 
-        # Start threads
         for i in range(pages_to_process):
              try: # Start try block for page processing
                  page = reader.pages[i]
@@ -515,7 +494,6 @@ def process_pdf_tab(pdf_file, max_pages, voice): # Corrected version
                   texts[i] = f"[❌ Error extract: {extract_e}]" # Store error message
                   print(f"Error page {i+1} extract: {extract_e}") # Log error
 
-        # Wait for threads and display progress
         progress_bar = st.progress(0.0, text="✨ Transmuting pages to sound...")
         total_threads = len(page_threads); start_join_time = time.time()
         while any(t.is_alive() for t in page_threads):
@@ -525,7 +503,6 @@ def process_pdf_tab(pdf_file, max_pages, voice): # Corrected version
             time.sleep(0.5)
         progress_bar.progress(1.0, text="✅ Processing complete.")
 
-        # Display results
         st.write("🎶 Results:")
         for i in range(pages_to_process):
               with st.expander(f"Page {i+1}"):
@@ -540,75 +517,126 @@ def process_pdf_tab(pdf_file, max_pages, voice): # Corrected version
     except ImportError: st.error("⚠️ PyPDF2 library needed.")
     except Exception as pdf_e: st.error(f"❌ Error reading PDF '{pdf_file.name}': {pdf_e}"); st.exception(pdf_e)
 
-
 # ==============================================================================
-# WebSocket Server Logic (Re-added for Chat/Presence)
+# 8. 🕸️ WebSocket Server Logic (Re-added for Chat/Presence)
 # ==============================================================================
 
 async def register_client(websocket):
+    """Adds client to tracking structures, ensuring thread safety."""
     client_id = str(websocket.id);
-    with clients_lock: connected_clients.add(client_id);
-    if 'active_connections' not in st.session_state: st.session_state.active_connections = defaultdict(dict);
-    st.session_state.active_connections[client_id] = websocket;
+    with clients_lock:
+        connected_clients.add(client_id);
+        if 'active_connections' not in st.session_state: st.session_state.active_connections = defaultdict(dict);
+        st.session_state.active_connections[client_id] = websocket;
     print(f"✅ Client registered: {client_id}. Total: {len(connected_clients)}")
 
 async def unregister_client(websocket):
+    """Removes client from tracking structures, ensuring thread safety."""
     client_id = str(websocket.id);
     with clients_lock:
         connected_clients.discard(client_id);
         if 'active_connections' in st.session_state: st.session_state.active_connections.pop(client_id, None);
-    print(f"❌ Client unregistered: {client_id}. Remaining: {len(connected_clients)}")
+    print(f"🔌 Client unregistered: {client_id}. Remaining: {len(connected_clients)}")
 
 async def send_safely(websocket, message, client_id):
      """Wrapper to send message and handle potential connection errors."""
      try: await websocket.send(message)
-     except websockets.ConnectionClosed: print(f"❌ WS Send failed (Closed) client {client_id}"); raise
+     except websockets.ConnectionClosed: print(f"❌ WS Send failed (Closed) client {client_id}"); raise # Raise to be caught by gather
      except RuntimeError as e: print(f"❌ WS Send failed (Runtime {e}) client {client_id}"); raise
      except Exception as e: print(f"❌ WS Send failed (Other {e}) client {client_id}"); raise
 
 async def broadcast_message(message, exclude_id=None):
     """Sends a message to all connected clients except the excluded one."""
+    # Create local copies under lock for thread safety
     with clients_lock:
         if not connected_clients: return
         current_client_ids = list(connected_clients)
-        active_connections_copy = st.session_state.active_connections.copy()
+        # Ensure active_connections exists and make a copy
+        if 'active_connections' in st.session_state:
+            active_connections_copy = st.session_state.active_connections.copy()
+        else:
+            active_connections_copy = {} # Should not happen if init_session_state is correct
 
     tasks = []
     for client_id in current_client_ids:
         if client_id == exclude_id: continue
-        websocket = active_connections_copy.get(client_id)
-        if websocket: tasks.append(asyncio.create_task(send_safely(websocket, message, client_id)))
+        websocket = active_connections_copy.get(client_id) # Use copy
+        if websocket:
+            tasks.append(asyncio.create_task(send_safely(websocket, message, client_id)))
+
+    if tasks:
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        # Optional: Check results for exceptions if specific error handling per client is needed
+
 
-    if tasks: await asyncio.gather(*tasks, return_exceptions=True) # Wait and ignore errors here
+async def broadcast_world_update():
+    """Broadcasts the current world state (from cache) to all clients."""
+    # Uses the cached state manager
+    world_state_copy = get_current_world_state_copy()
+    update_msg = json.dumps({"type": "initial_state", "payload": world_state_copy})
+    print(f"📡 Broadcasting full world update ({len(world_state_copy)} objects)...")
+    await broadcast_message(update_msg)
 
 async def websocket_handler(websocket, path):
-    """Handles WebSocket connections and messages (primarily for Chat)."""
+    """Handles WebSocket connections and messages (primarily for Chat & 3D Sync)."""
     await register_client(websocket); client_id = str(websocket.id);
     username = st.session_state.get('username', f"User_{client_id[:4]}")
 
-    try: # Announce join
-        print(f"✨ {username} ({client_id}) connected.")
+    try: # Send initial world state
+        initial_state_payload = get_current_world_state_copy() # Get state using cached helper
+        initial_state_msg = json.dumps({"type": "initial_state", "payload": initial_state_payload});
+        await websocket.send(initial_state_msg)
+        print(f"✅ Sent initial state ({len(initial_state_payload)} objs) to {client_id}")
+        # Announce join after state sent
         await broadcast_message(json.dumps({"type": "user_join", "payload": {"username": username, "id": client_id}}), exclude_id=client_id)
-    except Exception as e: print(f"❌ Error during join announcement {client_id}: {e}")
+    except Exception as e: print(f"❌ Error during initial phase {client_id}: {e}")
 
-    try: # Message loop
+    try: # Message processing loop
         async for message in websocket:
             try:
                 data = json.loads(message); msg_type = data.get("type"); payload = data.get("payload", {});
-                sender_username = payload.get("username", username) # Username sent from client
+                sender_username = payload.get("username", username) # Get username from payload
+
+                # --- Handle Different Message Types ---
+                manager = get_world_state_manager() # Get state manager for world updates
 
                 if msg_type == "chat_message":
                     chat_text = payload.get('message', ''); voice = payload.get('voice', FUN_USERNAMES.get(sender_username, DEFAULT_TTS_VOICE));
                     print(f"💬 WS Recv Chat from {sender_username}: {chat_text[:30]}...")
-                    # Schedule save/TTS locally
-                    run_async(save_chat_entry, sender_username, chat_text, voice)
-                    # Broadcast message to other clients (they will update their UI)
-                    await broadcast_message(message, exclude_id=client_id)
-                elif msg_type == "ping": # Handle keepalive pings
-                     await websocket.send(json.dumps({"type": "pong"}))
-                # Add other message types if needed (e.g., simple presence)
-                else:
-                     print(f"⚠️ WS Recv unknown message type from {client_id}: {msg_type}")
+                    run_async(save_chat_entry, sender_username, chat_text, voice) # Save locally async
+                    await broadcast_message(message, exclude_id=client_id) # Broadcast chat
+
+                elif msg_type == "place_object":
+                    obj_data = payload.get("object_data");
+                    if obj_data and 'obj_id' in obj_data and 'type' in obj_data:
+                        print(f"➕ WS Recv Place from {sender_username}: {obj_data['type']} ({obj_data['obj_id']})")
+                        with manager["lock"]: manager["state"][obj_data['obj_id']] = obj_data # Update cached state
+                        # Broadcast placement to others
+                        broadcast_payload = json.dumps({"type": "object_placed", "payload": {"object_data": obj_data, "username": sender_username}});
+                        await broadcast_message(broadcast_payload, exclude_id=client_id)
+                        run_async(lambda: add_action_log(f"Placed {obj_data['type']} ({obj_data['obj_id'][:6]}) by {sender_username}", TOOLS_MAP.get(obj_data['type'], '❓')))
+                    else: print(f"⚠️ WS Invalid place_object payload: {payload}")
+
+                elif msg_type == "delete_object":
+                     obj_id = payload.get("obj_id"); removed = False
+                     if obj_id:
+                          print(f"➖ WS Recv Delete from {sender_username}: {obj_id}")
+                          with manager["lock"]:
+                              if obj_id in manager["state"]: del manager["state"][obj_id]; removed = True
+                          if removed:
+                               broadcast_payload = json.dumps({"type": "object_deleted", "payload": {"obj_id": obj_id, "username": sender_username}});
+                               await broadcast_message(broadcast_payload, exclude_id=client_id)
+                               run_async(lambda: add_action_log(f"Deleted obj ({obj_id[:6]}) by {sender_username}", "🗑️"))
+                     else: print(f"⚠️ WS Invalid delete_object payload: {payload}")
+
+                elif msg_type == "player_position":
+                     pos_data = payload.get("position"); rot_data = payload.get("rotation")
+                     if pos_data:
+                          broadcast_payload = json.dumps({"type": "player_moved", "payload": {"username": sender_username, "id": client_id, "position": pos_data, "rotation": rot_data}});
+                          await broadcast_message(broadcast_payload, exclude_id=client_id) # Broadcast movement
+
+                elif msg_type == "ping": await websocket.send(json.dumps({"type": "pong"}))
+                else: print(f"⚠️ WS Recv unknown type from {client_id}: {msg_type}")
 
             except json.JSONDecodeError: print(f"⚠️ WS Invalid JSON from {client_id}: {message[:100]}...")
             except Exception as e: print(f"❌ WS Error processing msg from {client_id}: {e}")
@@ -616,18 +644,19 @@ async def websocket_handler(websocket, path):
     except Exception as e: print(f"❌ WS Unexpected handler error {client_id}: {e}")
     finally:
          await broadcast_message(json.dumps({"type": "user_leave", "payload": {"username": username, "id": client_id}}), exclude_id=client_id);
-         await unregister_client(websocket) # Cleanup
+         await unregister_client(websocket)
+
 
 async def run_websocket_server():
     """Coroutine to run the WebSocket server."""
-    if st.session_state.get('server_running_flag', False): return # Prevent multiple starts
+    if st.session_state.get('server_running_flag', False): return
     st.session_state['server_running_flag'] = True; print("⚙️ Attempting start WS server 0.0.0.0:8765...")
     stop_event = asyncio.Event(); st.session_state['websocket_stop_event'] = stop_event
     server = None
     try:
         server = await websockets.serve(websocket_handler, "0.0.0.0", 8765); st.session_state['server_instance'] = server
         print(f"✅ WS server started: {server.sockets[0].getsockname()}. Waiting for stop signal...")
-        await stop_event.wait() # Keep server running
+        await stop_event.wait()
     except OSError as e: print(f"### ❌ FAILED START WS SERVER: {e}"); st.session_state['server_running_flag'] = False;
     except Exception as e: print(f"### ❌ UNEXPECTED WS SERVER ERROR: {e}"); st.session_state['server_running_flag'] = False;
     finally:
@@ -658,7 +687,7 @@ def start_websocket_server_thread():
 
 
 # ==============================================================================
-# Streamlit UI Layout Functions
+# 9. 🎨 Streamlit UI Layout Functions
 # ==============================================================================
 
 def render_sidebar():
@@ -668,26 +697,35 @@ def render_sidebar():
         st.header("1. 💾 World Management")
         st.caption("💾 Save the current view or ✨ load a past creation.")
 
-        # World Save Button (simplified logic)
+        # World Save Button
         current_file = st.session_state.get('current_world_file')
         save_name_value = st.session_state.get('world_save_name_input', "MyDreamscape" if not current_file else parse_world_filename(os.path.join(SAVED_WORLDS_DIR, current_file)).get("name", current_file))
         world_save_name = st.text_input("World Name:", key="world_save_name_input", value=save_name_value, help="Enter name to save.")
 
-        if st.button("💾 Save Current View", key="sidebar_save_world"):
+        if st.button("💾 Save Current World View", key="sidebar_save_world"):
             if not world_save_name.strip(): st.warning("⚠️ Please enter a World Name.")
             else:
-                # Store info needed for callback after JS returns data
-                st.session_state.pending_save_filename = generate_world_save_filename(st.session_state.username, world_save_name)
-                st.session_state.pending_save_op_text = f"Saving {world_save_name}..."
-                # Trigger JS to get state and call Python function `handle_js_save_data`
-                try:
-                     print("🐍 Requesting world state from JS for saving...")
-                     # JS function `getWorldStateForSave` now calls Python func `handle_js_save_data`
-                     streamlit_js_eval("getWorldStateForSave(true);", key="trigger_js_save")
-                     st.info("💾 Requesting state from view...")
-                except Exception as e: st.error(f"❌ Failed to request save state: {e}")
-
-        # World Load Section
+                # Save current state (which is managed by cache resource, updated by WS)
+                filename_to_save = ""; is_overwrite = False
+                if current_file:
+                     try: # Check if name matches current loaded file's parsed name
+                          parsed_current = parse_world_filename(os.path.join(SAVED_WORLDS_DIR, current_file))
+                          if world_save_name == parsed_current.get('name', ''): filename_to_save = current_file; is_overwrite = True
+                     except Exception: pass # Fallback to new save if parsing fails
+
+                if not filename_to_save: filename_to_save = generate_world_save_filename(st.session_state.username, world_save_name)
+
+                op_text = f"Overwriting {filename_to_save}..." if is_overwrite else f"Saving as {filename_to_save}..."
+                with st.spinner(op_text):
+                    if save_world_state_to_md(filename_to_save): # Saves state from cached resource
+                        action = "Overwritten" if is_overwrite else "Saved new"
+                        st.success(f"World {action}: {filename_to_save}"); add_action_log(f"Saved world: {filename_to_save}", emoji="💾")
+                        st.session_state.current_world_file = filename_to_save # Track saved file
+                        st.rerun()
+                    else: st.error("❌ Failed to save world state.")
+
+
+        # --- World Load ---
         st.markdown("---")
         st.header("2. 📂 Load World")
         st.caption("📜 Unfurl a previously woven dreamscape.")
@@ -700,8 +738,6 @@ def render_sidebar():
              with cols_header[1]: st.write("**Load**")
              with cols_header[2]: st.write("**DL**")
 
-             display_limit = 15
-             # Use a container for scrollability if list is long
              list_container = st.container(height=300 if len(saved_worlds) > 7 else None)
              with list_container:
                  for world_info in saved_worlds:
@@ -717,15 +753,16 @@ def render_sidebar():
 
                     if btn_load:
                         print(f"🖱️ Load button clicked for: {f_basename}")
-                        world_dict = load_world_from_md(f_basename)
-                        if world_dict is not None:
-                            st.session_state.world_to_load_data = world_dict # Queue data for JS
-                            st.session_state.current_world_file = f_basename
-                            add_action_log(f"Loading world: {f_basename}", emoji="📂")
-                            st.rerun()
-                        else: st.error(f"❌ Failed to parse world file: {f_basename}")
-
-        # Build Tools Section
+                        with st.spinner(f"Loading {f_basename}..."):
+                            # load_world_state_from_md now updates the cached resource directly
+                            if load_world_state_from_md(f_basename):
+                                run_async(broadcast_world_update) # Broadcast the newly loaded state
+                                add_action_log(f"Loading world: {f_basename}", emoji="📂")
+                                st.toast("World loaded!", icon="✅")
+                                st.rerun() # Rerun to update UI and ensure clients get state via WS
+                            else: st.error(f"❌ Failed to load world file: {f_basename}")
+
+        # --- Build Tools ---
         st.markdown("---")
         st.header("3. 🛠️ Build Tools")
         st.caption("Select your creative instrument.")
@@ -748,7 +785,7 @@ def render_sidebar():
             st.rerun()
 
 
-        # Action Log Section
+        # --- Action Log ---
         st.markdown("---")
         st.header("4. 📝 Action Log")
         st.caption("📜 A chronicle of your recent creative acts.")
@@ -759,22 +796,22 @@ def render_sidebar():
             else: st.caption("🌬️ The log awaits your first action...")
 
 
-        # Voice/User Section
+        # --- Voice/User ---
         st.markdown("---")
         st.header("5. 👤 Voice & User")
         st.caption("🎭 Choose your persona in this realm.")
         current_username = st.session_state.get('username', "DefaultUser")
         username_options = list(FUN_USERNAMES.keys()) if FUN_USERNAMES else [current_username]
         current_index = 0;
-        try:
+        try: # Safely find index
             if current_username in username_options: current_index = username_options.index(current_username)
-        except ValueError: pass # Keep index 0 if not found
+        except ValueError: pass # Keep index 0
 
         new_username = st.selectbox("Change Name/Voice", options=username_options, index=current_index, key="username_select", format_func=lambda x: x.split(" ")[0])
         if new_username != st.session_state.get('username'):
             old_username = st.session_state.username
             change_msg = json.dumps({"type":"user_rename", "payload": {"old_username": old_username, "new_username": new_username}})
-            run_async(broadcast_message, change_msg) # Broadcast name change if WS is running
+            run_async(broadcast_message, change_msg) # Broadcast name change
             st.session_state.username = new_username; st.session_state.tts_voice = FUN_USERNAMES.get(new_username, DEFAULT_TTS_VOICE); save_username(st.session_state.username)
             add_action_log(f"Persona changed to {new_username}", emoji="🎭")
             st.rerun()
@@ -785,70 +822,10 @@ def render_main_content():
     """Renders the main content area with tabs."""
     st.title(f"{Site_Name} - User: {st.session_state.username}")
 
-    # 1. Check if world data needs to be sent to JS (loaded via sidebar button)
-    world_data_to_load = st.session_state.pop('world_to_load_data', None)
-    if world_data_to_load is not None:
-        print(f"🐍 Sending loaded world state ({len(world_data_to_load)} objects) to JS...")
-        try:
-            streamlit_js_eval(js_code=f"loadWorldState({json.dumps(world_data_to_load)});", key="load_world_js")
-            st.toast("🌌 World loaded in 3D view.", icon="🔄")
-        except Exception as e: st.error(f"❌ Failed to send loaded world state to JS: {e}")
-
-    # 2. Set up JS communication handlers (Object Placement & Save Data Callback)
-    streamlit_js_eval(
-        js_code="""
-            // Ensure functions are defined only once per page load
-            if (!window.streamlitPythonCallSetupDone) {
-                console.log('🐍 Setting up JS->Python communication functions...');
-                window.sendPlacedObjectToPython = (objectData) => {
-                    console.log('JS sending placed object:', objectData);
-                    streamlit_js_eval(python_code='handle_js_object_placed(data=' + JSON.stringify(objectData) + ')', key='js_place_event_handler');
-                };
-                window.sendSaveDataToPython = (jsonData) => {
-                     console.log('JS sending saved world state back to Python...');
-                     streamlit_js_eval(python_code='handle_js_save_data(data=' + JSON.stringify(jsonData) + ')', key='js_save_state_handler');
-                 };
-                 window.streamlitPythonCallSetupDone = true;
-             }
-        """,
-        key="setup_js_comms" # Key for the setup code itself
-    )
-
-    # 3. Process data received from JS callbacks (if any were triggered)
-    # Check for placement data
-    if 'js_place_event_handler' in st.session_state:
-        placed_data = st.session_state.pop('js_object_placed_data', None)
-        if placed_data: print(f"🐍 Python processed placed object: {placed_data.get('obj_id')}")
-        del st.session_state['js_place_event_handler'] # Clear trigger
-
-    # Check for save data
-    if 'js_save_state_handler' in st.session_state:
-        saved_data_str = st.session_state.pop('js_save_state_data', None)
-        del st.session_state['js_save_state_handler']
-        if saved_data_str:
-            print("🐍 Python processing saved world data received from JS...")
-            try:
-                world_data_dict = json.loads(saved_data_str)
-                if isinstance(world_data_dict, dict):
-                    save_filename = st.session_state.get("pending_save_filename") # Get filename set by button
-                    save_op_text = st.session_state.get("pending_save_op_text", f"Saving {save_filename}...")
-                    is_overwrite = st.session_state.get("pending_save_is_overwrite", False)
-                    if save_filename:
-                         with st.spinner(save_op_text):
-                             if save_world_to_md(save_filename, world_data_dict):
-                                 action = "Overwritten" if is_overwrite else "Saved new"; st.success(f"World {action}: {save_filename}");
-                                 add_action_log(f"Saved world: {save_filename}", emoji="💾")
-                                 st.session_state.current_world_file = save_filename # Update current file
-                                 # Clear pending save state
-                                 st.session_state.pop("pending_save_filename", None); st.session_state.pop("pending_save_op_text", None); st.session_state.pop("pending_save_is_overwrite", None)
-                                 st.rerun() # Refresh lists
-                             else: st.error("❌ Failed to save world state to file.")
-                    else: st.error("❌ Save triggered but filename was missing in state.")
-                else: st.error("❌ Invalid save data format received.")
-            except json.JSONDecodeError: st.error("❌ Failed to decode save data from JS.")
-            except Exception as e: st.error(f"❌ Error processing save data: {e}"); st.exception(e)
-        else: print("⚠️ Save callback triggered, but no save data found.")
-
+    # NOTE: No longer need to check/send 'world_to_load_data' here.
+    # The load button triggers load_world_state_from_md which updates the cache,
+    # then triggers broadcast_world_update (via run_async), and reruns.
+    # The WS handler sends initial state from the cache on new connections.
 
     # Define Tabs
     tab_world, tab_chat, tab_pdf, tab_files = st.tabs(["🏗️ World Builder", "🗣️ Chat", "📚 PDF Tools", "📂 Files & Settings"])
@@ -856,7 +833,7 @@ def render_main_content():
     # --- World Builder Tab ---
     with tab_world:
         st.header("🌌 Shared Dreamscape")
-        st.caption("✨ Weave reality with sidebar tools. Save your creations!")
+        st.caption("✨ Weave reality with sidebar tools. Changes shared live! Use sidebar to save/load.")
         current_file_basename = st.session_state.get('current_world_file', None)
         if current_file_basename:
              full_path = os.path.join(SAVED_WORLDS_DIR, current_file_basename)
@@ -868,20 +845,24 @@ def render_main_content():
         html_file_path = 'index.html'
         try:
             with open(html_file_path, 'r', encoding='utf-8') as f: html_template = f.read()
-            # Inject state needed by JS
-            initial_world_data = {} # Default empty, loadWorldState handles initial load
-            if world_data_to_load is None and st.session_state.get('current_world_file'):
-                 # If a file is selected, but wasn't just loaded (e.g., page refresh), load its data for initial injection
-                 loaded_dict = load_world_from_md(st.session_state.current_world_file)
-                 if loaded_dict: initial_world_data = loaded_dict
-
+            ws_url = "ws://localhost:8765" # Default
+            try: # Get WS URL (Best effort)
+                 from streamlit.web.server.server import Server
+                 session_info = Server.get_current()._get_session_info(st.runtime.scriptrunner.get_script_run_ctx().session_id)
+                 host_attr = getattr(session_info.ws.stream.request, 'host', None) or getattr(getattr(session_info, 'client', None), 'request', None)
+                 if host_attr: server_host = host_attr.host.split(':')[0]; ws_url = f"ws://{server_host}:8765"
+                 else: raise AttributeError("Host attribute not found")
+            except Exception as e: print(f"⚠️ WS URL detection failed ({e}), using localhost.")
+
+            # Inject only necessary state for JS init
             js_injection_script = f"""<script>
     window.USERNAME = {json.dumps(st.session_state.username)};
+    window.WEBSOCKET_URL = {json.dumps(ws_url)}; // Needed by JS to connect
     window.SELECTED_OBJECT_TYPE = {json.dumps(st.session_state.selected_object)};
     window.PLOT_WIDTH = {json.dumps(PLOT_WIDTH)};
     window.PLOT_DEPTH = {json.dumps(PLOT_DEPTH)};
-    window.INITIAL_WORLD_OBJECTS = {json.dumps(initial_world_data)}; /* Used only if loadWorldState isn't called */
-    console.log("🐍 Streamlit State Injected:", {{ username: window.USERNAME, selectedObject: window.SELECTED_OBJECT_TYPE, initialObjectsInject: {len(initial_world_data)} }});
+    // Initial world state is sent via WebSocket 'initial_state' message now
+    console.log("🐍 Streamlit State Injected:", {{ username: window.USERNAME, websocketUrl: window.WEBSOCKET_URL, selectedObject: window.SELECTED_OBJECT_TYPE }});
 </script>"""
             html_content_with_state = html_template.replace('</head>', js_injection_script + '\n</head>', 1)
             components.html(html_content_with_state, height=700, scrolling=False)
@@ -907,8 +888,10 @@ def render_main_content():
             if message_to_send.strip() and message_to_send != st.session_state.get('last_message', ''):
                 st.session_state.last_message = message_to_send
                 voice = st.session_state.get('tts_voice', DEFAULT_TTS_VOICE)
-                # Use run_async for background save/TTS generation
-                run_async(save_chat_entry, st.session_state.username, message_to_send, voice)
+                ws_message = json.dumps({"type": "chat_message", "payload": {"username": st.session_state.username, "message": message_to_send, "voice": voice}})
+                # Use run_async for background tasks
+                run_async(broadcast_message, ws_message) # Broadcast Chat via WS
+                run_async(save_chat_entry, st.session_state.username, message_to_send, voice) # Save async
                 add_action_log(f"Sent chat: {message_to_send[:20]}...", emoji="💬")
                 # Rerun is handled implicitly by button + on_click
             elif send_button_clicked: st.toast("Message empty or same as last.")
@@ -930,8 +913,50 @@ def render_main_content():
         st.caption("⚙️ Manage saved scrolls and application settings.")
 
         st.subheader("💾 World Scroll Management")
-        # Save buttons moved to sidebar for this iteration
+        current_file_basename = st.session_state.get('current_world_file', None)
 
+        # Save Current Version Button
+        if current_file_basename:
+            full_path = os.path.join(SAVED_WORLDS_DIR, current_file_basename)
+            save_label = f"Save Changes to '{current_file_basename}'"
+            if os.path.exists(full_path): parsed = parse_world_filename(full_path); save_label = f"💾 Save Changes to '{parsed['name']}'"
+            if st.button(save_label, key="save_current_world_files", help=f"Overwrite '{current_file_basename}'"):
+                 if not os.path.exists(full_path): st.error(f"❌ Cannot save, file missing.")
+                 else:
+                     with st.spinner(f"Saving changes to {current_file_basename}..."):
+                         # Save the current state from the cached resource
+                         if save_world_state_to_md(current_file_basename):
+                             st.success("✅ Current world saved!"); add_action_log(f"Saved world: {current_file_basename}", emoji="💾")
+                         else: st.error("❌ Failed to save world state.")
+        else: st.info("➡️ Load a world from the sidebar to enable 'Save Changes'.")
+
+        # Save As New Version Section
+        st.subheader("✨ Save As New Scroll")
+        new_name_files = st.text_input("New Scroll Name:", key="new_world_name_files_tab", value=st.session_state.get('new_world_name', 'MyDreamscape'))
+        if st.button("💾 Save Current View as New Scroll", key="save_new_version_files"):
+             if new_name_files.strip():
+                 with st.spinner(f"Saving new version '{new_name_files}'..."):
+                    new_filename_base = generate_world_save_filename(st.session_state.username, new_name_files)
+                    # Save the current state from the cached resource to a NEW file
+                    if save_world_state_to_md(new_filename_base):
+                         st.success(f"✅ Saved as {new_filename_base}")
+                         st.session_state.current_world_file = new_filename_base; st.session_state.new_world_name = "MyDreamscape";
+                         add_action_log(f"Saved new world: {new_filename_base}", emoji="✨")
+                         st.rerun()
+                    else: st.error("❌ Failed to save new version.")
+             else: st.warning("⚠️ Please enter a name.")
+
+        # Server Status
+        st.subheader("⚙️ Server Status")
+        col_ws, col_clients = st.columns(2)
+        with col_ws:
+             server_alive = st.session_state.get('server_task') and st.session_state.server_task.is_alive(); ws_status = "Running" if server_alive else "Stopped"; st.metric("WebSocket Server", ws_status)
+             if not server_alive and st.button("🔄 Restart Server Thread", key="restart_ws"): start_websocket_server_thread(); st.rerun()
+        with col_clients:
+             with clients_lock: client_count = len(connected_clients)
+             st.metric("🔗 Connected Clients", client_count)
+
+        # File Deletion
         st.subheader("🗑️ Archive Maintenance")
         st.caption("🧹 Cleanse the old to make way for the new.")
         st.warning("Deletion is permanent!", icon="⚠️")
@@ -945,6 +970,7 @@ def render_main_content():
         with col_del4:
             if st.button("🗑️ All Gen", key="del_all_gen"): delete_files([os.path.join(CHAT_DIR, "*.md"), os.path.join(AUDIO_DIR, "*.mp3"), os.path.join(AUDIO_CACHE_DIR, "*.mp3"), os.path.join(SAVED_WORLDS_DIR, "*.md"), os.path.join(MEDIA_DIR, "*.zip")]); st.session_state.chat_history = []; st.session_state.audio_cache = {}; st.session_state.current_world_file = None; add_action_log("Cleared All Generated", emoji="🔥"); st.rerun()
 
+        # Download Archives
         st.subheader("📦 Download Archives")
         st.caption("Bundle your creations for safekeeping or sharing.")
         col_zip1, col_zip2, col_zip3 = st.columns(3)
@@ -961,35 +987,40 @@ def render_main_content():
         else:
             st.caption("🌬️ No archives found.")
 
+
 # ==============================================================================
 # Main Execution Logic
 # ==============================================================================
 
 def initialize_app():
-    """Handles session init and initial world load setup."""
+    """Handles session init, server start, and ensures world state resource is accessed."""
     init_session_state()
-    # Load username
+    # Load/Assign username
     if not st.session_state.username:
         loaded_user = load_username()
         if loaded_user and loaded_user in FUN_USERNAMES: st.session_state.username = loaded_user; st.session_state.tts_voice = FUN_USERNAMES[loaded_user]
         else: st.session_state.username = random.choice(list(FUN_USERNAMES.keys())) if FUN_USERNAMES else "User"; st.session_state.tts_voice = FUN_USERNAMES.get(st.session_state.username, DEFAULT_TTS_VOICE); save_username(st.session_state.username)
 
-    # Queue initial world state load IF no world is selected AND no load is pending
-    if st.session_state.get('world_to_load_data') is None and st.session_state.get('current_world_file') is None:
-        print("🐍 Attempting initial load of most recent world...")
-        saved_worlds = get_saved_worlds()
-        if saved_worlds:
-             latest_world_file_basename = os.path.basename(saved_worlds[0]['filename'])
-             print(f"🐍 Queueing most recent world for load: {latest_world_file_basename}")
-             world_dict = load_world_from_md(latest_world_file_basename)
-             if world_dict is not None:
-                  st.session_state.world_to_load_data = world_dict # Queue data
-                  st.session_state.current_world_file = latest_world_file_basename # Set as current
-             else: print("❌ Failed to load most recent world."); st.session_state.world_to_load_data = {} # Send empty state
-        else: print("🌫️ No saved worlds found."); st.session_state.world_to_load_data = {} # Send empty state
+    # Ensure WebSocket server thread is running
+    server_thread = st.session_state.get('server_task'); server_alive = server_thread is not None and server_thread.is_alive()
+    if not st.session_state.get('server_running_flag', False) and not server_alive: start_websocket_server_thread()
+    elif server_alive and not st.session_state.get('server_running_flag', False): st.session_state.server_running_flag = True
+
+    # Trigger the cached resource initialization/retrieval
+    try:
+        manager = get_world_state_manager()
+        # Set initial current_world_file if needed (based on what cache loaded)
+        if st.session_state.get('current_world_file') is None:
+            if manager["state"]: # If the cache loaded state from a file
+                saved_worlds = get_saved_worlds()
+                if saved_worlds:
+                    st.session_state.current_world_file = os.path.basename(saved_worlds[0]['filename'])
+                    print(f"🐍 Set initial session 'current_world_file' to: {st.session_state.current_world_file}")
+    except Exception as e:
+        st.error(f"❌ Fatal error initializing world state manager: {e}"); st.exception(e); st.stop()
 
 
 if __name__ == "__main__":
-    initialize_app() # Initialize state, user, queue initial world load data
-    render_sidebar() # Render sidebar UI
-    render_main_content() # Render main UI (includes logic to send queued world data to JS)
+    initialize_app()
+    render_sidebar()
+    render_main_content()