pomera-ai-commander 1.2.2 → 1.2.4

package/README.md

@@ -1,4 +1,9 @@
 # Pomera AI Commander (PAC)
+
+<p align="center">
+  <img src="resources/icon.png" alt="Pomera - the fluffy Pomeranian mascot" width="128" height="128">
+</p>
+
 [![Download Latest Release](https://img.shields.io/badge/Download-Latest%20Release-blue?style=for-the-badge&logo=github)](https://github.com/matbanik/Pomera-AI-Commander/releases)
 
 A desktop text "workbench" + MCP server: clean, transform, extract, and analyze text fast—manually in a GUI or programmatically from AI assistants (Cursor / Claude Desktop / MCP clients).

package/core/mcp/tool_registry.py

@@ -1868,13 +1868,41 @@ class ToolRegistry:
         conn.row_factory = sqlite3.Row
         return conn
     
+    def _sanitize_text(self, text: str) -> str:
+        """
+        Sanitize text by removing invalid UTF-8 surrogate characters.
+        
+        Lone surrogates (U+D800 to U+DFFF) are invalid in UTF-8 and cause
+        encoding errors. This function removes them while preserving valid content.
+        
+        Args:
+            text: Input text that may contain invalid surrogates
+            
+        Returns:
+            Sanitized text safe for UTF-8 encoding and database storage
+        """
+        if not text:
+            return text
+        
+        # Encode to UTF-8 with 'surrogatepass' to handle surrogates,
+        # then decode with 'replace' to replace invalid sequences
+        try:
+            # This two-step process handles lone surrogates:
+            # 1. surrogatepass allows encoding surrogates (normally forbidden in UTF-8)
+            # 2. errors='replace' replaces invalid sequences with replacement char
+            sanitized = text.encode('utf-8', errors='surrogatepass').decode('utf-8', errors='replace')
+            return sanitized
+        except Exception:
+            # Fallback: manually filter out surrogate characters
+            return ''.join(c for c in text if not (0xD800 <= ord(c) <= 0xDFFF))
+    
     def _handle_notes_save(self, args: Dict[str, Any]) -> str:
         """Handle saving a new note."""
         from datetime import datetime
         
-        title = args.get("title", "")
-        input_content = args.get("input_content", "")
-        output_content = args.get("output_content", "")
+        title = self._sanitize_text(args.get("title", ""))
+        input_content = self._sanitize_text(args.get("input_content", ""))
+        output_content = self._sanitize_text(args.get("output_content", ""))
         
         if not title:
             return "Error: Title is required"
@@ -2042,15 +2070,15 @@ class ToolRegistry:
             
             if "title" in args:
                 updates.append("Title = ?")
-                values.append(args["title"])
+                values.append(self._sanitize_text(args["title"]))
             
             if "input_content" in args:
                 updates.append("Input = ?")
-                values.append(args["input_content"])
+                values.append(self._sanitize_text(args["input_content"]))
             
             if "output_content" in args:
                 updates.append("Output = ?")
-                values.append(args["output_content"])
+                values.append(self._sanitize_text(args["output_content"]))
             
             if not updates:
                 conn.close()
@@ -2639,12 +2667,17 @@ class ToolRegistry:
             """Save operation to notes and return note_id."""
             try:
                 from datetime import datetime
+                # Sanitize text to prevent UTF-8 surrogate errors
+                sanitized_title = registry._sanitize_text(title)
+                sanitized_input = registry._sanitize_text(input_content)
+                sanitized_output = registry._sanitize_text(output_content)
+                
                 conn = registry._get_notes_connection()
                 now = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
                 cursor = conn.execute('''
                     INSERT INTO notes (Created, Modified, Title, Input, Output)
                     VALUES (?, ?, ?, ?, ?)
-                ''', (now, now, title, input_content, output_content))
+                ''', (now, now, sanitized_title, sanitized_input, sanitized_output))
                 note_id = cursor.lastrowid
                 conn.commit()
                 conn.close()

package/create_shortcut.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+Create Desktop Shortcut for Pomera AI Commander
+
+Cross-platform script to create desktop shortcuts/launchers:
+- Windows: Creates .lnk shortcut
+- macOS: Creates .command script in ~/Desktop
+- Linux: Creates .desktop launcher
+
+Can be run standalone or as npm postinstall hook.
+"""
+
+import os
+import sys
+import stat
+import platform
+from pathlib import Path
+
+
+def get_package_dir() -> Path:
+    """Get the pomera-ai-commander package directory."""
+    # First check if we're running from the package itself
+    script_dir = Path(__file__).parent.resolve()
+    if (script_dir / "pomera.py").exists():
+        return script_dir
+    
+    # Check npm global installation
+    npm_global = os.environ.get("APPDATA", "") or os.path.expanduser("~")
+    if platform.system() == "Windows":
+        npm_path = Path(npm_global) / "npm" / "node_modules" / "pomera-ai-commander"
+    else:
+        npm_path = Path(npm_global) / ".npm-global" / "lib" / "node_modules" / "pomera-ai-commander"
+        if not npm_path.exists():
+            npm_path = Path("/usr/local/lib/node_modules/pomera-ai-commander")
+        if not npm_path.exists():
+            npm_path = Path.home() / ".npm-packages" / "lib" / "node_modules" / "pomera-ai-commander"
+    
+    if npm_path.exists():
+        return npm_path
+    
+    return script_dir
+
+
+def get_desktop_path() -> Path:
+    """Get the user's desktop directory."""
+    if platform.system() == "Windows":
+        return Path(os.environ.get("USERPROFILE", "")) / "Desktop"
+    elif platform.system() == "Darwin":  # macOS
+        return Path.home() / "Desktop"
+    else:  # Linux
+        # Check XDG user dirs
+        xdg_desktop = os.environ.get("XDG_DESKTOP_DIR")
+        if xdg_desktop:
+            return Path(xdg_desktop)
+        return Path.home() / "Desktop"
+
+
+def create_windows_shortcut(package_dir: Path, desktop: Path) -> bool:
+    """Create Windows .lnk shortcut."""
+    try:
+        import subprocess
+        
+        shortcut_path = desktop / "Pomera AI Commander.lnk"
+        pomera_py = package_dir / "pomera.py"
+        icon_path = package_dir / "resources" / "icon.ico"
+        
+        # Use PowerShell to create shortcut
+        ps_script = f'''
+$WshShell = New-Object -ComObject WScript.Shell
+$Shortcut = $WshShell.CreateShortcut("{shortcut_path}")
+$Shortcut.TargetPath = "pythonw.exe"
+$Shortcut.Arguments = '"{pomera_py}"'
+$Shortcut.WorkingDirectory = "{package_dir}"
+$Shortcut.Description = "Pomera AI Commander - Text Processing Toolkit"
+'''
+        if icon_path.exists():
+            ps_script += f'$Shortcut.IconLocation = "{icon_path},0"\n'
+        
+        ps_script += '$Shortcut.Save()'
+        
+        result = subprocess.run(
+            ["powershell", "-Command", ps_script],
+            capture_output=True,
+            text=True
+        )
+        
+        if result.returncode == 0:
+            print(f"✓ Created Windows shortcut: {shortcut_path}")
+            return True
+        else:
+            print(f"✗ Failed to create shortcut: {result.stderr}")
+            return False
+            
+    except Exception as e:
+        print(f"✗ Error creating Windows shortcut: {e}")
+        return False
+
+
+def create_macos_shortcut(package_dir: Path, desktop: Path) -> bool:
+    """Create macOS .command script."""
+    try:
+        shortcut_path = desktop / "Pomera AI Commander.command"
+        pomera_py = package_dir / "pomera.py"
+        
+        script_content = f'''#!/bin/bash
+# Pomera AI Commander Launcher
+cd "{package_dir}"
+python3 "{pomera_py}"
+'''
+        
+        shortcut_path.write_text(script_content)
+        # Make executable
+        shortcut_path.chmod(shortcut_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        
+        print(f"✓ Created macOS launcher: {shortcut_path}")
+        return True
+        
+    except Exception as e:
+        print(f"✗ Error creating macOS shortcut: {e}")
+        return False
+
+
+def create_linux_shortcut(package_dir: Path, desktop: Path) -> bool:
+    """Create Linux .desktop launcher."""
+    try:
+        shortcut_path = desktop / "pomera-ai-commander.desktop"
+        pomera_py = package_dir / "pomera.py"
+        icon_path = package_dir / "resources" / "icon.png"
+        
+        # Use icon if exists, otherwise use generic
+        icon = str(icon_path) if icon_path.exists() else "utilities-terminal"
+        
+        desktop_entry = f'''[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Pomera AI Commander
+Comment=Text Processing Toolkit with MCP tools for AI assistants
+Exec=python3 "{pomera_py}"
+Icon={icon}
+Terminal=false
+Categories=Development;Utility;TextTools;
+StartupNotify=true
+'''
+        
+        shortcut_path.write_text(desktop_entry)
+        # Make executable
+        shortcut_path.chmod(shortcut_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        
+        print(f"✓ Created Linux launcher: {shortcut_path}")
+        
+        # Also try to add to applications menu
+        try:
+            apps_dir = Path.home() / ".local" / "share" / "applications"
+            apps_dir.mkdir(parents=True, exist_ok=True)
+            apps_shortcut = apps_dir / "pomera-ai-commander.desktop"
+            apps_shortcut.write_text(desktop_entry)
+            apps_shortcut.chmod(apps_shortcut.stat().st_mode | stat.S_IXUSR)
+            print(f"✓ Added to applications menu: {apps_shortcut}")
+        except Exception:
+            pass  # Not critical
+        
+        return True
+        
+    except Exception as e:
+        print(f"✗ Error creating Linux shortcut: {e}")
+        return False
+
+
+def create_shortcut():
+    """Create desktop shortcut for the current platform."""
+    print("\n🐕 Pomera AI Commander - Desktop Shortcut Creator")
+    print("=" * 50)
+    
+    package_dir = get_package_dir()
+    desktop = get_desktop_path()
+    
+    print(f"Package directory: {package_dir}")
+    print(f"Desktop directory: {desktop}")
+    
+    if not (package_dir / "pomera.py").exists():
+        print(f"✗ Error: pomera.py not found in {package_dir}")
+        return False
+    
+    if not desktop.exists():
+        print(f"✗ Error: Desktop directory not found: {desktop}")
+        return False
+    
+    system = platform.system()
+    print(f"Platform: {system}")
+    print("-" * 50)
+    
+    if system == "Windows":
+        return create_windows_shortcut(package_dir, desktop)
+    elif system == "Darwin":
+        return create_macos_shortcut(package_dir, desktop)
+    elif system == "Linux":
+        return create_linux_shortcut(package_dir, desktop)
+    else:
+        print(f"✗ Unsupported platform: {system}")
+        return False
+
+
+def remove_shortcut():
+    """Remove desktop shortcut for the current platform."""
+    print("\n🐕 Removing Pomera AI Commander shortcut...")
+    
+    desktop = get_desktop_path()
+    system = platform.system()
+    
+    shortcuts = []
+    if system == "Windows":
+        shortcuts.append(desktop / "Pomera AI Commander.lnk")
+    elif system == "Darwin":
+        shortcuts.append(desktop / "Pomera AI Commander.command")
+    elif system == "Linux":
+        shortcuts.append(desktop / "pomera-ai-commander.desktop")
+        shortcuts.append(Path.home() / ".local" / "share" / "applications" / "pomera-ai-commander.desktop")
+    
+    for shortcut in shortcuts:
+        if shortcut.exists():
+            try:
+                shortcut.unlink()
+                print(f"✓ Removed: {shortcut}")
+            except Exception as e:
+                print(f"✗ Failed to remove {shortcut}: {e}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "--remove":
+        remove_shortcut()
+    else:
+        success = create_shortcut()
+        if success:
+            print("\n✅ Desktop shortcut created successfully!")
+        else:
+            print("\n⚠️  Failed to create desktop shortcut")
+            sys.exit(1)

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "pomera-ai-commander",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Text processing toolkit with 22 MCP tools including case transformation, encoding, hashing, text analysis, and notes management for AI assistants.",
   "homepage": "https://github.com/matbanik/Pomera-AI-Commander",
   "repository": "https://github.com/matbanik/Pomera-AI-Commander",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pomera-ai-commander",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Text processing toolkit with 22 MCP tools for AI assistants - case transformation, encoding, hashing, text analysis, and notes management",
   "main": "pomera_mcp_server.py",
   "bin": {
@@ -50,8 +50,10 @@
     "core/",
     "tools/",
     "scripts/",
+    "resources/",
     "pomera_mcp_server.py",
     "pomera.py",
+    "create_shortcut.py",
     "migrate_data.py",
     "mcp.json",
     "README.md",

package/pomera.py

@@ -779,6 +779,9 @@ class PromeraAIApp(tk.Tk):
         
         self.title("Pomera AI Commander")
         self.geometry(AppConfig.DEFAULT_WINDOW_SIZE)
+        
+        # Set window icon (Pomera dog mascot)
+        self._set_window_icon()
 
         self._after_id = None
         self._regex_cache = {}
@@ -1201,7 +1204,7 @@ class PromeraAIApp(tk.Tk):
             pyproject_path = Path(__file__).parent / "pyproject.toml"
             if pyproject_path.exists():
                 content = pyproject_path.read_text()
-                match = re.search(r'version = "([^"]+)"', content)
+                match = re.search(r'version = "1.2.4"]+)"', content)
                 if match:
                     current_version = match.group(1)
         except Exception:
@@ -1212,7 +1215,7 @@ class PromeraAIApp(tk.Tk):
                 import importlib.metadata
                 current_version = importlib.metadata.version("pomera-ai-commander")
             except Exception:
-                current_version = "Unknown"
+                current_version = "1.2.4"
         
         # Detect OS for download link
         system = platform.system()
@@ -1350,11 +1353,8 @@ class PromeraAIApp(tk.Tk):
     
     def _show_about_dialog(self):
         """Show About dialog."""
-        try:
-            import importlib.metadata
-            version = importlib.metadata.version("pomera-ai-commander")
-        except Exception:
-            version = "1.2.0"
+        # Version managed by bump_version.py script
+        version = "1.2.4"
         
         messagebox.showinfo(
             "About Pomera AI Commander",
@@ -1362,6 +1362,42 @@ class PromeraAIApp(tk.Tk):
             "Text processing toolkit with MCP tools for AI assistants.\n\n"
             "https://github.com/matbanik/Pomera-AI-Commander"
         )
+    
+    def _set_window_icon(self):
+        """Set the window icon (Pomera dog mascot)."""
+        try:
+            # Find icon file - check multiple locations
+            script_dir = Path(__file__).parent.resolve()
+            icon_locations = [
+                script_dir / "resources" / "icon.ico",
+                script_dir / "icon.ico",
+                script_dir / "resources" / "icon.png",
+                script_dir / "icon.png",
+            ]
+            
+            icon_path = None
+            for loc in icon_locations:
+                if loc.exists():
+                    icon_path = loc
+                    break
+            
+            if icon_path is None:
+                return  # No icon found, use default
+            
+            if platform.system() == "Windows" and icon_path.suffix == ".ico":
+                # Windows: use iconbitmap for .ico files
+                self.iconbitmap(str(icon_path))
+            else:
+                # Other platforms or PNG: use PhotoImage
+                from PIL import Image, ImageTk
+                img = Image.open(icon_path)
+                # Resize to appropriate icon size - use NEAREST for sharp pixel art
+                img = img.resize((32, 32), Image.Resampling.NEAREST)
+                self._icon_photo = ImageTk.PhotoImage(img)
+                self.iconphoto(True, self._icon_photo)
+                
+        except Exception as e:
+            self.logger.debug(f"Could not set window icon: {e}")
 
     def _auto_save_settings(self):
         """Auto-save settings periodically (called by Task Scheduler)."""

package/pomera_mcp_server.py

@@ -70,7 +70,7 @@ def main():
     parser.add_argument(
         "--version",
         action="version",
-        version="pomera-mcp-server 1.2.2"
+        version="pomera-mcp-server 1.2.4"
     )
     parser.add_argument(
         "--list-tools",
@@ -160,7 +160,7 @@ def main():
     server = StdioMCPServer(
         tool_registry=registry,
         server_name="pomera-mcp-server",
-        server_version="1.2.2"
+        server_version="1.2.4"
     )
     
     logger.info("Starting Pomera MCP Server...")

package/scripts/postinstall.js

@@ -2,19 +2,23 @@
 /**
  * Pomera AI Commander - npm postinstall script
  * 
- * This script runs after npm install/update and checks for
- * databases in the package directory that might be at risk.
- * 
- * Displays a warning if portable mode data is detected.
+ * This script runs after npm install/update and:
+ * 1. Checks for databases in the package directory that might be at risk
+ * 2. Creates a desktop shortcut for easy access to the GUI
  */
 
 const fs = require('fs');
 const path = require('path');
+const { execSync, spawn } = require('child_process');
+const os = require('os');
 
 // Package root directory
 const packageDir = path.join(__dirname, '..');
 
-// Check for databases in package directory
+// ============================================================
+// Part 1: Database Warning Check
+// ============================================================
+
 const databases = ['settings.db', 'notes.db', 'settings.json'];
 const foundDatabases = [];
 
@@ -30,7 +34,6 @@ databases.forEach(db => {
     }
 });
 
-// If databases found in package directory, show warning
 if (foundDatabases.length > 0) {
     console.log('\n' + '='.repeat(70));
     console.log('⚠️  POMERA DATA WARNING ⚠️');
@@ -56,7 +59,163 @@ if (foundDatabases.length > 0) {
     }
     console.log('\n' + '='.repeat(70) + '\n');
 } else {
-    // No databases in package directory - safe configuration
     console.log('✅ Pomera AI Commander installed successfully.');
     console.log('   Data will be stored in platform-appropriate directory (safe from updates).');
 }
+
+// ============================================================
+// Part 2: Desktop Shortcut Creation
+// ============================================================
+
+function getDesktopPath() {
+    if (process.platform === 'win32') {
+        return path.join(os.homedir(), 'Desktop');
+    } else if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Desktop');
+    } else {
+        // Linux - check XDG
+        const xdgDesktop = process.env.XDG_DESKTOP_DIR;
+        if (xdgDesktop) return xdgDesktop;
+        return path.join(os.homedir(), 'Desktop');
+    }
+}
+
+function createWindowsShortcut() {
+    const desktop = getDesktopPath();
+    const shortcutPath = path.join(desktop, 'Pomera AI Commander.lnk');
+    const pomeraPath = path.join(packageDir, 'pomera.py');
+    const iconPath = path.join(packageDir, 'resources', 'icon.ico');
+
+    let psScript = `
+$WshShell = New-Object -ComObject WScript.Shell
+$Shortcut = $WshShell.CreateShortcut("${shortcutPath.replace(/\\/g, '\\\\')}")
+$Shortcut.TargetPath = "pythonw.exe"
+$Shortcut.Arguments = '"${pomeraPath.replace(/\\/g, '\\\\')}"'
+$Shortcut.WorkingDirectory = "${packageDir.replace(/\\/g, '\\\\')}"
+$Shortcut.Description = "Pomera AI Commander - Text Processing Toolkit"
+`;
+    if (fs.existsSync(iconPath)) {
+        psScript += `$Shortcut.IconLocation = "${iconPath.replace(/\\/g, '\\\\')},0"\n`;
+    }
+    psScript += '$Shortcut.Save()';
+
+    try {
+        execSync(`powershell -Command "${psScript.replace(/"/g, '\\"')}"`, { stdio: 'pipe' });
+        console.log(`\n🐕 Desktop shortcut created: ${shortcutPath}`);
+        return true;
+    } catch (e) {
+        console.log('\n⚠️  Could not create desktop shortcut automatically.');
+        console.log('   Run: python create_shortcut.py');
+        return false;
+    }
+}
+
+function createMacOSShortcut() {
+    const desktop = getDesktopPath();
+    const shortcutPath = path.join(desktop, 'Pomera AI Commander.command');
+    const pomeraPath = path.join(packageDir, 'pomera.py');
+
+    const script = `#!/bin/bash
+# Pomera AI Commander Launcher
+cd "${packageDir}"
+python3 "${pomeraPath}"
+`;
+
+    try {
+        fs.writeFileSync(shortcutPath, script);
+        fs.chmodSync(shortcutPath, 0o755);
+        console.log(`\n🐕 Desktop launcher created: ${shortcutPath}`);
+        return true;
+    } catch (e) {
+        console.log('\n⚠️  Could not create desktop shortcut automatically.');
+        return false;
+    }
+}
+
+function createLinuxShortcut() {
+    const desktop = getDesktopPath();
+    const shortcutPath = path.join(desktop, 'pomera-ai-commander.desktop');
+    const pomeraPath = path.join(packageDir, 'pomera.py');
+    const iconPath = path.join(packageDir, 'resources', 'icon.png');
+
+    const icon = fs.existsSync(iconPath) ? iconPath : 'utilities-terminal';
+
+    const desktopEntry = `[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Pomera AI Commander
+Comment=Text Processing Toolkit with MCP tools for AI assistants
+Exec=python3 "${pomeraPath}"
+Icon=${icon}
+Terminal=false
+Categories=Development;Utility;TextTools;
+StartupNotify=true
+`;
+
+    try {
+        fs.writeFileSync(shortcutPath, desktopEntry);
+        fs.chmodSync(shortcutPath, 0o755);
+        console.log(`\n🐕 Desktop launcher created: ${shortcutPath}`);
+
+        // Also add to applications menu
+        const appsDir = path.join(os.homedir(), '.local', 'share', 'applications');
+        if (!fs.existsSync(appsDir)) {
+            fs.mkdirSync(appsDir, { recursive: true });
+        }
+        const appsPath = path.join(appsDir, 'pomera-ai-commander.desktop');
+        fs.writeFileSync(appsPath, desktopEntry);
+        console.log(`   Also added to applications menu`);
+
+        return true;
+    } catch (e) {
+        console.log('\n⚠️  Could not create desktop shortcut automatically.');
+        return false;
+    }
+}
+
+function createDesktopShortcut() {
+    console.log('\n🐕 Creating desktop shortcut...');
+
+    const desktop = getDesktopPath();
+    if (!fs.existsSync(desktop)) {
+        console.log(`   Desktop directory not found: ${desktop}`);
+        return false;
+    }
+
+    if (process.platform === 'win32') {
+        return createWindowsShortcut();
+    } else if (process.platform === 'darwin') {
+        return createMacOSShortcut();
+    } else {
+        return createLinuxShortcut();
+    }
+}
+
+// Check if Python/pythonw is available before creating shortcut
+function checkPython() {
+    try {
+        if (process.platform === 'win32') {
+            execSync('where pythonw', { stdio: 'pipe' });
+        } else {
+            execSync('which python3', { stdio: 'pipe' });
+        }
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+// Create shortcut if Python is available
+if (checkPython()) {
+    createDesktopShortcut();
+} else {
+    console.log('\n⚠️  Python not found in PATH. Desktop shortcut not created.');
+    console.log('   Install Python and run: python create_shortcut.py');
+}
+
+console.log('\n📖 To start the GUI manually:');
+console.log('   python pomera.py');
+console.log('\n📖 To start the MCP server:');
+console.log('   npx pomera-ai-commander');
+console.log('');
+

package/tools/notes_widget.py

@@ -99,6 +99,33 @@ class NotesWidget:
             if conn:
                 conn.close()
     
+    def _sanitize_text(self, text: str) -> str:
+        """
+        Sanitize text by removing invalid UTF-8 surrogate characters.
+        
+        Lone surrogates (U+D800 to U+DFFF) are invalid in UTF-8 and cause
+        encoding errors when saving to the database. This can happen when
+        pasting content from the clipboard that contains malformed data.
+        
+        Args:
+            text: Input text that may contain invalid surrogates
+            
+        Returns:
+            Sanitized text safe for UTF-8 encoding and database storage
+        """
+        if not text:
+            return text
+        
+        try:
+            # This two-step process handles lone surrogates:
+            # 1. surrogatepass allows encoding surrogates (normally forbidden in UTF-8)
+            # 2. errors='replace' replaces invalid sequences with replacement char
+            sanitized = text.encode('utf-8', errors='surrogatepass').decode('utf-8', errors='replace')
+            return sanitized
+        except Exception:
+            # Fallback: manually filter out surrogate characters
+            return ''.join(c for c in text if not (0xD800 <= ord(c) <= 0xDFFF))
+    
     def init_database(self) -> None:
         """Initialize the SQLite database and Full-Text Search (FTS5) table."""
         try:
@@ -707,10 +734,12 @@ class NotesWidget:
                     row = conn.execute('SELECT * FROM notes WHERE id = ?', (self.current_item,)).fetchone()
                     if row:
                         now = datetime.now().isoformat()
+                        # Sanitize text to prevent UTF-8 surrogate errors
                         conn.execute('''
                             INSERT INTO notes (Created, Modified, Title, Input, Output)
                             VALUES (?, ?, ?, ?, ?)
-                        ''', (now, now, row['Title'], row['Input'], row['Output']))
+                        ''', (now, now, self._sanitize_text(row['Title']), 
+                              self._sanitize_text(row['Input']), self._sanitize_text(row['Output'])))
                         conn.commit()
                         self.perform_search(select_first=True)
                         self.logger.info(f"Duplicated note {self.current_item}")
@@ -788,9 +817,10 @@ class NotesWidget:
             return
         
         try:
-            title = self.title_entry.get() if hasattr(self, 'title_entry') else ""
-            input_content = self.input_display.get(1.0, tk.END).strip()
-            output_content = self.output_display.get(1.0, tk.END).strip()
+            # Sanitize text to prevent UTF-8 surrogate errors from clipboard paste
+            title = self._sanitize_text(self.title_entry.get() if hasattr(self, 'title_entry') else "")
+            input_content = self._sanitize_text(self.input_display.get(1.0, tk.END).strip())
+            output_content = self._sanitize_text(self.output_display.get(1.0, tk.END).strip())
             
             now = datetime.now().isoformat()
             
@@ -962,12 +992,17 @@ class NotesWidget:
             The ID of the created note, or None on error
         """
         try:
+            # Sanitize text to prevent UTF-8 surrogate errors
+            sanitized_title = self._sanitize_text(title)
+            sanitized_input = self._sanitize_text(input_content)
+            sanitized_output = self._sanitize_text(output_content)
+            
             now = datetime.now().isoformat()
             with self.get_db_connection() as conn:
                 cursor = conn.execute('''
                     INSERT INTO notes (Created, Modified, Title, Input, Output)
                     VALUES (?, ?, ?, ?, ?)
-                ''', (now, now, title, input_content, output_content))
+                ''', (now, now, sanitized_title, sanitized_input, sanitized_output))
                 note_id = cursor.lastrowid
                 conn.commit()